include/grlib/grtm.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /* GRTM Telemetry (TM) 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 __GRTM_H__
0031 #define __GRTM_H__
0032
0033 #include <rtems.h>
0034
0035 #ifdef __cplusplus
0036 extern "C" {
0037 #endif
0038
0039 #define GRTM_IOC_UNUSED         0
0040
0041 /* Driver operation controlling commands */
0042 #define GRTM_IOC_START          1
0043 #define GRTM_IOC_STOP           2
0044 #define GRTM_IOC_ISSTARTED      3
0045 #define GRTM_IOC_SET_BLOCKING_MODE  4
0046 #define GRTM_IOC_SET_TIMEOUT        5
0047
0048 /* Available only in STOPPED mode */
0049 #define GRTM_IOC_SET_CONFIG     32
0050
0051 /* Available in both running and stopped mode */
0052 #define GRTM_IOC_RECLAIM        64
0053 #define GRTM_IOC_GET_CONFIG     65
0054 #define GRTM_IOC_GET_HW_IMPL        66
0055 #define GRTM_IOC_GET_HW_STATUS      67  /* Not implemented */
0056 #define GRTM_IOC_GET_OCFREG     68
0057 #define GRTM_IOC_GET_STATS      69
0058 #define GRTM_IOC_CLR_STATS      70
0059
0060 /* Available only in RUNNING mode */
0061 #define GRTM_IOC_SEND           96
0062
0063 /* Args to GRTC_IOC_SET_BLOCKING_MODE */
0064 enum {
0065     GRTM_BLKMODE_POLL   = 0,    /* Never block (polling mode) */
0066     GRTM_BLKMODE_BLK    = 1,    /* Block until at least 1 byte can be read */
0067 };
0068
0069 /* Reed Solomon Encoder implemented */
0070 enum {
0071     GRTM_RS_IMPL_NONE   = 0,
0072     GRTM_RS_IMPL_E16    = 1,    /* E16 */
0073     GRTM_RS_IMPL_E8     = 2,    /* E8 */
0074     GRTM_RS_IMPL_BOTH   = 3 /* Both E8 and E16 */
0075
0076 };
0077
0078 struct grtm_ioc_hw {
0079     char        cs;     /* Sub Carrier */
0080     char        sp;     /* Split-Phase Level */
0081     char        ce;
0082     char        nrz;
0083     char        psr;
0084     char        te;
0085     unsigned char   rsdep;
0086     unsigned char   rs;
0087     char        aasm;
0088     char        fecf;
0089     char        ocf;
0090     char        evc;
0091     char        idle;
0092     char        fsh;
0093     char        mcg;
0094     char        iz;
0095     char        fhec;
0096     char        aos;
0097     char        cif;
0098     char        ocfb;
0099
0100     unsigned short  blk_size;   /* Block Size */
0101     unsigned short  fifo_size;  /* FIFO Size */
0102
0103 };
0104
0105 /* Driver Mode */
0106 enum {
0107     GRTM_MODE_TM        = 0,    /* TM */
0108     GRTM_MODE_AOS       = 1 /* AOS */
0109 };
0110
0111 /* Physical layer Options */
0112 #define GRTM_IOC_PHY_SCF    (1<<15)     /* Sub Carrier Fall */
0113 #define GRTM_IOC_PHY_SF     (1<<31)     /* Symbol Fall */
0114
0115 /* Coding Sub-layer Options */
0116 #define GRTM_IOC_CODE_SC    (1<<0)      /* Enable Sub Carrier modulation */
0117 #define GRTM_IOC_CODE_SP    (1<<1)      /* Enable Split-Phase (SP) level modulation */
0118 #define GRTM_IOC_CODE_CE    (1<<5)      /* Enable Convolutional Encoding */
0119 #define GRTM_IOC_CODE_NRZ   (1<<6)      /* Enable Non-Return-to-Zero mark encoding */
0120 #define GRTM_IOC_CODE_PSR   (1<<7)      /* Enable Pseudo-Randomizer */
0121 #define GRTM_IOC_CODE_RS8   (1<<11)     /* Reed-solomon Encoder to use: 0=E16, 1=E8 */
0122 #define GRTM_IOC_CODE_RS    (1<<15)     /* Enable Reed-Solomon Encoder */
0123 #define GRTM_IOC_CODE_AASM  (1<<16)     /* Enable Alternative attached synchronization marker */
0124 #define GRTM_IOC_CODE_ALL   (GRTM_IOC_CODE_SC|GRTM_IOC_CODE_SP|GRTM_IOC_CODE_CE| \
0125                 GRTM_IOC_CODE_NRZ|GRTM_IOC_CODE_PSR|GRTM_IOC_CODE_RS8|\
0126                 GRTM_IOC_CODE_RS|GRTM_IOC_CODE_AASM)
0127
0128 enum {
0129     GRTM_CERATE_00      = 0,    /* Rate 1/2, no puncturing */
0130     GRTM_CERATE_02      = 2,    /* Rate 1/2, punctured */
0131     GRTM_CERATE_04      = 4,    /* Rate 2/3, punctured */
0132     GRTM_CERATE_05      = 5,    /* Rate 3/4, punctured */
0133     GRTM_CERATE_06      = 6,    /* Rate 5/6, punctured */
0134     GRTM_CERATE_07      = 7,    /* Rate 7/8, punctured */
0135 };
0136
0137 /* Options for Generating all frames */
0138 #define GRTM_IOC_ALL_FHEC   0x01    /* Enable Frame Header Error Control (Only AOS) */
0139 #define GRTM_IOC_ALL_FECF   0x02    /* Enable Transfer Frame CRC */
0140 #define GRTM_IOC_ALL_IZ     0x04    /* Enable Insert Zone */
0141 #define GRTM_IOC_ALL_ALL    (GRTM_IOC_ALL_FHEC|GRTM_IOC_ALL_FECF|GRTM_IOC_ALL_IZ)
0142
0143 /* Master Frame Generation Options */
0144 #define GRTM_IOC_MF_OW      0x01    /* Over Write OCF bits 16 and 17 */
0145 #define GRTM_IOC_MF_OCF     0x02    /* Enable Operation Control Field (OCF) for master channel */
0146 #define GRTM_IOC_MF_FSH     0x04    /* Enable MC_FSH for master channel */
0147 #define GRTM_IOC_MF_MC      0x08    /* Enable Master channel counter generation */
0148 #define GRTM_IOC_MF_ALL     (GRTM_IOC_MF_OW|GRTM_IOC_MF_OCF|GRTM_IOC_MF_FSH|GRTM_IOC_MF_MC)
0149
0150 /* Idle Frames Generation Options */
0151 #define GRTM_IOC_IDLE_MC    0x01    /* Enable Master Channel (MC) counter generation (TM Only) */
0152 #define GRTM_IOC_IDLE_VCC   0x02    /* Enable Virtual Channel counter cycle generation (AOS Only)*/
0153 #define GRTM_IOC_IDLE_FSH   0x04    /* Enable Frame Secondary Header (FSH) for idle frames (TM Only) */
0154 #define GRTM_IOC_IDLE_EVC   0x08    /* Enable Extended Virtual Channel Counter Generation */
0155 #define GRTM_IOC_IDLE_OCF   0x10    /* Enable OCF/CLCW in idle frame */
0156 #define GRTM_IOC_IDLE_EN    0x20    /* Enable Idle frame generation */
0157 #define GRTM_IOC_IDLE_ALL   (GRTM_IOC_IDLE_MC|GRTM_IOC_IDLE_VCC|GRTM_IOC_IDLE_FSH| \
0158                 GRTM_IOC_IDLE_EVC|GRTM_IOC_IDLE_OCF|GRTM_IOC_IDLE_EN)
0159
0160 /* Argument of GRTM_IOC_SET_CONFIG and GRTM_IOC_GET_CONFIG.
0161  * Driver and Hardware configuration.
0162  *
0163  * Pointer to:
0164  */
0165 struct grtm_ioc_config {
0166
0167     /* Mode AOS or TM */
0168     unsigned char   mode;       /* 0=TM, 1=AOS */
0169
0170     unsigned short  frame_length;   /* Length of every frame transmitted */
0171     unsigned short  limit;      /* Number of data bytes fetched by DMA before transmission starts */
0172     unsigned int    as_marker;  /* Attached Synchronization Marker */
0173
0174     /* Physical layer options */
0175     unsigned short  phy_subrate;    /* Sub Carrier rate - sub carrier devision factor - 1 */
0176     unsigned short  phy_symbolrate; /* Symbol Rate division factor - 1 */
0177     unsigned char   phy_opts;   /* Mask of GRTM_IOC_PHY_XXXX */
0178
0179     /* Coding sub-layer Options */
0180     unsigned char   code_rsdep; /* Coding sub-layer Reed-Solomon interleave depth (3-bit) */
0181     unsigned char   code_ce_rate;   /* Convolutional encoding rate, select one of GRTM_CERATE_00 ... GRTM_CERATE_07 */
0182     unsigned char   code_csel;  /*   */
0183     unsigned int    code_opts;  /* Mask of GRTM_IOC_CODE_XXXX */
0184
0185     /* All Frames Generation */
0186     unsigned char   all_izlen;  /* FSH/IZ Length (5-bit) */
0187     unsigned char   all_opts;   /* Mask of GRTM_IOC_ALL_XXXX */
0188
0189     /* Master Frame Generation */
0190     unsigned char   mf_opts;    /* Mask of GRTM_IOC_MF_XXXX */
0191
0192     /* Idle frame Generation */
0193     unsigned short  idle_scid;
0194     unsigned char   idle_vcid;
0195     unsigned char   idle_opts;  /* Mask of GRTM_IOC_IDLE_XXXX */
0196
0197     /* Interrupt options */
0198     unsigned int    enable_cnt; /* Number of frames in between Interrupt is generated, Zero disables interrupt */
0199     int     isr_desc_proc;  /* Enable ISR to process descriptors */
0200     int     blocking;   /* Blocking mode select (POLL,BLK..) */
0201     rtems_interval  timeout;    /* Blocking mode timeout */
0202 };
0203
0204 struct grtm_frame;
0205
0206 struct grtm_list {
0207     struct grtm_frame *head;    /* First Frame in list */
0208     struct grtm_frame *tail;    /* Last Frame in list */
0209 };
0210
0211 #define GRTM_FLAGS_SENT     0x01
0212 #define GRRM_FLAGS_ERR      0x02
0213
0214 #define GRTM_FLAGS_TRANSLATE    (1<<31) /* Translate frame payload address from CPU address to remote bus (the bus GRTM is resident on) */
0215 #define GRTM_FLAGS_TRANSLATE_AND_REMEMBER   (1<<30) /* As GRTM_FLAGS_TRANSLATE, however if the translated payload address equals the payload address
0216                              * the GRTM_FLAGS_TRANSLATE_AND_REMEMBER bit is cleared and the GRTM_FLAGS_TRANSLATE bit is set */
0217 #define GRTM_FLAGS_COPY_DATA    (1<<29) /* Where available: Transfer Frame payload to target, may be used for SpaceWire, where the GRTM driver transfer
0218                      * the payload to a buffer on the SpaceWire target.
0219                      */
0220
0221 #define GRTM_FLAGS_TS       (1<<14)
0222 #define GRTM_FLAGS_VCE      (1<<9)
0223 #define GRTM_FLAGS_MCB      (1<<8)
0224 #define GRTM_FLAGS_FSHB     (1<<7)
0225 #define GRTM_FLAGS_OCFB     (1<<6)
0226 #define GRTM_FLAGS_FHECB    (1<<5)
0227 #define GRTM_FLAGS_IZB      (1<<4)
0228 #define GRTM_FLAGS_FECFB    (1<<3)
0229
0230 #define GRTM_FLAGS_MASK     (GRTM_FLAGS_TS|GRTM_FLAGS_VCE|GRTM_FLAGS_MCB|\
0231                  GRTM_FLAGS_FSHB|GRTM_FLAGS_OCFB|GRTM_FLAGS_FHECB|\
0232                  GRTM_FLAGS_IZB|GRTM_FLAGS_FECFB)
0233
0234 /* The GRTM software representation of a Frame */
0235 struct grtm_frame {
0236     /* Options and status */
0237     unsigned int        flags;      /* bypass options, and sent/error status */
0238
0239     struct grtm_frame   *next;      /* Next packet in chain */
0240
0241     unsigned int        *payload;   /* The Headers and Payload,  Frame data and header must be word aligned */
0242 };
0243
0244 #define FRAME_SIZE(payloadlen)  (sizeof(struct grtm_frame)+payloadlen)
0245
0246 struct grtm_ioc_stats {
0247     unsigned long long  frames_sent;
0248     unsigned int        err_underrun;
0249     unsigned int        err_tx;
0250     unsigned int        err_ahb;
0251     unsigned int        err_transfer_frame;
0252 };
0253
0254 /* Register GRTM driver at driver manager */
0255 void grtm_register_drv(void);
0256
0257 /* Register GRTM RMAP driver at driver manager */
0258 void grtm_rmap_register_drv (void);
0259
0260 #ifdef __cplusplus
0261 }
0262 #endif
0263
0264 #endif /* __GRTM_H__ */