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.3 $ 12 * $Date: 2004/12/27 14:00:54 $ 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 */ 385