diff options
Diffstat (limited to 'gdb/rdi-share/channels.h')
| -rw-r--r-- | gdb/rdi-share/channels.h | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/gdb/rdi-share/channels.h b/gdb/rdi-share/channels.h new file mode 100644 index 0000000..b43ebc1 --- /dev/null +++ b/gdb/rdi-share/channels.h @@ -0,0 +1,384 @@ +/* + * 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 */ |