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:11:40 $
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 */
40typedef 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 */
58extern unsigned Angel_ChanBuffSize;
59
60/* the size of a long buffer, for global use */
61extern unsigned Angel_ChanLongSize;
62
63#ifdef TARGET
64AdpErrs 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
84void 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
103AdpErrs 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
123p_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
143void 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
168ChanError 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
199typedef void (*ChanTx_CB_Fn)(ChannelID  chanid,         /* which channel  */
200                             void      *callback_data); /* as supplied... */
201
202
203ChanError 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 */
234ChanError 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
269typedef 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
276ChanError 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
307ChanError 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 */
338ChanError 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
365ChanError 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
380ChanError angel_ChannelReadActiveDevice(DeviceID *device);
381
382#endif /* ndef angel_channels_h */
383
384/* EOF channels.h */
385