gdb/rdi-share/devclnt.h

   1 /*
   2  * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
   3  *
   4  * This software may be freely used, copied, modified, and distributed
   5  * provided that the above copyright notice is preserved in all copies of the
   6  * software.
   7  */
   8
   9 /* -*-C-*-
  10  *
  11  * $Revision$
  12  *     $Date$
  13  *
  14  *
  15  *   Project: ANGEL
  16  *
  17  *     Title: Public client interface to devices
  18  */
  19
  20 #ifndef angel_devclnt_h
  21 #define angel_devclnt_h
  22
  23 /*
  24  * This header exports the public interface to Angel-compliant device
  25  * drivers.
  26  *
  27  * They are intended to be used solely by Angel, not by the User
  28  * Application.  See devappl.h for the User Application interface to
  29  * the device drivers.
  30  */
  31
  32 #include "devices.h"
  33
  34 /* General purpose constants, macros, enums, typedefs */
  35
  36 /*
  37  * possible channels at device level
  38  *
  39  * XXX
  40  *
  41  * these are used as array indices, so be specific about their values
  42  */
  43 typedef enum DevChanID {
  44   DC_DBUG = 0,                  /* reliable debug packets
  45                                  * containing SDBG, CLIB,UDBG, etc.) */
  46   DC_APPL = 1,                  /* application packets */
  47   DC_NUM_CHANNELS
  48 } DevChanID;
  49
  50 /* Publically-accessible globals */
  51 /* none */
  52
  53 /* Public functions */
  54
  55 /*
  56  * Function: angel_DeviceWrite
  57  *  Purpose: The main entry point for asynchronous writes to a device.
  58  *
  59  *   Params:
  60  *              Input: devID     index of the device to write to
  61  *                     buff      data to write
  62  *                     length    how much data to write
  63  *                     callback  callback here when write finished
  64  *                                or error
  65  *                     cb_data   data to be passed to callback
  66  *                     chanID    device channel to use
  67  *             Output: -
  68  *             In/Out: -
  69  *
  70  *            Returns: DE_OKAY     write request is underway
  71  *                     DE_NO_DEV   no such device
  72  *                     DE_BAD_DEV  device does not support angel writes
  73  *                     DE_BAD_CHAN no such device channel
  74  *                     DE_BUSY     device busy with another write
  75  *                     DE_INVAL    silly length
  76  *
  77  *      Reads globals: -
  78  *   Modifies globals: -
  79  *
  80  * Other side effects: -
  81  *
  82  * Commence asynchronous transmission of a buffer on a device.  The
  83  * callback will occur when the write completes or if there is an
  84  * error.
  85  *
  86  * This must be called for each packet to be sent.
  87  */
  88
  89 DevError angel_DeviceWrite(DeviceID devID, p_Buffer buff,
  90                            unsigned length, DevWrite_CB_Fn callback,
  91                            void *cb_data, DevChanID chanID);
  92
  93
  94 /*
  95  * Function: angel_DeviceRegisterRead
  96  *  Purpose: The main entry point for asynchronous reads from a device.
  97  *
  98  *   Params:
  99  *              Input: devID     index of the device to read from
 100  *                     callback  callback here when read finished
 101  *                                or error
 102  *                     cb_data   data to be passed to callback
 103  *                     get_buff  callback to be used to acquire buffer
 104  *                                for incoming packets
 105  *                     getb_data data to be passed to get_buff
 106  *                     chanID    device channel to use
 107  *             Output: -
 108  *             In/Out: -
 109  *
 110  *            Returns: DE_OKAY     read request is underway
 111  *                     DE_NO_DEV   no such device
 112  *                     DE_BAD_DEV  device does not support angel reads
 113  *                     DE_BAD_CHAN no such device channel
 114  *                     DE_BUSY     device busy with another read
 115  *                     DE_INVAL    silly length
 116  *
 117  *      Reads globals: -
 118  *   Modifies globals: -
 119  *
 120  * Other side effects: -
 121  *
 122  * Register asynchronous packet read from a device.  The callback will
 123  * occur when the read completes or if there is an error.
 124  *
 125  * This is persistent: the read remains registered for all incoming
 126  * packets on the device channel.
 127  */
 128
 129 DevError angel_DeviceRegisterRead(DeviceID devID,
 130                                   DevRead_CB_Fn callback, void *cb_data,
 131                                   DevGetBuff_Fn get_buff, void *getb_data,
 132                                   DevChanID chanID);
 133
 134
 135 /*
 136  * Function: angel_DeviceControl
 137  *  Purpose: Call a control function for a device
 138  *
 139  *   Params:
 140  *              Input: devID     index of the device to control to
 141  *                     op        operation to perform
 142  *                     arg       parameter depending on op
 143  *
 144  *            Returns: DE_OKAY     control request is underway
 145  *                     DE_NO_DEV   no such device
 146  *                     DE_BAD_OP   device does not support operation
 147  *
 148  *      Reads globals: -
 149  *   Modifies globals: -
 150  *
 151  * Other side effects: -
 152  *
 153  * Have a device perform a control operation.  Extra parameters vary
 154  * according to the operation requested.
 155  */
 156
 157 DevError angel_DeviceControl(DeviceID devID, DeviceControl op, void *arg);
 158
 159
 160 /*
 161  * Function: angel_ReceiveMode
 162  *  Purpose: enable or disable reception across all devices
 163  *
 164  *   Params:
 165  *              Input: mode   choose enable or disable
 166  *
 167  * Pass the mode parameter to the receive_mode control method of each device
 168  */
 169
 170 void angel_ReceiveMode(DevRecvMode mode);
 171
 172
 173 /*
 174  * Function: angel_ResetDevices
 175  *  Purpose: reset all devices
 176  *
 177  *   Params: none
 178  *
 179  * Call the reset control method for each device
 180  */
 181
 182 void angel_ResetDevices(void);
 183
 184
 185 /*
 186  * Function: angel_InitialiseDevices
 187  *  Purpose: initialise the device driver layer
 188  *
 189  *   Params: none
 190  *
 191  * Set up the device driver layer and call the init method for each device
 192  */
 193
 194 void angel_InitialiseDevices(void);
 195
 196
 197 /*
 198  * Function: angel_IsAngelDevice
 199  *  Purpose: Find out if a device supports Angel packets
 200  *
 201  *   Params:
 202  *              Input: devID     index of the device to control to
 203  *
 204  *            Returns: TRUE      supports Angel packets
 205  *                     FALSE     raw device
 206  *
 207  *      Reads globals: -
 208  *   Modifies globals: -
 209  *
 210  * Other side effects: -
 211  */
 212
 213 bool angel_IsAngelDevice(DeviceID devID);
 214
 215
 216 #if !defined(MINIMAL_ANGEL) || MINIMAL_ANGEL == 0
 217
 218 /*
 219  * Function: angel_ApplDeviceHandler
 220  *  Purpose: The entry point for User Application Device Driver requests
 221  *           in a full functiionality version of Angel.
 222  *           It will never be called directly by the User Application,
 223  *           but gets called indirectly, via the SWI handler.
 224  *
 225  *  Params:
 226  *      Input: swi_r0    Argument to SWI indicating that
 227  *                       angel_ApplDeviceHandler was to be called.  This
 228  *                       will not be used in this function, but is needed
 229  *                       by the SWI handler.
 230  *             arg_blk   pointer to block of arguments
 231  *                       arg_blk[0] is one of
 232  *                       angel_SWIreason_ApplDevice_{Read,Write,Yield}
 233  *                       which indicates which angel_Device* fn is to
 234  *                       be called.  arg_blk[1] - arg_blk[n] are the
 235  *                       arguments to the corresponding
 236  *                       angel_ApplDevice* function.
 237  *             Output: -
 238  *             In/Out: -
 239  *
 240  *            Returns:   whatever the specified angel_Device* function
 241  *                       returns.
 242  *
 243  *      Reads globals: -
 244  *   Modifies globals: -
 245  *
 246  * Other side effects: -
 247  *
 248  * This has the side effects of angel_Device{Read,Write,Yield}
 249  * depending upon which is operation is specified as described above.
 250  */
 251
 252 DevError angel_ApplDeviceHandler(
 253   unsigned swi_r0, unsigned *arg_blk
 254 );
 255
 256 #endif /* ndef MINIMAL_ANGEL */
 257
 258 #endif /* ndef angel_devclnt_h */
 259
 260 /* EOF devclnt.h */