Commit | Line | Data |
---|---|---|
c906108c SS |
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: User interface to the channels layer | |
18 | */ | |
19 | ||
20 | #ifndef angel_channels_h | |
21 | #define angel_channels_h | |
22 | ||
23 | /* | |
24 | * This provides the public interface to the channels layer read and write | |
25 | * routines, and buffer management routines. | |
26 | */ | |
27 | ||
28 | /* Nested header files, if required */ | |
29 | ||
30 | #include "devices.h" | |
31 | #include "chandefs.h" | |
32 | #include "adperr.h" | |
33 | ||
34 | /* General purpose constants, macros, enums, typedefs */ | |
35 | ||
36 | /* use the default device */ | |
37 | #define CH_DEFAULT_DEV ((DeviceID)-1) | |
38 | ||
39 | /* return codes */ | |
40 | typedef enum ChanError { | |
41 | CE_OKAY, /* no error */ | |
42 | CE_ABANDONED, /* abandoned due to device switch */ | |
43 | CE_DEV_ERROR, /* unexpected error from device driver */ | |
44 | CE_BUSY, /* channel in use */ | |
45 | CE_BUFF_ERROR, /* unable to get buffer */ | |
46 | CE_PRIVATE /* start of internal error codes */ | |
47 | } ChanError; | |
48 | ||
49 | ||
50 | /* Publically-accessible globals */ | |
51 | ||
52 | /* | |
53 | * The following two globals are only valid after angel_InitialiseChannels() | |
54 | * has been called. | |
55 | */ | |
56 | ||
57 | /* the default size of a channel buffer, for global use */ | |
58 | extern unsigned Angel_ChanBuffSize; | |
59 | ||
60 | /* the size of a long buffer, for global use */ | |
61 | extern unsigned Angel_ChanLongSize; | |
62 | ||
63 | #ifdef TARGET | |
64 | AdpErrs send_resend_msg(DeviceID devid); | |
65 | #endif | |
66 | ||
67 | /* | |
68 | * Function: angel_InitialiseChannels | |
69 | * Purpose: initialise the channels layer | |
70 | * | |
71 | * Params: | |
72 | * Input: - | |
73 | * Output: - | |
74 | * In/Out: - | |
75 | * | |
76 | * Returns: - | |
77 | * | |
78 | * Reads globals: - | |
79 | * Modifies globals: - | |
80 | * | |
81 | * Other side effects: - | |
82 | */ | |
83 | ||
84 | void angel_InitialiseChannels( void ); | |
85 | ||
86 | /* | |
87 | * Function: adp_init_seq | |
88 | * Purpose: initialise sequence numbers and free anyt leftover buffers | |
89 | * | |
90 | * Params: | |
91 | * Input: - | |
92 | * Output: - | |
93 | * In/Out: - | |
94 | * | |
95 | * Returns: - adp_ok if things went ok else an error code | |
96 | * | |
97 | * Reads globals: - | |
98 | * Modifies globals: - | |
99 | * | |
100 | * Other side effects: - | |
101 | */ | |
102 | ||
103 | AdpErrs adp_init_seq(void); | |
104 | ||
105 | /* | |
106 | * Function: angel_ChannelAllocBuffer | |
107 | * Purpose: allocate a buffer that is at least req_size bytes long | |
108 | * | |
109 | * Params: | |
110 | * Input: req_size the minimum size required | |
111 | * Output: - | |
112 | * In/Out: - | |
113 | * | |
114 | * Returns: pointer to allocated buffer, or | |
115 | * NULL if unable to allocate suitable buffer | |
116 | * | |
117 | * Reads globals: - | |
118 | * Modifies globals: - | |
119 | * | |
120 | * Other side effects: - | |
121 | */ | |
122 | ||
123 | p_Buffer angel_ChannelAllocBuffer(unsigned req_size); | |
124 | ||
125 | ||
126 | /* | |
127 | * Function: angel_ChannelReleaseBuffer | |
128 | * Purpose: release a buffer back to the free pool | |
129 | * | |
130 | * Params: | |
131 | * Input: buffer the buffer to release | |
132 | * Output: - | |
133 | * In/Out: - | |
134 | * | |
135 | * Returns: - | |
136 | * | |
137 | * Reads globals: - | |
138 | * Modifies globals: - | |
139 | * | |
140 | * Other side effects: - | |
141 | */ | |
142 | ||
143 | void angel_ChannelReleaseBuffer(p_Buffer buffer); | |
144 | ||
145 | ||
146 | /* | |
147 | * Function: angel_ChannelSend | |
148 | * Purpose: blocking send of a packet via a channel | |
149 | * | |
150 | * Params: | |
151 | * Input: devid Device to use, or CH_DEFAULT_DEV | |
152 | * chanid Channel to use for tx | |
153 | * buffer Pointer to data to send | |
154 | * len Length of data to send | |
155 | * Output: - | |
156 | * In/Out: - | |
157 | * | |
158 | * Returns: CE_OKAY Transmission completed | |
159 | * CE_BAD_CHAN Channel id invalid | |
160 | * CE_ABANDONED Tx abandoned due to device switch | |
161 | * | |
162 | * Reads globals: - | |
163 | * Modifies globals: - | |
164 | * | |
165 | * Other side effects: - | |
166 | */ | |
167 | ||
168 | ChanError angel_ChannelSend(DeviceID devid, ChannelID chanid, | |
169 | const p_Buffer buffer, unsigned len); | |
170 | ||
171 | ||
172 | /* | |
173 | * Function: angel_ChannelSendAsync | |
174 | * Purpose: asynchronous send of a packet via a channel | |
175 | * | |
176 | * Params: | |
177 | * Input: devid Device to use, or CH_DEFAULT_DEV | |
178 | * chanid Channel to use for tx | |
179 | * buffer Pointer to data to send | |
180 | * len Length of data to send | |
181 | * callback Function to call on completion | |
182 | * callback_data Pointer to pass to callback | |
183 | * Output: - | |
184 | * In/Out: - | |
185 | * | |
186 | * Returns: CE_OKAY Transmission underway | |
187 | * CE_BAD_CHAN Channel id invalid | |
188 | * CE_ABANDONED Tx abandoned due to device switch | |
189 | * | |
190 | * Reads globals: - | |
191 | * Modifies globals: - | |
192 | * | |
193 | * Other side effects: - | |
194 | * | |
195 | * register an asynchronous send on the given channel | |
196 | * (blocks until send can be commenced) | |
197 | */ | |
198 | ||
199 | typedef void (*ChanTx_CB_Fn)(ChannelID chanid, /* which channel */ | |
200 | void *callback_data); /* as supplied... */ | |
201 | ||
202 | ||
203 | ChanError angel_ChannelSendAsync( DeviceID devid, | |
204 | ChannelID chanid, | |
205 | const p_Buffer buffer, | |
206 | unsigned len, | |
207 | ChanTx_CB_Fn callback, | |
208 | void *callback_data); | |
209 | ||
210 | ||
211 | /* | |
212 | * Function: angel_ChannelRead | |
213 | * Purpose: blocking read of a packet from a channel | |
214 | * | |
215 | * Params: | |
216 | * Input: devid Device to use, or CH_DEFAULT_DEV | |
217 | * chanid Channel to use for rx | |
218 | * Output: buffer The buffer, supplied and filled | |
219 | * len How many bytes there are in the buffer | |
220 | * In/Out: - | |
221 | * | |
222 | * Returns: CE_OKAY Reception successful | |
223 | * CE_BAD_CHAN Channel id invalid | |
224 | * CE_ABANDONED Tx abandoned due to device switch | |
225 | * | |
226 | * Reads globals: - | |
227 | * Modifies globals: - | |
228 | * | |
229 | * Other side effects: - | |
230 | * | |
231 | * Note that in the present version, if an asynchronous read has been | |
232 | * registered, a blocking read will be refused with CE_BUSY. | |
233 | */ | |
234 | ChanError angel_ChannelRead(DeviceID devid, | |
235 | ChannelID chanid, | |
236 | p_Buffer *buffer, | |
237 | unsigned *len); | |
238 | ||
239 | ||
240 | /* | |
241 | * Function: angel_ChannelReadAsync | |
242 | * Purpose: asynchronous read of a packet via a channel | |
243 | * | |
244 | * Params: | |
245 | * Input: devid Device to use, or CH_DEFAULT_DEV | |
246 | * chanid Channel to wait on | |
247 | * callback Function to call on completion, or NULL | |
248 | * callback_data Pointer to pass to callback | |
249 | * Output: - | |
250 | * In/Out: - | |
251 | * | |
252 | * Returns: CE_OKAY Read request registered | |
253 | * CE_BAD_CHAN Channel id invalid | |
254 | * CE_BUSY Someone else is using the channel | |
255 | * (in a single threaded world) | |
256 | * | |
257 | * Reads globals: - | |
258 | * Modifies globals: - | |
259 | * | |
260 | * Other side effects: - | |
261 | * | |
262 | * Register an asynchronous read on the given channel. There can only be one | |
263 | * async. reader per channel, and blocking reads are not permitted whilst | |
264 | * an async. reader is registered. | |
265 | * | |
266 | * Reader can unregister by specifying NULL as the callback function. | |
267 | */ | |
268 | ||
269 | typedef void (*ChanRx_CB_Fn)(DeviceID devID, /* ID of receiving device */ | |
270 | ChannelID chanID, /* ID of receiving channel */ | |
271 | p_Buffer buff, /* pointer to buffer */ | |
272 | unsigned len, /* length of data */ | |
273 | void *cb_data /* callback data */ | |
274 | ); | |
275 | ||
276 | ChanError angel_ChannelReadAsync(DeviceID devid, | |
277 | ChannelID chanid, | |
278 | ChanRx_CB_Fn callback, | |
279 | void *callback_data); | |
280 | ||
281 | ||
282 | /* | |
283 | * Function: angel_ChannelReadAll | |
284 | * Purpose: register an asynchronous read across all devices | |
285 | * | |
286 | * Params: | |
287 | * Input: chanid Channel to look for (usually HBOOT) | |
288 | * callback Function to call on completion | |
289 | * callback_data Pointer to pass to callback | |
290 | * Output: - | |
291 | * In/Out: - | |
292 | * | |
293 | * Returns: CE_OKAY Read request registered | |
294 | * CE_BAD_CHAN Channel id invalid | |
295 | * CE_BUSY Someone else is reading all devices | |
296 | * | |
297 | * Reads globals: - | |
298 | * Modifies globals: - | |
299 | * | |
300 | * Other side effects: - | |
301 | * | |
302 | * Register an asynchronous read across all devices. This is a 'fallback', | |
303 | * which will be superseded (temporarily) by a registered reader or blocking | |
304 | * read on a specific device. | |
305 | */ | |
306 | ||
307 | ChanError angel_ChannelReadAll( ChannelID chanid, | |
308 | ChanRx_CB_Fn callback, | |
309 | void *callback_data); | |
310 | ||
311 | ||
312 | ||
313 | /* | |
314 | * Function: angel_ChannelSendThenRead | |
315 | * Purpose: blocking write to followed by read from a channel | |
316 | * | |
317 | * Params: | |
318 | * Input: devid Device to use, or CH_DEFAULT_DEV | |
319 | * chanid Channel to use for rx | |
320 | * In/Out: buffer On entry: the packet to be sent | |
321 | * On return: the packet received | |
322 | * len On entry: length of packet to be sent | |
323 | * On return: length of packet rx'd | |
324 | * In/Out: - | |
325 | * | |
326 | * Returns: CE_OKAY Tx and Reception successful | |
327 | * CE_BAD_CHAN Channel id invalid | |
328 | * CE_ABANDONED Tx abandoned due to device switch | |
329 | * | |
330 | * Reads globals: - | |
331 | * Modifies globals: - | |
332 | * | |
333 | * Other side effects: - | |
334 | * | |
335 | * Note that in the present version, if an asynchronous read has been | |
336 | * registered, this will be refused with CE_BUSY. | |
337 | */ | |
338 | ChanError angel_ChannelSendThenRead(DeviceID devid, | |
339 | ChannelID chanid, | |
340 | p_Buffer *buffer, | |
341 | unsigned *len); | |
342 | ||
343 | ||
344 | /* | |
345 | * Function: angel_ChannelSelectDevice | |
346 | * Purpose: select the device to be used for all channel comms | |
347 | * | |
348 | * Params: | |
349 | * Input: device ID of device to use as the default | |
350 | * Output: - | |
351 | * In/Out: - | |
352 | * | |
353 | * Returns: CE_OKAY Default device selected | |
354 | * CE_BAD_DEV Invalid device ID | |
355 | * | |
356 | * Reads globals: - | |
357 | * Modifies globals: - | |
358 | * | |
359 | * Other side effects: Any channel operations in progress are | |
360 | * abandoned. | |
361 | * | |
362 | * select the device for all channels comms | |
363 | */ | |
364 | ||
365 | ChanError angel_ChannelSelectDevice(DeviceID device); | |
366 | ||
367 | ||
368 | /* | |
369 | * Function: angel_ChannelReadActiveDevice | |
370 | * Purpose: reads the device id of the currently active device | |
371 | * | |
372 | * Params: | |
373 | * Input: device address of a DeviceID variable | |
374 | * Output: *device ID of device currently being used | |
375 | * In/Out: - | |
376 | * | |
377 | * Returns: CE_OKAY Default device selected | |
378 | */ | |
379 | ||
380 | ChanError angel_ChannelReadActiveDevice(DeviceID *device); | |
381 | ||
382 | #endif /* ndef angel_channels_h */ | |
383 | ||
384 | /* EOF channels.h */ |