2 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
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
17 * Title: User interface to the channels layer
20 #ifndef angel_channels_h
21 #define angel_channels_h
24 * This provides the public interface to the channels layer read and write
25 * routines, and buffer management routines.
28 /* Nested header files, if required */
34 /* General purpose constants, macros, enums, typedefs */
36 /* use the default device */
37 #define CH_DEFAULT_DEV ((DeviceID)-1)
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 */
50 /* Publically-accessible globals */
53 * The following two globals are only valid after angel_InitialiseChannels()
57 /* the default size of a channel buffer, for global use */
58 extern unsigned Angel_ChanBuffSize
;
60 /* the size of a long buffer, for global use */
61 extern unsigned Angel_ChanLongSize
;
64 AdpErrs
send_resend_msg(DeviceID devid
);
68 * Function: angel_InitialiseChannels
69 * Purpose: initialise the channels layer
81 * Other side effects: -
84 void angel_InitialiseChannels( void );
87 * Function: adp_init_seq
88 * Purpose: initialise sequence numbers and free anyt leftover buffers
95 * Returns: - adp_ok if things went ok else an error code
100 * Other side effects: -
103 AdpErrs
adp_init_seq(void);
106 * Function: angel_ChannelAllocBuffer
107 * Purpose: allocate a buffer that is at least req_size bytes long
110 * Input: req_size the minimum size required
114 * Returns: pointer to allocated buffer, or
115 * NULL if unable to allocate suitable buffer
118 * Modifies globals: -
120 * Other side effects: -
123 p_Buffer
angel_ChannelAllocBuffer(unsigned req_size
);
127 * Function: angel_ChannelReleaseBuffer
128 * Purpose: release a buffer back to the free pool
131 * Input: buffer the buffer to release
138 * Modifies globals: -
140 * Other side effects: -
143 void angel_ChannelReleaseBuffer(p_Buffer buffer
);
147 * Function: angel_ChannelSend
148 * Purpose: blocking send of a packet via a channel
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
158 * Returns: CE_OKAY Transmission completed
159 * CE_BAD_CHAN Channel id invalid
160 * CE_ABANDONED Tx abandoned due to device switch
163 * Modifies globals: -
165 * Other side effects: -
168 ChanError
angel_ChannelSend(DeviceID devid
, ChannelID chanid
,
169 const p_Buffer buffer
, unsigned len
);
173 * Function: angel_ChannelSendAsync
174 * Purpose: asynchronous send of a packet via a channel
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
186 * Returns: CE_OKAY Transmission underway
187 * CE_BAD_CHAN Channel id invalid
188 * CE_ABANDONED Tx abandoned due to device switch
191 * Modifies globals: -
193 * Other side effects: -
195 * register an asynchronous send on the given channel
196 * (blocks until send can be commenced)
199 typedef void (*ChanTx_CB_Fn
)(ChannelID chanid
, /* which channel */
200 void *callback_data
); /* as supplied... */
203 ChanError
angel_ChannelSendAsync( DeviceID devid
,
205 const p_Buffer buffer
,
207 ChanTx_CB_Fn callback
,
208 void *callback_data
);
212 * Function: angel_ChannelRead
213 * Purpose: blocking read of a packet from a channel
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
222 * Returns: CE_OKAY Reception successful
223 * CE_BAD_CHAN Channel id invalid
224 * CE_ABANDONED Tx abandoned due to device switch
227 * Modifies globals: -
229 * Other side effects: -
231 * Note that in the present version, if an asynchronous read has been
232 * registered, a blocking read will be refused with CE_BUSY.
234 ChanError
angel_ChannelRead(DeviceID devid
,
241 * Function: angel_ChannelReadAsync
242 * Purpose: asynchronous read of a packet via a channel
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
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)
258 * Modifies globals: -
260 * Other side effects: -
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.
266 * Reader can unregister by specifying NULL as the callback function.
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 */
276 ChanError
angel_ChannelReadAsync(DeviceID devid
,
278 ChanRx_CB_Fn callback
,
279 void *callback_data
);
283 * Function: angel_ChannelReadAll
284 * Purpose: register an asynchronous read across all devices
287 * Input: chanid Channel to look for (usually HBOOT)
288 * callback Function to call on completion
289 * callback_data Pointer to pass to callback
293 * Returns: CE_OKAY Read request registered
294 * CE_BAD_CHAN Channel id invalid
295 * CE_BUSY Someone else is reading all devices
298 * Modifies globals: -
300 * Other side effects: -
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.
307 ChanError
angel_ChannelReadAll( ChannelID chanid
,
308 ChanRx_CB_Fn callback
,
309 void *callback_data
);
314 * Function: angel_ChannelSendThenRead
315 * Purpose: blocking write to followed by read from a channel
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
326 * Returns: CE_OKAY Tx and Reception successful
327 * CE_BAD_CHAN Channel id invalid
328 * CE_ABANDONED Tx abandoned due to device switch
331 * Modifies globals: -
333 * Other side effects: -
335 * Note that in the present version, if an asynchronous read has been
336 * registered, this will be refused with CE_BUSY.
338 ChanError
angel_ChannelSendThenRead(DeviceID devid
,
345 * Function: angel_ChannelSelectDevice
346 * Purpose: select the device to be used for all channel comms
349 * Input: device ID of device to use as the default
353 * Returns: CE_OKAY Default device selected
354 * CE_BAD_DEV Invalid device ID
357 * Modifies globals: -
359 * Other side effects: Any channel operations in progress are
362 * select the device for all channels comms
365 ChanError
angel_ChannelSelectDevice(DeviceID device
);
369 * Function: angel_ChannelReadActiveDevice
370 * Purpose: reads the device id of the currently active device
373 * Input: device address of a DeviceID variable
374 * Output: *device ID of device currently being used
377 * Returns: CE_OKAY Default device selected
380 ChanError
angel_ChannelReadActiveDevice(DeviceID
*device
);
382 #endif /* ndef angel_channels_h */
This page took 0.03852 seconds and 4 git commands to generate.