/* * 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-*- * * 1.1.1.1 * 1999/04/16 01:34:27 * * * 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 */