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