kst_session.h

Go to the documentation of this file.

 
#ifndef KST_SESSION_H
#define KST_SESSION_H
 
#include <stdbool.h>
#include <stdint.h>
 
#include "kst_plan.h"
#include "kst_reg.h"
#include "kst_wire.h"
 
#ifdef __cplusplus
extern "C" {
#endif

#define KST_ENTRY_LOW_US 100000u
#define KST_GAP_US 3000u
#define KST_GAP_AFTER_FAULT_US 20000u
#define KST_DRIVER_SLACK_US 5000u

#define KST_READ_PASSES     3u
#define KST_READ_PASSES_MAX 5u
#define KST_READ_EQUAL 3u
#define KST_WRITE_ATTEMPTS 3u

typedef struct {
    void *ctx;              
    bool (*start)(void *ctx, const kst_frame_t *frame, uint32_t window_ns);
    bool (*poll)(void *ctx, kst_capture_t *out);
    uint32_t (*now_us)(void *ctx);  
} kst_driver_t;

typedef enum {
    KST_SES_OK = 0,            
    KST_SES_BUSY,              
    KST_SES_ERR_BUSY,          
    KST_SES_ERR_ARG,           
    KST_SES_ERR_NO_SERVO,      
    KST_SES_ERR_NOT_IN_MODE,   
    KST_SES_ERR_READ,          
    KST_SES_ERR_NO_BACKUP,     
    KST_SES_ERR_FINGERPRINT,   
    KST_SES_ERR_LOCKED,        
    KST_SES_ERR_BAD_PLAN,      
    KST_SES_ERR_UNCONFIRMED,   
    KST_SES_ERR_CHANGED,       
    KST_SES_ERR_WRITE_FAILED,  
    KST_SES_ERR_ROLLED_BACK,   
    KST_SES_ERR_TORN,          
    KST_SES_ERR_UNINTENDED,    
    KST_SES_ERR_VERIFY,        
    KST_SES_ERR_DRIVER,        
    KST_SES_ERR_ABORTED,       
    KST_SES_ERR_NO_PLAN,       
} kst_ses_t;

typedef struct {
    uint32_t replies;        
    uint32_t faults;         
    uint32_t delay_min_ns;   
    uint32_t delay_max_ns;   
    uint32_t half_min_ns;    
    uint32_t half_max_ns;    
} kst_stats_t;

typedef struct {
    /* --- for the caller to read ------------------------------------------- */
    kst_image_t image;       
    kst_image_t backup;      
    kst_fingerprint_t fingerprint;  
    kst_stats_t stats;
    kst_reply_t last_reply;  
    uint32_t bad_regs;       
    uint32_t wrote_regs;     
    uint32_t diff_regs;      
    uint8_t result;          
    uint8_t in_mode;         
    uint8_t has_image;       
    uint8_t has_backup;      
    uint8_t fingerprint_ok;  
    uint8_t locked;          
    uint8_t step_index;      
    uint8_t planning;        
    uint8_t plan_result;     
    kst_rules_t plan_rules;  
    uint32_t plan_cap;       
 
    /* --- private ----------------------------------------------------------- */
    kst_driver_t drv;
    kst_plan_t plan;         
    kst_plan_job_t job;      
    kst_image_t expect;      
    kst_image_t read;        
    kst_frame_t frame;
    uint8_t vals[KST_READ_PASSES_MAX][KST_REG_COUNT];
    uint32_t vals_ok[KST_READ_PASSES_MAX];
    uint32_t t_mark;         
    uint32_t t_gap;          
    uint32_t t_start;
    uint32_t t_limit;
    int16_t undo;            
    int16_t undo_stop;
    uint8_t op;
    uint8_t phase;
    uint8_t t_state;
    uint8_t t_expect;
    uint8_t t_frame;
    uint8_t t_reg;           
    uint8_t fault;
    uint8_t abort;
    uint8_t reading;
    uint8_t read_result;
    uint8_t pass;
    uint8_t passes;
    uint8_t reg;
    uint8_t attempt;
    uint8_t first_ok;
    uint8_t dirty;
    uint8_t unseen;          /* a write ended with the servo not read */
    uint8_t cycled;          /* the supply was off under the running
                                operation */
    uint8_t undone;
    uint8_t confirm;         
} kst_session_t;

bool kst_session_init(kst_session_t *s, const kst_driver_t *driver);

kst_ses_t kst_session_enter(kst_session_t *s);

kst_ses_t kst_session_read_all(kst_session_t *s);

kst_ses_t kst_session_edit(kst_session_t *s, const kst_image_t *target,
                           kst_field_set_t unlocked);

kst_ses_t kst_session_restore(kst_session_t *s, bool confirm_unchecked);

kst_ses_t kst_session_release_pairing(kst_session_t *s);

const kst_plan_t *kst_session_plan(const kst_session_t *s);

kst_ses_t kst_session_write(kst_session_t *s, const kst_plan_t *plan,
                            bool confirm_unchecked);

kst_ses_t kst_session_verify(kst_session_t *s, const kst_image_t *expected);

kst_ses_t kst_session_step(kst_session_t *s);

void kst_session_abort(kst_session_t *s);

void kst_session_power_cycled(kst_session_t *s);
 
#ifdef __cplusplus
}
#endif
 
#endif /* KST_SESSION_H */