| /* |
| * 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: User interface to the channels layer |
| */ |
| |
| #ifndef angel_channels_h |
| #define angel_channels_h |
| |
| /* |
| * This provides the public interface to the channels layer read and write |
| * routines, and buffer management routines. |
| */ |
| |
| /* Nested header files, if required */ |
| |
| #include "devices.h" |
| #include "chandefs.h" |
| #include "adperr.h" |
| |
| /* General purpose constants, macros, enums, typedefs */ |
| |
| /* use the default device */ |
| #define CH_DEFAULT_DEV ((DeviceID)-1) |
| |
| /* return codes */ |
| typedef enum ChanError { |
| CE_OKAY, /* no error */ |
| CE_ABANDONED, /* abandoned due to device switch */ |
| CE_DEV_ERROR, /* unexpected error from device driver */ |
| CE_BUSY, /* channel in use */ |
| CE_BUFF_ERROR, /* unable to get buffer */ |
| CE_PRIVATE /* start of internal error codes */ |
| } ChanError; |
| |
| |
| /* Publically-accessible globals */ |
| |
| /* |
| * The following two globals are only valid after angel_InitialiseChannels() |
| * has been called. |
| */ |
| |
| /* the default size of a channel buffer, for global use */ |
| extern unsigned Angel_ChanBuffSize; |
| |
| /* the size of a long buffer, for global use */ |
| extern unsigned Angel_ChanLongSize; |
| |
| #ifdef TARGET |
| AdpErrs send_resend_msg(DeviceID devid); |
| #endif |
| |
| /* |
| * Function: angel_InitialiseChannels |
| * Purpose: initialise the channels layer |
| * |
| * Params: |
| * Input: - |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: - |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| */ |
| |
| void angel_InitialiseChannels( void ); |
| |
| /* |
| * Function: adp_init_seq |
| * Purpose: initialise sequence numbers and free anyt leftover buffers |
| * |
| * Params: |
| * Input: - |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: - adp_ok if things went ok else an error code |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| */ |
| |
| AdpErrs adp_init_seq(void); |
| |
| /* |
| * Function: angel_ChannelAllocBuffer |
| * Purpose: allocate a buffer that is at least req_size bytes long |
| * |
| * Params: |
| * Input: req_size the minimum size required |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: pointer to allocated buffer, or |
| * NULL if unable to allocate suitable buffer |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| */ |
| |
| p_Buffer angel_ChannelAllocBuffer(unsigned req_size); |
| |
| |
| /* |
| * Function: angel_ChannelReleaseBuffer |
| * Purpose: release a buffer back to the free pool |
| * |
| * Params: |
| * Input: buffer the buffer to release |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: - |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| */ |
| |
| void angel_ChannelReleaseBuffer(p_Buffer buffer); |
| |
| |
| /* |
| * Function: angel_ChannelSend |
| * Purpose: blocking send of a packet via a channel |
| * |
| * Params: |
| * Input: devid Device to use, or CH_DEFAULT_DEV |
| * chanid Channel to use for tx |
| * buffer Pointer to data to send |
| * len Length of data to send |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Transmission completed |
| * CE_BAD_CHAN Channel id invalid |
| * CE_ABANDONED Tx abandoned due to device switch |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| */ |
| |
| ChanError angel_ChannelSend(DeviceID devid, ChannelID chanid, |
| const p_Buffer buffer, unsigned len); |
| |
| |
| /* |
| * Function: angel_ChannelSendAsync |
| * Purpose: asynchronous send of a packet via a channel |
| * |
| * Params: |
| * Input: devid Device to use, or CH_DEFAULT_DEV |
| * chanid Channel to use for tx |
| * buffer Pointer to data to send |
| * len Length of data to send |
| * callback Function to call on completion |
| * callback_data Pointer to pass to callback |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Transmission underway |
| * CE_BAD_CHAN Channel id invalid |
| * CE_ABANDONED Tx abandoned due to device switch |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| * |
| * register an asynchronous send on the given channel |
| * (blocks until send can be commenced) |
| */ |
| |
| typedef void (*ChanTx_CB_Fn)(ChannelID chanid, /* which channel */ |
| void *callback_data); /* as supplied... */ |
| |
| |
| ChanError angel_ChannelSendAsync( DeviceID devid, |
| ChannelID chanid, |
| const p_Buffer buffer, |
| unsigned len, |
| ChanTx_CB_Fn callback, |
| void *callback_data); |
| |
| |
| /* |
| * Function: angel_ChannelRead |
| * Purpose: blocking read of a packet from a channel |
| * |
| * Params: |
| * Input: devid Device to use, or CH_DEFAULT_DEV |
| * chanid Channel to use for rx |
| * Output: buffer The buffer, supplied and filled |
| * len How many bytes there are in the buffer |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Reception successful |
| * CE_BAD_CHAN Channel id invalid |
| * CE_ABANDONED Tx abandoned due to device switch |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| * |
| * Note that in the present version, if an asynchronous read has been |
| * registered, a blocking read will be refused with CE_BUSY. |
| */ |
| ChanError angel_ChannelRead(DeviceID devid, |
| ChannelID chanid, |
| p_Buffer *buffer, |
| unsigned *len); |
| |
| |
| /* |
| * Function: angel_ChannelReadAsync |
| * Purpose: asynchronous read of a packet via a channel |
| * |
| * Params: |
| * Input: devid Device to use, or CH_DEFAULT_DEV |
| * chanid Channel to wait on |
| * callback Function to call on completion, or NULL |
| * callback_data Pointer to pass to callback |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Read request registered |
| * CE_BAD_CHAN Channel id invalid |
| * CE_BUSY Someone else is using the channel |
| * (in a single threaded world) |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| * |
| * Register an asynchronous read on the given channel. There can only be one |
| * async. reader per channel, and blocking reads are not permitted whilst |
| * an async. reader is registered. |
| * |
| * Reader can unregister by specifying NULL as the callback function. |
| */ |
| |
| typedef void (*ChanRx_CB_Fn)(DeviceID devID, /* ID of receiving device */ |
| ChannelID chanID, /* ID of receiving channel */ |
| p_Buffer buff, /* pointer to buffer */ |
| unsigned len, /* length of data */ |
| void *cb_data /* callback data */ |
| ); |
| |
| ChanError angel_ChannelReadAsync(DeviceID devid, |
| ChannelID chanid, |
| ChanRx_CB_Fn callback, |
| void *callback_data); |
| |
| |
| /* |
| * Function: angel_ChannelReadAll |
| * Purpose: register an asynchronous read across all devices |
| * |
| * Params: |
| * Input: chanid Channel to look for (usually HBOOT) |
| * callback Function to call on completion |
| * callback_data Pointer to pass to callback |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Read request registered |
| * CE_BAD_CHAN Channel id invalid |
| * CE_BUSY Someone else is reading all devices |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| * |
| * Register an asynchronous read across all devices. This is a 'fallback', |
| * which will be superseded (temporarily) by a registered reader or blocking |
| * read on a specific device. |
| */ |
| |
| ChanError angel_ChannelReadAll( ChannelID chanid, |
| ChanRx_CB_Fn callback, |
| void *callback_data); |
| |
| |
| |
| /* |
| * Function: angel_ChannelSendThenRead |
| * Purpose: blocking write to followed by read from a channel |
| * |
| * Params: |
| * Input: devid Device to use, or CH_DEFAULT_DEV |
| * chanid Channel to use for rx |
| * In/Out: buffer On entry: the packet to be sent |
| * On return: the packet received |
| * len On entry: length of packet to be sent |
| * On return: length of packet rx'd |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Tx and Reception successful |
| * CE_BAD_CHAN Channel id invalid |
| * CE_ABANDONED Tx abandoned due to device switch |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: - |
| * |
| * Note that in the present version, if an asynchronous read has been |
| * registered, this will be refused with CE_BUSY. |
| */ |
| ChanError angel_ChannelSendThenRead(DeviceID devid, |
| ChannelID chanid, |
| p_Buffer *buffer, |
| unsigned *len); |
| |
| |
| /* |
| * Function: angel_ChannelSelectDevice |
| * Purpose: select the device to be used for all channel comms |
| * |
| * Params: |
| * Input: device ID of device to use as the default |
| * Output: - |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Default device selected |
| * CE_BAD_DEV Invalid device ID |
| * |
| * Reads globals: - |
| * Modifies globals: - |
| * |
| * Other side effects: Any channel operations in progress are |
| * abandoned. |
| * |
| * select the device for all channels comms |
| */ |
| |
| ChanError angel_ChannelSelectDevice(DeviceID device); |
| |
| |
| /* |
| * Function: angel_ChannelReadActiveDevice |
| * Purpose: reads the device id of the currently active device |
| * |
| * Params: |
| * Input: device address of a DeviceID variable |
| * Output: *device ID of device currently being used |
| * In/Out: - |
| * |
| * Returns: CE_OKAY Default device selected |
| */ |
| |
| ChanError angel_ChannelReadActiveDevice(DeviceID *device); |
| |
| #endif /* ndef angel_channels_h */ |
| |
| /* EOF channels.h */ |
