gdb/rdi-share/devsw.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 #ifndef angsd_devsw_h
  16 #define angsd_devsw_h
  17
  18 #include "devclnt.h"
  19 #include "adperr.h"
  20 #include "drivers.h"
  21
  22 #ifndef __cplusplus
  23 typedef struct Packet Packet;
  24 typedef struct DevSWState DevSWState;
  25 #endif
  26
  27 /*
  28  * the basic structure used for passing packets around
  29  */
  30 struct Packet
  31 {
  32     struct Packet *pk_next;             /* XXX first field in struct */
  33     unsigned int   pk_length;
  34     unsigned char *pk_buffer;
  35 };
  36
  37 /*
  38  * control structure, used for maintaining device switcher state
  39  */
  40 struct DevSWState
  41 {
  42     unsigned int  ds_opendevchans;      /* bitmap of open device channels */
  43
  44     /*
  45      * queue of packets read for the various device channels
  46      */
  47     Packet       *ds_readqueue[DC_NUM_CHANNELS];
  48
  49     /*
  50      * structures for managing active read and write operations
  51      */
  52     Packet       *ds_nextreadpacket;
  53     DriverCall    ds_activeread;
  54     DriverCall    ds_activewrite;
  55 };
  56
  57 #ifdef __cplusplus
  58     extern "C" {
  59 #endif
  60
  61 /*
  62  *  Function: DevSW_AllocatePacket
  63  *   Purpose: Claim some memory to hold a struct Packet, and the buffer for
  64  *              that packet.
  65  *
  66  *    Params:
  67  *       Input: length  Size of the buffer in struct Packet.
  68  *
  69  *   Returns:
  70  *          OK: Pointer to the newly malloc()ed Packet.
  71  *       Error: NULL
  72  */
  73 Packet *DevSW_AllocatePacket(const unsigned int length);
  74
  75 /*
  76  *  Function: DevSW_FreePacket
  77  *   Purpose: Free the memory associated with a struct Packet.
  78  *
  79  *  Pre-conditions The structure must have been originally claimed
  80  *                      via DevSW_AllocatePacket.
  81  *
  82  *    Params:
  83  *       Input: pk      The packet to be freed.
  84  *
  85  *   Returns: Nothing
  86  */
  87 void DevSW_FreePacket(Packet *pk);
  88
  89 /*
  90  *  Function: DevSW_Open
  91  *   Purpose: Open the specified device driver
  92  *
  93  *    Params:
  94  *       Input: name    Identifies which device to open.  This can either be
  95  *                      a host specific identifier (e.g. "/dev/ttya",
  96  *                      "COM1:"), or a number which is used to refer to
  97  *                      `standard' interfaces, so "1" would be the first host
  98  *                      interface, "2" the second, and so on.
  99  *
 100  *              arg     Driver specific arguments.  For example, some serial
 101  *                      drivers accept speed and control arguments such as
 102  *                      "9600" or "19200/NO_BREAK".  These arguments are
 103  *                      completely free-form: it is the individual drivers
 104  *                      which do the necessary interpretation.
 105  *
 106  *              type    The type of packet the caller is interested in.  Only
 107  *                      one open is allowed for each type of packet.
 108  *
 109  *      In/Out: device  The device driver to open
 110  *
 111  *   Returns:
 112  *          OK: adp_ok
 113  *       Error: adp_device_open_failed
 114  *              adp_device_already_open
 115  *              adp_malloc_failure
 116  */
 117 AdpErrs DevSW_Open(DeviceDescr *device, const char *name, const char *arg,
 118                    const DevChanID type);
 119
 120 /*
 121  *  Function: DevSW_Match
 122  *   Purpose: Minimal veneer for DeviceMatch
 123  *
 124  *    Params:
 125  *       Input: device  The device driver to match.
 126  *
 127  *              name    Identifies which device to open.  This can either be
 128  *                      a host specific identifier (e.g. "/dev/ttya",
 129  *                      "COM1:"), or a number which is used to refer to
 130  *                      `standard' interfaces, so "1" would be the first host
 131  *                      interface, "2" the second, and so on.
 132  *
 133  *              arg     Driver specific arguments.  For example, some serial
 134  *                      drivers accept speed and control arguments such as
 135  *                      "9600" or "19200/NO_BREAK".  These arguments are
 136  *                      completely free-form: it is the individual drivers
 137  *                      which do the necessary interpretation.
 138  *
 139  *   Returns:
 140  *          OK: adp_ok
 141  *       Error: adp_failed
 142  */
 143 AdpErrs DevSW_Match(const DeviceDescr *device, const char *name,
 144                     const char *arg);
 145
 146 /*
 147  *  Function: DevSW_Close
 148  *   Purpose: Close the specified device driver. All packets of the type
 149  *              used by the caller held within the switching layer will
 150  *              be discarded.
 151  *
 152  *  Pre-conditions: Device must have been previously opened.
 153  *
 154  *    Params:
 155  *       Input: device  The device driver to close
 156  *
 157  *              type    The type of packet the caller was interested in.
 158  *
 159  *   Returns:
 160  *          OK: adp_ok
 161  *       Error: adp_device_not_open
 162  */
 163 AdpErrs DevSW_Close(const DeviceDescr *device, const DevChanID type);
 164
 165 /*
 166  *  Function: DevSW_Read
 167  *   Purpose: Read a packet of appropriate type from the device driver
 168  *
 169  *    Params:
 170  *       Input: device  The device driver to read packet from.
 171  *
 172  *              type    The type of packet the caller is interested in.
 173  *
 174  *      Output: packet  Pointer to new packet (if one is available)
 175  *              NULL (if no complete packet is available)
 176  *
 177  *       Input: block   If TRUE, read may safely block for a short period
 178  *                      of time (say up to 20ms), to avoid high CPU load
 179  *                      whilst waiting for a reply.
 180  *                      If FALSE, read MUST NOT block.
 181  *
 182  *   Returns:
 183  *          OK: adp_ok
 184  *       Error: adp_bad_packet
 185  *
 186  * Post-conditions: The calling function is responsible for freeing the
 187  *                      resources used by the packet when it is no longer
 188  *                      needed.
 189  */
 190 AdpErrs DevSW_Read(const DeviceDescr *device, const DevChanID type,
 191                    Packet **packet, bool block);
 192
 193 /*
 194  *  Function: DevSW_Write
 195  *   Purpose: Try to write a packet to the device driver.  The write will
 196  *              be bounced if another write is still in progress.
 197  *
 198  *    Params:
 199  *       Input: device  The device driver to write a packet to.
 200  *
 201  *              packet  The packet to be written.
 202  *
 203  *              type    The type to be assigned to the packet.
 204  *
 205  *   Returns:
 206  *          OK: adp_ok
 207  *       Error: adp_illegal_args
 208  *              adp_write_busy
 209  *
 210  * Post-conditions: The calling function retains "ownership" of the packet,
 211  *                      i.e. it is responsible for freeing the resources used
 212  *                      by the packet when it is no longer needed.
 213  */
 214 AdpErrs DevSW_Write(const DeviceDescr *device, Packet *packet, DevChanID type);
 215
 216 /*
 217  *  Function: DevSW_FlushPendingWrite
 218  *   Purpose: If a write is in progress, give it a chance to finish.
 219  *
 220  *    Params:
 221  *       Input: device  The device driver to flush.
 222  *
 223  *   Returns:
 224  *              adp_ok           no pending write, or write flushed completely
 225  *              adp_write_busy   pending write not flushed completely
 226  */
 227 AdpErrs DevSW_FlushPendingWrite(const DeviceDescr *device);
 228
 229 /*
 230  *  Function: DevSW_Ioctl
 231  *   Purpose: Perform miscellaneous control operations.  This is a minimal
 232  *              veneer to DeviceIoctl.
 233  *
 234  *    Params:
 235  *       Input: device  The device driver to control.
 236  *
 237  *              opcode  Reason code indicating the operation to perform.
 238  *
 239  *      In/Out: args    Pointer to opcode-sensitive arguments/result space.
 240  *
 241  *   Returns:
 242  *          OK: adp_ok
 243  *       Error: adp_failed
 244  */
 245 AdpErrs DevSW_Ioctl(const DeviceDescr *device, const int opcode, void *args);
 246
 247 /*
 248  *  Function: DevSW_WriteFinished
 249  *   Purpose: Return TRUE if the active device has finished writing
 250  *              the last packet to be sent, or FALSE if a packet is still
 251  *              being transmitted.
 252  *
 253  *    Params:
 254  *       Input: device  The device driver to check.
 255  *
 256  *   Returns:
 257  *        TRUE: write finished or inactive
 258  *       FALSE: write in progress
 259  */
 260 bool DevSW_WriteFinished(const DeviceDescr *device);
 261
 262 #ifdef __cplusplus
 263     }
 264 #endif
 265
 266 #endif /* ndef angsd_devsw_h */
 267
 268 /* EOF devsw.h */