include/grlib/grtc.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /* GRTC Telecommand (TC) decoder driver interface
0004  *
0005  * COPYRIGHT (c) 2007.
0006  * Cobham Gaisler AB.
0007  *
0008  * Redistribution and use in source and binary forms, with or without
0009  * modification, are permitted provided that the following conditions
0010  * are met:
0011  * 1. Redistributions of source code must retain the above copyright
0012  *    notice, this list of conditions and the following disclaimer.
0013  * 2. Redistributions in binary form must reproduce the above copyright
0014  *    notice, this list of conditions and the following disclaimer in the
0015  *    documentation and/or other materials provided with the distribution.
0016  *
0017  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0018  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0020  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0021  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0022  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0023  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0026  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0027  * POSSIBILITY OF SUCH DAMAGE.
0028  */
0029
0030 #ifndef __GRTC_H__
0031 #define __GRTC_H__
0032
0033 #ifdef __cplusplus
0034 extern "C" {
0035 #endif
0036
0037 #define GRTC_IOC_UNUSED         0
0038
0039 /* Driver operation controlling commands */
0040 #define GRTC_IOC_START          1
0041 #define GRTC_IOC_STOP           2
0042 #define GRTC_IOC_ISSTARTED      3
0043 #define GRTC_IOC_SET_BLOCKING_MODE  4   /* Raw mode only */
0044 #define GRTC_IOC_SET_TIMEOUT        5   /* Raw mode only */
0045
0046 #define GRTC_IOC_ADD_BUFF       16  /* Frame mode only */
0047 #define GRTC_IOC_RECV           17  /* Frame mode only */
0048
0049 /* Available only in STOPPED mode */
0050 #define GRTC_IOC_SET_MODE       32  /* Set frame mode (ioctl) or raw mode (read) */
0051 #define GRTC_IOC_SET_BUF_PARAM      33
0052 #define GRTC_IOC_SET_CONFIG     34
0053 #define GRTC_IOC_POOLS_SETUP        35  /* Frame mode only */
0054
0055 /* Available in both running and stopped mode */
0056 #define GRTC_IOC_GET_CONFIG     64
0057 #define GRTC_IOC_GET_BUF_PARAM      65
0058 #define GRTC_IOC_GET_HW_STATUS      66
0059 #define GRTC_IOC_ASSIGN_FRM_POOL    67
0060 #define GRTC_IOC_GET_CLCW_ADR       68  /* Get address of CLCWRx1 */
0061 #define GRTC_IOC_GET_STATS      69  /* Get statistics, note that most of the stats are only avilable in FRAME mode */
0062 #define GRTC_IOC_CLR_STATS      70  /* Clear statistics */
0063
0064 /* Available only in RUNNING mode */
0065
0066 /* Args to GRTC_IOC_GET_BUF_PARAMS */
0067 #define GRTC_BUF_MAXLEN (0x100*1024)
0068 #define GRTC_BUF_MASK 0xfffffc00
0069 struct grtc_ioc_buf_params {
0070     unsigned int    length;     /* Length of new buffer in multiples of 1kbyte blocks */
0071     void        *custom_buffer; /* If set zero driver will allocate with malloc, set LSB to 1 to indicate remote address */
0072 };
0073
0074 /* Args to GRTC_IOC_SET_BLOCKING_MODE */
0075 enum {
0076     GRTC_BLKMODE_POLL   = 0,    /* Never block (polling mode) */
0077     GRTC_BLKMODE_BLK    = 1,    /* Block until at least 1 byte can be read */
0078     GRTC_BLKMODE_COMPLETE   = 2 /* Block until all data requested has be read */
0079 };
0080
0081 /* Argument of GRTC_IOC_SET_CONFIG and GRTC_IOC_GET_CONFIG
0082  * Pointer to:
0083  */
0084 struct grtc_ioc_config {
0085     int     psr_enable;
0086     int     nrzm_enable;
0087     int     pss_enable;
0088     int     crc_calc;   /* Enable Software CRC calculation (only Frame mode) */
0089 };
0090
0091 /* Argument of GRTC_IOC_GET_HW_STATUS:
0092  * Pointer to a grtc_ioc_hw_status structure that will be filled
0093  * in by driver.
0094  */
0095 struct grtc_ioc_hw_status {
0096     unsigned int    sir;
0097     unsigned int    far;
0098     unsigned int    clcw1;
0099     unsigned int    clcw2;
0100     unsigned int    phir;
0101     unsigned int    str;
0102 };
0103
0104 struct grtc_hdr {
0105     unsigned short  flags_scid;
0106     unsigned short  vc_len;
0107     unsigned char   seqnum;
0108 } __attribute__((packed));
0109
0110 /* Frame pool, all frames in pool have the same buffer length (frame mode only) */
0111 struct grtc_frame {
0112     struct grtc_frame   *next;      /* Next frame in list */
0113     unsigned short      len;        /* Length of frame extracted */
0114     unsigned short      reserved;   /* Reserved */
0115     struct grtc_frame_pool  *pool;      /* The frame pool this frame belongs to */
0116
0117     /* The Frame content */
0118     struct grtc_hdr     hdr;        /* Primary Header */
0119     unsigned char       data[3];    /* Frame payload */
0120 } __attribute__((packed));
0121
0122 /* GRTC_IOC_RECV argument, single linked list of received frames */
0123 struct grtc_list {
0124     struct grtc_frame   *head;      /* First frame in list */
0125     struct grtc_frame   *tail;      /* Last frame in list */
0126     int         cnt;        /* Number of frames in list */
0127 };
0128
0129 struct grtc_ioc_pools_setup {
0130     unsigned int    pool_cnt;       /* Number of pools */
0131     unsigned int    pool_frame_len[1];  /* Array of 'pool_cnt' length: Frame length of frames in a pool
0132                          * Lengths must be sorted, starting with the smallest frame pool.
0133                          */
0134 };
0135
0136 struct grtc_ioc_assign_frm_pool {
0137     unsigned int        frame_len;  /* The length of the pool to insert the frame into */
0138     struct grtc_frame   *frames;    /* Frames to assign to a pool */
0139 };
0140
0141 enum {
0142     GRTC_MODE_RAW   = 0,
0143     GRTC_MODE_FRAME = 1
0144 };
0145
0146 /* TC driver stats collected during receiving. The statistics is only available
0147  * in FRAME mode. In RAW mode the user interprets the incoming frames and is
0148  * therefore responsible for generating the staticstics.
0149  */
0150 struct grtc_ioc_stats {
0151     unsigned long long  frames_recv;        /* Total number of non-erroneous frames received */
0152     /* Errors related to incoming data */
0153     unsigned int        err;            /* total number of errors */
0154     unsigned int        err_hdr;        /* number of errors in Header */
0155     unsigned int        err_payload;        /* Number of errors in payload */
0156     unsigned int        err_ending;     /* Number of errors in end (Filler, end marker) */
0157     unsigned int        err_abandoned;      /* Number of abandoned frames, NOT IMPLEMENTED */
0158     /* Errors related to the handling of incoming frames */
0159     unsigned int        dropped;        /* Number of dropped frames TC driver */
0160     unsigned int        dropped_no_buf;     /* Number of dropped frame caused by no buffers were available */
0161     unsigned int        dropped_too_long;   /* Number of dropped frames that was larger than any buffer available for driver */
0162 };
0163
0164 /* Register GRTC driver at driver manager */
0165 void grtc_register_drv(void);
0166
0167 /* Register GRTC RMAP driver at driver manager */
0168 void grtc_rmap_register_drv (void);
0169
0170 #ifdef __cplusplus
0171 }
0172 #endif
0173
0174 #endif /* __GRTC_H__ */