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

260 lines
7.6 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: Public client interface to devices
*/
#ifndef angel_devclnt_h
#define angel_devclnt_h
/*
* This header exports the public interface to Angel-compliant device
* drivers.
*
* They are intended to be used solely by Angel, not by the User
* Application. See devappl.h for the User Application interface to
* the device drivers.
*/
#include "devices.h"
/* General purpose constants, macros, enums, typedefs */
/*
* possible channels at device level
*
* XXX
*
* these are used as array indices, so be specific about their values
*/
typedef enum DevChanID {
DC_DBUG = 0, /* reliable debug packets
* containing SDBG, CLIB,UDBG, etc.) */
DC_APPL = 1, /* application packets */
DC_NUM_CHANNELS
} DevChanID;
/* Publically-accessible globals */
/* none */
/* Public functions */
/*
* Function: angel_DeviceWrite
* Purpose: The main entry point for asynchronous writes to a device.
*
* Params:
* Input: devID index of the device to write to
* buff data to write
* length how much data to write
* callback callback here when write finished
* or error
* cb_data data to be passed to callback
* chanID device channel to use
* Output: -
* In/Out: -
*
* Returns: DE_OKAY write request is underway
* DE_NO_DEV no such device
* DE_BAD_DEV device does not support angel writes
* DE_BAD_CHAN no such device channel
* DE_BUSY device busy with another write
* DE_INVAL silly length
*
* Reads globals: -
* Modifies globals: -
*
* Other side effects: -
*
* Commence asynchronous transmission of a buffer on a device. The
* callback will occur when the write completes or if there is an
* error.
*
* This must be called for each packet to be sent.
*/
DevError angel_DeviceWrite(DeviceID devID, p_Buffer buff,
unsigned length, DevWrite_CB_Fn callback,
void *cb_data, DevChanID chanID);
/*
* Function: angel_DeviceRegisterRead
* Purpose: The main entry point for asynchronous reads from a device.
*
* Params:
* Input: devID index of the device to read from
* callback callback here when read finished
* or error
* cb_data data to be passed to callback
* get_buff callback to be used to acquire buffer
* for incoming packets
* getb_data data to be passed to get_buff
* chanID device channel to use
* Output: -
* In/Out: -
*
* Returns: DE_OKAY read request is underway
* DE_NO_DEV no such device
* DE_BAD_DEV device does not support angel reads
* DE_BAD_CHAN no such device channel
* DE_BUSY device busy with another read
* DE_INVAL silly length
*
* Reads globals: -
* Modifies globals: -
*
* Other side effects: -
*
* Register asynchronous packet read from a device. The callback will
* occur when the read completes or if there is an error.
*
* This is persistent: the read remains registered for all incoming
* packets on the device channel.
*/
DevError angel_DeviceRegisterRead(DeviceID devID,
DevRead_CB_Fn callback, void *cb_data,
DevGetBuff_Fn get_buff, void *getb_data,
DevChanID chanID);
/*
* Function: angel_DeviceControl
* Purpose: Call a control function for a device
*
* Params:
* Input: devID index of the device to control to
* op operation to perform
* arg parameter depending on op
*
* Returns: DE_OKAY control request is underway
* DE_NO_DEV no such device
* DE_BAD_OP device does not support operation
*
* Reads globals: -
* Modifies globals: -
*
* Other side effects: -
*
* Have a device perform a control operation. Extra parameters vary
* according to the operation requested.
*/
DevError angel_DeviceControl(DeviceID devID, DeviceControl op, void *arg);
/*
* Function: angel_ReceiveMode
* Purpose: enable or disable reception across all devices
*
* Params:
* Input: mode choose enable or disable
*
* Pass the mode parameter to the receive_mode control method of each device
*/
void angel_ReceiveMode(DevRecvMode mode);
/*
* Function: angel_ResetDevices
* Purpose: reset all devices
*
* Params: none
*
* Call the reset control method for each device
*/
void angel_ResetDevices(void);
/*
* Function: angel_InitialiseDevices
* Purpose: initialise the device driver layer
*
* Params: none
*
* Set up the device driver layer and call the init method for each device
*/
void angel_InitialiseDevices(void);
/*
* Function: angel_IsAngelDevice
* Purpose: Find out if a device supports Angel packets
*
* Params:
* Input: devID index of the device to control to
*
* Returns: TRUE supports Angel packets
* FALSE raw device
*
* Reads globals: -
* Modifies globals: -
*
* Other side effects: -
*/
bool angel_IsAngelDevice(DeviceID devID);
#if !defined(MINIMAL_ANGEL) || MINIMAL_ANGEL == 0
/*
* Function: angel_ApplDeviceHandler
* Purpose: The entry point for User Application Device Driver requests
* in a full functiionality version of Angel.
* It will never be called directly by the User Application,
* but gets called indirectly, via the SWI handler.
*
* Params:
* Input: swi_r0 Argument to SWI indicating that
* angel_ApplDeviceHandler was to be called. This
* will not be used in this function, but is needed
* by the SWI handler.
* arg_blk pointer to block of arguments
* arg_blk[0] is one of
* angel_SWIreason_ApplDevice_{Read,Write,Yield}
* which indicates which angel_Device* fn is to
* be called. arg_blk[1] - arg_blk[n] are the
* arguments to the corresponding
* angel_ApplDevice* function.
* Output: -
* In/Out: -
*
* Returns: whatever the specified angel_Device* function
* returns.
*
* Reads globals: -
* Modifies globals: -
*
* Other side effects: -
*
* This has the side effects of angel_Device{Read,Write,Yield}
* depending upon which is operation is specified as described above.
*/
DevError angel_ApplDeviceHandler(
unsigned swi_r0, unsigned *arg_blk
);
#endif /* ndef MINIMAL_ANGEL */
#endif /* ndef angel_devclnt_h */
/* EOF devclnt.h */