old-cross-binutils/gdb/rdi-share/channels.h
1999-04-16 01:35:26 +00:00

384 lines
11 KiB
C

/*
* 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 */