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: 1.2 $ 12 * $Date: 1998/01/08 11:12:29 $ 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 */ 36typedef 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 */ 44typedef 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 */ 73typedef 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 */ 84struct 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 */ 103typedef 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 */ 127typedef 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 147struct 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 */ 160struct 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 */ 170struct 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 187void 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 207re_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 */ 220bool 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 234void 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 255te_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 */ 264