acq400_SOE.h

Go to the documentation of this file.

/** @file acq400_SOE.h
 * @brief acq400_SOE class implements SOE function
 *
 *  Created on: 23 Feb 2026
 *      Author: pgm
 */
 
/* provide an interface to the SOE_LUT and SOE_HOLD_TABLE  SOE_HLD
 * block on "new buffer"
 * copy new buffer to backing store (for PM)
 * wait for FMT
 * act on FMT.
 */
#ifndef XRMIOCAPP_SRC_ACQ400_SOE_H_
#define XRMIOCAPP_SRC_ACQ400_SOE_H_
 
#include "acq400_asyn_common.h"
#include "xrm_structs.h"
#include "acq400_FMT.h"
#include "SamplePrams.h"
 
#define PS_SOE_STRATEGY      "SOE_STRATEGY"        /* select LUT strategy 0,1.. */
 
#define PS_SOE_LUT_COL_ROWNUM    "SOE_LUT_COL_ROWNUM"  /* cosmetic for display, NOT part of FMT */
#define PS_SOE_LUT_COL_EVENT     "SOE_LUT_COL_EVENT"    /* asynInt16Array, ro */
#define PS_SOE_LUT_COL_PAD   "SOE_LUT_COL_PAD"  /* asynInt16Array, ro */
#define PS_SOE_LUT_COL_PV_ID     "SOE_LUT_COL_PV_ID"    /* asynInt32Array, ro */
#define PS_SOE_LUT_COL_OFFSET_US "SOE_LUT_COL_OFFSET_US" /* asynInt32Array, ro */
 
/* REDIT : Row EDIT */
#define PS_SOE_LUT_REDIT_ROW        "SOE_LUT_REDIT_ROW"     /* edit this row */
#define PS_SOE_LUT_REDIT_ROWCOUNT   "SOE_LUT_REDIT_ROWCOUNT"    /* for this many rows */
#define PS_SOE_LUT_REDIT_EVENT          "SOE_LUT_REDIT_EVENT"       /* set this event */
#define PS_SOE_LUT_REDIT_EVENT_STEP     "SOE_LUT_REDIT_EVENT_STEP"  /* adding to subsequent rows */
#define PS_SOE_LUT_REDIT_PV_ID          "SOE_LUT_REDIT_PV_ID"       /* set this event */
#define PS_SOE_LUT_REDIT_PV_ID_STEP     "SOE_LUT_REDIT_PV_ID_STEP"  /* adding to subsequent rows */
#define PS_SOE_LUT_REDIT_OFFSET_US  "SOE_LUT_REDIT_OFFSET_US"
#define PS_SOE_LUT_REDIT_OFFSET_US_STEP "SOE_LUT_REDIT_OFFSET_US_STEP"
 
#define PS_SOE_LUT_REDIT_COMMIT     "SOE_LUT_REDIT_COMMIT"
 
#define PS_SOE_HLD_COL_ROWNUM    "SOE_HLD_COL_ROWNUM"
#define PS_SOE_HLD_COL_EVT       "SOE_HLD_COL_EVT"
#define PS_SOE_HLD_COL_PV_ID     "SOE_HLD_COL_PV_ID"
#define PS_SOE_HLD_COL_OFFSET_US "SOE_HLD_COL_OFFSET_US"
#define PS_SOE_HLD_COL_CLIDAT    "SOE_HLD_COL_CLIDAT"
#define PS_SOE_HLD_COL_TS        "SOE_HLD_COL_TS"
#define PS_SOE_HLD_COL_DATA_OFFSET "SOE_HLD_COL_DATA_OFFSET"
 
#define PS_SOE_AGG_SITES    "SOE_AGG_SITES"
#define PS_SOE_SITE_SSB     "SOE_SITE_SSB" /* addr per site */
#define PS_SOE_SMPL_NSAM    "SOE_SMPL_NSAM"
#define PS_SOE_SITE_IS_ADC  "SOE_SITE_IS_ADC"  /* addr per site */
#define PS_SOE_SMPL_SS_U32  "SOE_SMPL_SS_U32"
#define PS_SOE_SMPL_AI_COUNT    "SOE_SMPL_AI_COUNT"
#define PS_SOE_SMPL_DI_COUNT    "SOE_SMPL_DI_COUNT"
#define PS_SOE_SMPL_SP_COUNT    "SOE_SMPL_SP_COUNT"
 
#define PS_SOE_SMPL_DI_INDEX    "SOE_SMPL_DI_INDEX"
#define PS_SOE_SMPL_SP_INDEX    "SOE_SMPL_SP_INDEX"
 
#define PS_SOE_KBUF_INDEX       "SOE_KBUF_INDEX"
#define PS_SOE_KBUF_WRT0        "SOE_KBUF_WRT0"
#define PS_SOE_KBUF_WRT1        "SOE_KBUF_WRT1"
 
/* 2 columns each data for show */
#define PS_SOE_HLD_COL_AI1  "SOE_HLD_COL_AI1"
#define PS_SOE_HLD_COL_AI2  "SOE_HLD_COL_AI2"
 
#define PS_SOE_HLD_COL_DI1  "SOE_HLD_COL_DI1"
#define PS_SOE_HLD_COL_DI2  "SOE_HLD_COL_DI2"
 
 
/* SP0 : SPAD0 aka Sample Number
 * SP1 : SPAD1 aka WR_VERNIER
 */
#define PS_SOE_HLD_COL_SP0  "SOE_HLD_COL_SP0"
#define PS_SOE_HLD_COL_SP1  "SOE_HLD_COL_SP1"
#define PS_SOE_HLD_COL_SP2  "SOE_HLD_COL_SP2"   // WRV
#define PS_SOE_HLD_COL_SP3  "SOE_HLD_COL_SP3"           // WRS Seconds Since EPOCH, SP3
#define PS_SOE_HLD_COL_WRVS "SOE_HLD_COL_WRVS"  // WR Vernier, seconds
#define PS_SOE_HLD_COL_WRVT     "SOE_HLD_COL_WRVT"  // WR Vernier, ticks
#define PS_SOE_HLD_COL_WRUS     "SOE_HLD_COL_WRUS"  // WR time, usec since epoch
 
 
 
/* define a column for each data type.git
 * There will be up to 64 of these by asyn "address"
 * BUT: this is NOT going to play well with a table
 * Really, one row per event again, 32 AI cols, 2DI, 2SP ..
 * @@todo !Think! Also, suck it and see..
 */
#define PS_SOE_HLD_DATA_COL_AI  "SOE_HLD_DATA_COL_AI"  // 64 records
#define PS_SOE_HLD_DATA_COL_DI  "SOE_HLD_DATA_COL_DI"
#define PS_SOE_HLD_DATA_COL_SP  "SOE_HLD_DATA_COL_SP"
 
#define PS_SOE_FMT_RX_TIMEOUTS  "SOE_FMT_RX_TIMEOUTS"
#define PS_SOE_FMT_RX_TIMEOUT_REASON    \
                "SOE_FMT_RX_TIMEOUT_REASON"
#define PS_SOE_FMT_DELTA_TS "SOE_FMT_DELTA_TS"
#define PS_SOE_FMT_RX_SUCCESS   "SOE_FMT_RX_SUCCESS"
#define PS_SOE_FMT_EV_MATCHES   "SOE_FMT_EV_MATCHES"
#define PS_SOE_FMT_EV_NIB   "SOE_FMT_EV_NOT_IN_BUFFER"
#define PS_SOE_FMT_BUF_POS  "SOE_FMT_BUF_POS"
#define PS_SOE_FMT_NEXT_RETRY   "SOE_FMT_NEXT_RETRY"
 
#define PS_SOE_HLD_TABLE_WF "SOE_HLD_TABLE_WF" // raw event table.
 
 
/** @brief KBUF "Kernel BUFfer"
 * On boot: KBUF's are preassigned for capture memory
 * Typical transient recorder: 128*4MB
 * A streaming capture cycles through the buffers.
 * When a buffer is filled, the buffer index is passed to clients.
 * acq400_SOE uses struct KBUF to model the buffer.
 */
struct KBUF {
    unsigned ib;        /**< kernel buffer index 0..N */
    epicsInt64 wrt0;    /**< WR timestamp at start.   */
    epicsInt64 wrt1;    /**< WR timestamp at end.     */
    const char* raw;    /**< PA of the raw data from DMA. */
};
 
struct SOE_DIMS {
    KBUF& kbuf;
    SamplePrams& samplePrams;
    SOE_LUT& lut;
};
 
/** singleton */
class acq400_SOE_Strategy {
 
public:
    enum ERR_CODES {
        SOE_SUCCESS = 0,
        E_TIMEOUT = -1,
        E_FMT_TS_TOO_EARLY_FOR_KB = -2,
        E_FMT_TS_TOO_LATE_FOR_KB = -3,
        E_FMT_NO_EVENTS_FOUND = -4,
        E_FMT_UNDEFINED = -99
    };
    enum FMT_NUM {
        FMT_PRE = -1,
        FMT_CUR = 0,
        FMT_WAIT = 1
    };
    struct RC {
        ERR_CODES status;
 
        long long delta_us;
        int ht_size32;
        short events_accepted;
        short events_not_in_buffer;
        FMT_NUM fmt_num;
        short next_retry;
    };
    /** implements strategy, .. waitFMT, compare LUT, look up data in raw and build output <ht> */
    virtual RC operator() (const SOE_DIMS& soe, SOE_HOLD_TABLE ht) = 0;
 
    static acq400_SOE_Strategy** factory();
 
 
};
 
 
class acq400_SOE: public acq400_asynPortDriver {
protected:
    static int verbose;
 
 
    SOE_LUT soe_lut;
    SOE_HOLD_HEADER* the_hold_table;   /**< preallocate the max possible size. do it once! */
 
    acq400_SOE_Strategy* strategy;
 
    /* TABLE representation for Phoebus */
    struct COLUMNS {
        epicsInt8  c_rownum[SOE_LUT_ROWS];
        epicsInt16 c_event[SOE_LUT_ROWS];
        epicsInt16 c_pad[SOE_LUT_ROWS];
        epicsInt32 c_pv_id[SOE_LUT_ROWS];
        epicsInt64 c_offset_us[SOE_LUT_ROWS];
    }cols;
 
    struct HOLD_COLS {
        epicsInt8    c_rownum[SOE_HLD_ROWS];
        epicsInt16   c_event[SOE_HLD_ROWS];
        epicsInt32   c_pv_id[SOE_HLD_ROWS];
        epicsInt32   c_offset_us[SOE_HLD_ROWS];
        epicsInt32  c_client_data[SOE_HLD_ROWS];
        epicsInt64  c_timestamp[SOE_HLD_ROWS];      // really U64 but..
        epicsFloat32 c_AI1[SOE_HLD_ROWS];
        epicsFloat32 c_AI2[SOE_HLD_ROWS];
        epicsInt32  c_DI1[SOE_HLD_ROWS];       // really U32, but we only have doCallbacksInt32Array()
        epicsInt32  c_DI2[SOE_HLD_ROWS];
        epicsInt32  c_SP0[SOE_HLD_ROWS];
        epicsInt32  c_SP1[SOE_HLD_ROWS];
        epicsInt32  c_SP2[SOE_HLD_ROWS];
        epicsInt32  c_SP3[SOE_HLD_ROWS];
        epicsInt8   c_WRVS[SOE_HLD_ROWS];
        epicsInt32  c_WRVT[SOE_HLD_ROWS];
        epicsInt64  c_WRUS[SOE_HLD_ROWS];
    } hold_cols;
    unsigned fmt_rx_timeouts;
    unsigned fmt_rx_success;
    int hold_row_limit;
    static int nice;
 
    SamplePrams samplePrams;
    void get_sample_dimensions();
    void init_the_hold_table();
 
    void redit();
    virtual void update_soe_lut(bool first_time = false);
    virtual void update_soe_lut_columns(void);
    virtual void update_soe_lut_callbacks(bool call_array_callbacks);
 
    virtual void update_hld_tab_columns(void);
    virtual void update_hld_tab_callbacks(int n_u32);
    virtual void update_hld_tab_columns_callbacks(void);
 
    struct KBUF current_kb;
    inline char* get_raw();
    void update_kbuf_info(char* raw);
 
    virtual void task();
 
    static void task_runner(void *drvPvt);
 
    int P_SOE_STRATEGY;     /**< STRATEGY: LutFmtStrategy1 or NullStrategy (used initial test). */
 
    int P_SOE_LUT_COL_ROWNUM;   /**< LUT view show ROWNUM (synthetic)   */
    int P_SOE_LUT_COL_EVENT;    /**< LUT view show EVENT        */
    int P_SOE_LUT_COL_PAD;      /**< LUT view show PAD          */
    int P_SOE_LUT_COL_PV_ID;    /**< LUT view show PV_ID        */
    int P_SOE_LUT_COL_OFFSET_US;    /**< LUT view show OFFSET_US        */
 
    int P_SOE_LUT_REDIT_ROW;    /**< Row Edit define first row      */
    int P_SOE_LUT_REDIT_ROWCOUNT;   /**< Row Edit number of rows to edit    */
    int P_SOE_LUT_REDIT_EVENT;  /**< Row Edit set EVENT for first row   */
    int P_SOE_LUT_REDIT_EVENT_STEP; /**< Row Edit def series of EVENTs  */
    int P_SOE_LUT_REDIT_PV_ID;  /**< Row Edit set first PV ID           */
    int P_SOE_LUT_REDIT_PV_ID_STEP; /**< Row Edit def series of PV_IDS's    */
    int P_SOE_LUT_REDIT_OFFSET_US;  /**< Row Edit first OFFSET_US           */
    int P_SOE_LUT_REDIT_OFFSET_US_STEP; /**< Row edit def series of offsets */
 
    int P_SOE_LUT_REDIT_COMMIT; /**< Row Edit: action the new definition */
 
 
 
    int P_SOE_AGG_SITES;        /**< Geometry: aggregator site list     */
    int P_SOE_SITE_SSB;     /**< Geometry: Sample Size Bytes    */
    int P_SOE_SMPL_SS_U32;      /**< Geometry: Sample Size U32      */
 
    int P_SOE_SMPL_NSAM;        /**< Geometry: Number of Samples in Burst*/
    int P_SOE_SITE_IS_ADC;      /**< Geometry: First ADC site       */
 
    int P_SOE_SMPL_AI_COUNT;    /**< Geometry: number of AI16 columns in data */
    int P_SOE_SMPL_DI_COUNT;    /**< Geometry: number of DI32 columns in data */
    int P_SOE_SMPL_SP_COUNT;    /**< Geometry: number of SP32 columns in data */
    int P_SOE_SMPL_DI_INDEX;    /**< Geometry: index of first DI word */
    int P_SOE_SMPL_SP_INDEX;    /**< Geometry: index of first SP word */
 
    int P_SOE_HLD_COL_ROWNUM;   /**< HLD view show ROWNUM (synthetic)   */
    int P_SOE_HLD_COL_EVT;      /**< HLD view show EVT (from LUT)   */
    int P_SOE_HLD_COL_PV_ID;    /**< HLD view show PV_ID        */
    int P_SOE_HLD_COL_OFFSET_US;    /**< HLD view show offset us (from LUT) */
    int P_SOE_HLD_COL_CLIDAT;   /**< HLD view show CLIDAT       */
    int P_SOE_HLD_COL_TS;       /**< HLD view show TimeStamp        */
    int P_SOE_HLD_COL_DATA_OFFSET;  /**< HLD view show offset to data in HLD TABLE */
 
    int P_SOE_HLD_COL_AI1;      /**< HLD view speciment AI#1 (we can't slice them all) */
    int P_SOE_HLD_COL_AI2;      /**< HLD view speciment AI#2 (we can't slice them all) */
 
    int P_SOE_HLD_COL_DI1;      /**< HLD view DI32#1 */
    int P_SOE_HLD_COL_DI2;      /**< HLD view DI32#2 */
 
    int P_SOE_HLD_COL_SP0;      /**< HLD view SPAD[0] (Sample Number)       */
    int P_SOE_HLD_COL_SP1;      /**< HLD view SPAD[1] (usec since trigger)  */
    int P_SOE_HLD_COL_SP2;      /**< HLD view SPAD[2] (WR Vernier)      */
    int P_SOE_HLD_COL_SP3;      /**< HLD view SPAD[3] (WR seconds since EPOCH)  */
    int P_SOE_HLD_COL_WRVS;     /**< HLD view WR Vernier Seconds (f(SPAD[2])    */
    int P_SOE_HLD_COL_WRVT;     /**< HLD view WR Vernier Ticks (f(SPAD[2])  */
    int P_SOE_HLD_COL_WRUS;         /**< HLD view WR Time usec since epich (calculated) */
 
    int P_SOE_KBUF_INDEX;       /**< Current KBUF number */
    int P_SOE_KBUF_WRT0;        /**< Current KBUF start time */
    int P_SOE_KBUF_WRT1;        /**< Current KBUF end time */
 
    int P_SOE_FMT_RX_TIMEOUTS;  /**< Stat: Receive Timeouts */
    int P_SOE_FMT_RX_TIMEOUT_REASON;/**< Stat: Receive Timeout Reason */
    int P_SOE_FMT_DELTA_TS;     /**< Stat: Delta TS: time between FMT and latest KBUF */
    int P_SOE_FMT_RX_SUCCESS;   /**< Stat: count timely received buffers */
    int P_SOE_FMT_EV_MATCHES;   /**< Stat: count buffers with matching events */
    int P_SOE_FMT_EV_NIB;       /**< Stat: count buffers with events NOT IN BUFFER */
    int P_SOE_FMT_BUF_POS;      /**< Stat: buffer position: -1:PREV, 0:CUR, 1:NEXT */
    int P_SOE_FMT_NEXT_RETRY;   /**< Stat: if next, number of retrys */
    int P_SOE_HLD_TABLE_WF;     /**< HLD Table full binary output for remote clients */
 
    int ib;         /** ib is physical buffer contains bpb vpb's */
    acq400_SOE(const char *portName, acq400_SOE_Strategy* strategy);
 
    static acq400_SOE* _instance;
public:
    static void create_instance(const char *portName, acq400_SOE_Strategy* strategy);
    virtual ~acq400_SOE() {}
 
    void clearHold();
 
    virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
 
    static const int CYCLE_MS;
};
 
#endif /* XRMIOCAPP_SRC_ACQ400_SOE_H_ */