gdb/rdi-share/rxtx.h

   1 /*
   2  * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
   3  *
   4  * This software may be freely used, copied, modified, and distributed
   5  * provided that the above copyright notice is preserved in all copies of the
   6  * software.
   7  */
   8
   9 /*-*-C-*-
  10  *
  11  * $Revision$
  12  *     $Date$
  13  *
  14  *
  15  *   Project: ANGEL
  16  *
  17  *     Title:  Definitions required for the rx and tx engines
  18  */
  19
  20 #ifndef angel_rxtx_h
  21 #define angel_rxtx_h
  22
  23
  24 /*
  25  * we need a definition for bool, which is "system" dependent
  26  */
  27 #ifdef TARGET
  28 # include "angel.h"
  29 #else
  30 # include "host.h"
  31 #endif
  32
  33 #include "devclnt.h"
  34
  35 /* return status codes for the rx engine */
  36 typedef enum re_status {
  37   RS_WAIT_PKT,
  38   RS_IN_PKT,
  39   RS_BAD_PKT,
  40   RS_GOOD_PKT
  41 } re_status;
  42
  43 /* return status codes for the tx engine */
  44 typedef enum te_status {
  45   TS_IDLE,
  46   TS_IN_PKT,
  47   TS_DONE_PKT
  48 } te_status;
  49
  50
  51 /*
  52  * required serial definitions, they should all be <32, refer to the
  53  * re_config struct comments for more details
  54  */
  55 #define serial_STX    (0x1c) /* data packet start */
  56 #define serial_ETX    (0x1d) /* packet end */
  57 #define serial_ESC    (0x1b) /* standard escape character */
  58 #define serial_XON    (0x11) /* software flow control - enable transmission */
  59 #define serial_XOFF   (0x13) /* software flow control - disable transmission */
  60
  61 /*
  62  * All other characters are transmitted clean. If any of the above
  63  * characters need to be transmitted as part of the serial data stream
  64  * then the character will be preceded by the "serial_ESC" character,
  65  * and then the required character transmitted (OR-ed with the
  66  * "serial_ESCAPE" value, to ensure that the serial stream never has
  67  * any of the exceptional characters generated by data transfers).
  68  */
  69
  70 #define serial_ESCAPE   (0x40)  /* OR-ed with escaped characters */
  71
  72 /* bad packet error codes */
  73 typedef enum re_error {
  74   RE_OKAY,
  75   RE_U_STX,
  76   RE_U_ETX,
  77   RE_LEN,
  78   RE_CRC,
  79   RE_NETX,
  80   RE_INTERNAL
  81 } re_error;
  82
  83 /* a decoded packet */
  84 struct data_packet {
  85   unsigned short  buf_len;      /* should be set by caller */
  86   DevChanID       type;         /* valid when status is RS_GOOD_PKT */
  87   unsigned short  len;          /* --"--                            */
  88   unsigned int    crc;          /* crc for the unescaped pkt */
  89   unsigned char   *data;        /* should be set by caller */
  90 };
  91
  92 /*
  93  * Purpose: typedef for flow control function
  94  *
  95  *  Params:
  96  *          Input:  fc_char  the flow control character in question
  97  *          In/Out: cb_data  callback data as set in the fc_data
  98  *                             field of re_config, typically device id
  99  *
 100  * This callback would tpyically respond to received XON and XOFF
 101  * characters by controlling the transmit side of the device.
 102  */
 103 typedef void (*fc_cb_func)(char fc_char, void *cb_data);
 104
 105
 106 /*
 107  * Purpose: typedef for the function to alloc the data buffer
 108  *
 109  *  Params:
 110  *          In/Out: packet    the data packet: len and type will be set on
 111  *                              entry, and buf_len and data should
 112  *                              be set by this routine if successful.
 113  *                  cb_data   callback data as set in the ba_data
 114  *                              field of re_config, typically device id
 115  *
 116  *         Returns: TRUE      buffer allocated okay
 117  *                  FALSE     couldn't allocate buffer of required size
 118  *                              for given type
 119  *
 120  * This callback should attempt to acquire a buffer for the data portion
 121  * of the packet which is currently being received, based on the len and
 122  * type fields supplied in packet.
 123  *
 124  * angel_DD_RxEng_BufferAlloc() is supplied for use as this callback,
 125  * and will be sufficient for most devices.
 126  */
 127 typedef bool (*BufferAlloc_CB_Fn)(struct data_packet *packet, void *cb_data);
 128
 129
 130 /*
 131  * The static info needed by the engine, may vary per device.
 132  *
 133  * fc_set and esc_set are bitmaps, e.g. bit 3 == charcode 3 == ASCII ETX.
 134  * Thus any of the first 32 charcodes can be set for flow control or to
 135  * be escaped.
 136  *
 137  * Note that esc_set should include all of fc_set, and should have bits
 138  * set for stx, etx and esc, as a minimum.
 139  *
 140  * If character codes > 31 need to be used then fc_set and esc_set
 141  * and their handling can be extended to use arrays and bit manipulation
 142  * macros, potentially up to the full 256 possible chars.
 143  *
 144  * Note too that this could/should be shared with the tx engine.
 145  */
 146
 147 struct re_config {
 148   unsigned char     stx;                  /* the STX char for this device */
 149   unsigned char     etx;                  /* the ETX --"--                */
 150   unsigned char     esc;                  /* the ESC --"--                */
 151   unsigned int      fc_set;               /* bitmap of flow control chars */
 152   unsigned int      esc_set;              /* bitmap of special chars      */
 153   fc_cb_func        fc_callback;          /* flow control callback func   */
 154   void              *fc_data;             /* data to pass to fc_callback  */
 155   BufferAlloc_CB_Fn ba_callback;          /* buffer alloc callback        */
 156   void              *ba_data;             /* data to pass to ba_calback   */
 157 };
 158
 159 /* the dynamic info needed by the rx engine */
 160 struct re_state {
 161   unsigned char          rx_state; /* 3 bits pkt state, 1 prepro state */
 162   unsigned short         field_c;  /* chars left in current field */
 163   unsigned short         index;    /* index into buffer */
 164   unsigned int           crc;      /* crc accumulator */
 165   re_error               error;    /* valid only if status is RS_BAD_PKT */
 166   const struct re_config *config;  /* pointer to static config */
 167 };
 168
 169 /* dynamic state info needed by the tx engine */
 170 struct te_state {
 171   unsigned short         field_c;  /* position in current field */
 172   unsigned char          tx_state; /* encodes n,e, and f (2+1+2=5 bits) */
 173   unsigned char          encoded;  /* escape-encoded char for transmission */
 174   const struct re_config *config;  /* pointer to static config */
 175   unsigned int           crc;      /* space for CRC (before escaping) */
 176 };
 177
 178 /*
 179  * Function: Angel_RxEngineInit
 180  *  Purpose: Initialise state (during device init) for engine.
 181  *
 182  *   Params:
 183  *              Input: config   static config info
 184  *             In/Out: state    internal state
 185  */
 186
 187 void Angel_RxEngineInit(const struct re_config *config,
 188                         struct re_state *state);
 189
 190 /*
 191  * Function: Angel_RxEngine
 192  *  Purpose: Rx Engine for character-based devices
 193  *
 194  *   Params:
 195  *              Input: new_ch       the latest character
 196  *
 197  *             In/Out: packet       details of packet
 198  *                                   packet.buf_len and packet.data must
 199  *                                   be set on entry!
 200  *                     state        internal state, intially set by
 201  *                                   angel_RxEngineInit()
 202  *
 203  *            Returns: re_status (see above)
 204  *
 205  */
 206
 207 re_status Angel_RxEngine(unsigned char new_ch, struct data_packet *packet,
 208                          struct re_state *state);
 209
 210 /*
 211  * This can be used as the buffer allocation callback for the rx engine,
 212  * and will make use of angel_DD_GetBuffer() [in devdrv.h].
 213  *
 214  * Saves duplicating this callback function in every device driver that
 215  * uses the rx engine.
 216  *
 217  * Note that this REQUIRES that the device id is installed as ba_data
 218  * in the rx engine config structure for the driver.
 219  */
 220 bool angel_DD_RxEng_BufferAlloc( struct data_packet *packet, void *cb_data );
 221
 222 /*
 223  * Function: Angel_TxEngineInit
 224  *  Purpose: Set up tx engine at start of new packet, calculate CRC etc.
 225  *           (This should perform the actions described under
 226  *             "Initialisation" above)
 227  *
 228  *   Params:
 229  *              Input: config   static config info
 230  *                     packet   the packet to transmit
 231  *             In/Out: state    internal state
 232  */
 233
 234 void Angel_TxEngineInit(const struct re_config   *config,
 235                         const struct data_packet *packet,
 236                         struct te_state    *state);
 237
 238 /*
 239  * Function: Angel_TxEngine
 240  *  Purpose: Tx Engine for character-based devices
 241  *
 242  *   Params:
 243  *              Input: packet       details of packet
 244  *                                   packet.len, packet.data and
 245  *                                   packet.type must
 246  *                                   be set on entry!
 247  *             In/Out: state        internal state, intially set by
 248  *                                   angel_TxEngineStart()
 249  *             Output: tx_ch        the character to be transmitted
 250  *                                   (NOT SET if return code is TS_IDLE)
 251  *
 252  *            Returns: te_status (see above)
 253  */
 254
 255 te_status Angel_TxEngine(const struct data_packet  *packet,
 256                          struct te_state *state,
 257                          unsigned char *tx_ch);
 258
 259
 260
 261 #endif /* !defined(angel_rxtx_h) */
 262
 263 /*  EOF rxtx.h */