FIPCAPTURE Library : User’s Guide

int fipcap_init()

void fipcap_exit()

const struct fipcap_version *fipcap_version_get()

int main(int argc, char *argv[])
{
    const struct fipcap_version *lib_version;

    fipcap_init();

    /* fipcap - get lib version */
    lib_version = fipcap_version_get();

    printf("fipcap lib: v%d.%d.%d [build date: %02d/%02d/%02d]\n",
        lib_version->info.major,
        lib_version->info.minor,
        lib_version->info.patch,
        lib_version->date.info.month,
        lib_version->date.info.day,
        lib_version->date.info.year);

    fipcap_exit();

    return 0;
}

int fipcap_error_get()

const char *fipcap_strerror(int err)

int fipcap_device_list_get(struct fw_dev_infos *dev_infos, int *dev_cnt)

struct fipcap_dev *fipcap_device_open(uint8_t dev_id)

int fipcap_device_reset(struct fipcap_dev *dev)

int fipcap_device_close(struct fipcap_dev *dev)

int fipcap_device_infos_get(struct fipcap_dev *dev, struct fw_dev_infos *info)

struct fipcap_sess *fipcap_sess_init(struct fipcap_sess_cfg *cfg)

void usr_rst_handler(struct fipcap_sess *sess)
{
    /* calling the reset function for a pci/pcie device */
    if (fipcap_device_reset(sess->infos->cfg.dev)) {
        printf("reset failed: %s\n", fipcap_strerror(errno));
        return;
    }
    _print(src, evt, "reset coprocessor component (fipwatcher) done\n");
}

void usr_err_handler(struct fipcap_sess *sess,
        enum fipcap_error_code code)
{
    printf("error_handler: %s (err_code=%d)\n",
        fipcap_strerror(code), code);
}

int main(int argc, char *argv[])
{
    int err = 0;
    struct fipcap_dev *dev;
    struct fipcap_sess *sess;
    struct fipcap_sess_cfg cfg;

    /* fipcap lib initialization [mandatory] */
    if (fipcap_init()) {
        printf("cannot init fipcap library: %s\n",
            fipcap_strerror(errno));
        return -1;
    }

    /* open a pci/pcie device (1st index) */
    dev = fipcap_device_open(1);
    if (!dev) {
        printf("cannot open device: %s\n",
            fipcap_strerror(errno));
        fipcap_exit();
        return -1;
    }

    /**
     * Session initialization:
     * Minimal set-up for a PCI/PCIe fipwatcher device
     */
    cfg.dev = dev; /* coprocessor attachment: pci/pcie device to bind */
    cfg.fipcap_error_handler = usr_err_handler; /* local handler to notify
                                                   the internal errors of
                                                   the library */
    cfg.fipcap_reset_handler = usr_rst_handler; /* local handler to reset
                                                   the bound device */

    sess = fipcap_sess_init(&cfg);
    if (!sess) {
        printf("sesion initialization failed: %s\n",
            fipcap_strerror(errno));
        err = -1;
        goto end;
    }

    /**
     * Other tasks
     */
    /* ... */

end:
    /**
     * Session exit
     */
    /*...*/

    /* close device */
    fipcap_device_close(dev);

    /* fipcap lib exit [mandatory] */
    fipcap_exit();
    return err;
}

int fipcap_sess_exit(struct fipcap_sess *sess)

int fipcap_sess_report_get(struct fipcap_sess *sess,
        struct fipcap_sess_report *report)

int main(int argc, char *argv[])
{
    int err = 0;
    struct fipcap_sess *sess;
    struct fipcap_sess_report rep; /* full report */

    /**
     * Session initialization
     */
    /*...*/

    /**
     * Session startup
     */
    /*...*/

    /* get capture report */
    err = fipcap_sess_report_get(sess, &rep);
    if (err) {
        printf("capture report getter failed: %s\n", fipcap_strerror(errno));
        goto end;
    }

    printf("  CAPTURED FRAMES    : TOTAL=%d\n", rep.stats.frm.total);
    printf("    id_dat           : %d\n", rep.stats.frm.id_dat);
    printf("    id_msg           : %d\n", rep.stats.frm.id_msg);
    printf("    id_rq1           : %d\n", rep.stats.frm.id_rq1);
    printf("    id_rq2           : %d\n", rep.stats.frm.id_rq2);
    printf("    rp_dat           : %d\n", rep.stats.frm.rp_dat);
    printf("    rp_dat_msg       : %d\n", rep.stats.frm.rp_dat_msg);
    printf("    rp_dat_rq1       : %d\n", rep.stats.frm.rp_dat_rq1);
    printf("    rp_dat_rq2       : %d\n", rep.stats.frm.rp_dat_rq2);
    printf("    rp_dat_rq1_msg   : %d\n", rep.stats.frm.rp_dat_rq1_msg);
    printf("    rp_dat_rq2_msg   : %d\n", rep.stats.frm.rp_dat_rq2_msg);
    printf("    rp_rq1           : %d\n", rep.stats.frm.rp_rq1);
    printf("    rp_rq2           : %d\n", rep.stats.frm.rp_rq2);
    printf("    rp_msg_noack     : %d\n", rep.stats.frm.rp_msg_noack);
    printf("    rp_msg_ack_even  : %d\n", rep.stats.frm.rp_msg_ack_even);
    printf("    rp_msg_ack_odd   : %d\n", rep.stats.frm.rp_msg_ack_odd);
    printf("    rp_ack_even_p    : %d\n", rep.stats.frm.rp_ack_even_p);
    printf("    rp_ack_odd_p     : %d\n", rep.stats.frm.rp_ack_odd_p);
    printf("    rp_ack_even_m    : %d\n", rep.stats.frm.rp_ack_even_m);
    printf("    rp_ack_odd_m     : %d\n", rep.stats.frm.rp_ack_odd_m);
    printf("    rp_fin           : %d\n", rep.stats.frm.rp_fin);
    printf("    padding          : %d\n\n", rep.stats.frm.padding);
    printf("  ERRORS DETECTED    : TOTAL=%d\n", rep.stats.frm_err.total);
    printf("    ** physical layer errors\n");
    printf("    pre_mis          : %d\n", rep.stats.frm_err.pre_mis);
    printf("    fsd_mis          : %d\n", rep.stats.frm_err.fsd_mis);
    printf("    fsd_unk          : %d\n", rep.stats.frm_err.fsd_unk);
    printf("    fed_mis          : %d\n", rep.stats.frm_err.fed_mis);
    printf("    ** data-link layer errors\n");
    printf("    ctl_unk          : %d\n", rep.stats.frm_err.ctl_unk);
    printf("    fcs_bad          : %d\n", rep.stats.frm_err.fcs_bad);
    printf("    ** application layer errors\n");
    printf("    pdu_bad          : %d\n", rep.stats.frm_err.pdu_bad);
    printf("    len_bad          : %d\n", rep.stats.frm_err.len_bad);
    printf("    ** library errors\n");
    printf("    idx_loss         : %d\n", rep.stats.frm_err.idx_loss);

    /**
     * Other tasks
     */
    /* ... */

end:
    /**
     * Session exit
     */
    /*...*/
    return err;
}

int fipcap_sess_stats_clear(struct fipcap_sess *sess)

int fipcap_sess_start(struct fipcap_sess *sess)

int fipcap_sess_stop(struct fipcap_sess *sess)

struct fipcap_date {
    union {
        uint32_t raw;
        struct {
            uint8_t day;
            uint8_t month;
            uint8_t year;
            uint8_t reserved;
        } info;
    };
};

struct fipcap_version {
    union {
        uint32_t raw;
        struct {
            uint8_t patch;
            uint8_t minor;
            uint8_t major;
            uint8_t reserved;
        } info;
    };
    /* build date */
    struct fipcap_date date;
};

struct fw_dev_infos {
    uint32_t    index;
    uint32_t    sn;
    /* device general info */
    uint16_t    vid;
    uint16_t    did;
    uint16_t    ssvid;
    uint16_t    ssdid;
    /* physical BAR addresses */
    int         bar_cnt;
    uint64_t    bar_bsz[BAR_MAX];
    uint64_t    bar_base[BAR_MAX];
    /* irq infos*/
    int         irq_number;
    /* driver infos */
    uint32_t    drv_version;
    uint32_t    drv_date;
    /* fip infos */
    int         fip_bitrate;
};

struct fipcap_sess_cfg {
    /**
     * General FIP settings
     */
    uint16_t padding;
    /**
     * Hardware access
     */
    struct fipcap_dev *dev;
    unsigned long dpm_base_addr;
    /**
     * General Handlers
     */
    void *user_ctx;
    void (* fipcap_frm_handler)(struct fipcap_sess *sess,
                struct fipcap_frm *frm);
    void (* fipcap_diag_handler)(struct fipcap_sess *sess,
                struct fipcap_sess_report *report);
    void (* fipcap_error_handler)(struct fipcap_sess *sess,
                enum fipcap_error_code error);
    void (* fipcap_reset_handler)(struct fipcap_sess *sess);
};

struct fipcap_frm_msg_addr {
    union {
        uint32_t addr;
        struct {
            union {
                uint8_t seg;
                struct {
                    uint8_t seg_num:7;
                    uint8_t seg_group:1;
                };
            };
            union {
                uint16_t lsap;
                struct {
                    uint16_t lsap_num:15;
                    uint16_t lsap_group:1;
                };
            };
            uint8_t reserved;
        };
    };
};

struct fipcap_frm_msg_hdr {
    struct fipcap_frm_msg_addr src;
    struct fipcap_frm_msg_addr dst;
};

struct fipcap_frm_msg {
    struct fipcap_frm_msg_hdr hdr;
    uint16_t payload_bsz;
    uint8_t *payload;
};

struct fipcap_frm_usrdata {
    enum fipcap_frm_usrdata_type type;
    union {
        struct fipcap_frm_var var;
        struct fipcap_frm_var_list var_list;
        struct fipcap_frm_msg msg;
    };
};

struct fipcap_frm_var_list {
    uint32_t reserved[2];
    uint16_t ids_cnt;
    uint16_t *ids;
};

struct fipcap_frm_var {
    uint8_t reserved[7];
    uint8_t pdu;
    uint16_t payload_bsz;
    uint8_t *payload;
};

struct fipcap_frm {
    uint64_t idx;
    struct {
        uint64_t epoch;
        uint32_t frame_nstime;
        uint32_t interframe_nstime;
    } time_info;
    uint8_t error;
    uint16_t raw_bsz;
    uint8_t *raw;
    /* dissected frame */
    uint8_t ctrl;
    uint16_t id;
    uint16_t fcs;
    struct fipcap_frm_usrdata usrdata;
};

struct fipcap_ba_aper_wind {
    uint32_t end_ustime;
};

#define _FIPCAP_BA_WIND_REQ_CNT_MAX 1000

struct fipcap_ba_per_wind {
    int req_cnt;
    struct fipcap_ba_req req_list[_FIPCAP_BA_WIND_REQ_CNT_MAX];
};

#define _FIPCAP_BA_WIND_CNT_MAX 50

struct fipcap_ba_mcycle {
    int wind_cnt;
    struct fipcap_ba_wind wind_list[_FIPCAP_BA_WIND_CNT_MAX];
    uint32_t duration_ustime;
};

struct fipcap_ba_req {
    uint16_t type;
    uint16_t id;
};

struct fipcap_ba_wind {
    int type;
    union {
        struct fipcap_ba_per_wind per;
        struct fipcap_ba_aper_wind aper;
    };
};

struct fipcap_sess_ba_info {
    uint8_t addr;
    uint8_t mcycle_idx;
    struct fipcap_ba_mcycle mcycle;
};

struct fipcap_sess_infos {
    struct fipcap_sess_cfg cfg;
    uint32_t sn;
    struct fipcap_version drv_version;
    struct fipcap_version lib_version;
};

struct fipcap_sess_node_info {
    /**
     * Presence infos
     */
    int is_present;
    uint64_t last_pres_epoch;
    uint64_t last_abs_epoch;
    int absence_cnt;
    int ba_status;
    int ba_prio;
    /**
     * Identification
     */
    char manufacturer_name[128];
    char model_name[128];
    uint8_t revision;
    char tag_name[128];
    uint8_t smmps_class;
    char vendor_field[128];
    /**
     * Report
     */
    uint16_t rx_ok_ch1;
    uint16_t rx_ok_ch2;
    uint16_t rx_nok_ch1;
    uint16_t rx_nok_ch2;
    union channel_status {
        uint16_t value;
        struct {
            uint16_t tx_quality_ch1:1;
            uint16_t tx_quality_ch2:1;
            uint16_t rx_quality_ch1:1;
            uint16_t rx_quality_ch2:1;
            uint16_t valid_ch1:1;
            uint16_t valid_ch2:1;
            uint16_t traffic_ch1:1;
            uint16_t traffic_ch2:1;
            uint16_t summary_ch1:1;
            uint16_t summary_ch2:1;
            uint16_t reserved:6;
        };
    } channel_status;
};

#define _FIPCAP_NODE_CNT_MAX 256

struct fipcap_sess_report {
    struct fipcap_sess_status status;
    struct fipcap_sess_stats stats;
    struct fipcap_sess_node_info node[_FIPCAP_NODE_CNT_MAX];
    struct fipcap_sess_ba_info ba;
};

struct fipcap_sess_stats {

    /* frame counters */
    struct {
        uint64_t total;
        uint64_t id_dat;
        uint64_t id_msg;
        uint64_t id_rq1;
        uint64_t id_rq2;
        uint64_t rp_dat;
        uint64_t rp_dat_msg;
        uint64_t rp_dat_rq1;
        uint64_t rp_dat_rq2;
        uint64_t rp_dat_rq1_msg;
        uint64_t rp_dat_rq2_msg;
        uint64_t rp_rq1;
        uint64_t rp_rq2;
        uint64_t rp_msg_noack;
        uint64_t rp_msg_ack_even;
        uint64_t rp_msg_ack_odd;
        uint64_t rp_ack_even_p;
        uint64_t rp_ack_odd_p;
        uint64_t rp_ack_even_m;
        uint64_t rp_ack_odd_m;
        uint64_t rp_fin;
        uint64_t padding;
    } frm;

    /* frame error counters */
    struct {
        uint64_t total;
        /* -> Physical Layer errors */
        uint64_t pre_mis;
        uint64_t fsd_mis;
        uint64_t fsd_unk;
        uint64_t fed_mis;
        /* -> Data-Link Layer errors */
        uint64_t ctl_unk;
        uint64_t fcs_bad;
        /* -> Application Layer errors */
        uint64_t pdu_bad;
        uint64_t len_bad;
        /* -> Library errors */
        uint64_t idx_loss;
    } frm_err;
};

struct fipcap_sess_status {
    uint16_t state;
    /* network information */
    uint8_t frm_type;
    uint8_t frm_bitrate;
    /* capturing time */
    uint64_t start_epoch;
    uint64_t stop_epoch;
    uint64_t duration_us;
    /* fip time */
    uint32_t turn_around_ustime;
    uint32_t silence_ustime;
};

struct fipcap_sess {
    struct fipcap_sess_infos *infos;
    void *priv;
};