gdb/rdi-share/drivers.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: Definitions for device driver interface.
  18  */
  19 #ifndef angsd_drivers_h
  20 #define angsd_drivers_h
  21
  22 #include "rxtx.h"
  23
  24 #ifndef __cplusplus
  25 typedef struct DeviceDescr DeviceDescr;
  26 typedef struct DriverCall DriverCall;
  27 #endif
  28
  29 /*
  30  * used to pass packets across the driver interface
  31  */
  32 struct DriverCall
  33 {
  34     struct data_packet  dc_packet;
  35     void               *dc_context;
  36 };
  37
  38 /*
  39  * used to describe a device driver
  40  */
  41 struct DeviceDescr
  42 {
  43     char  *DeviceName;
  44     int  (*DeviceOpen)(const char *name, const char *arg);
  45     int  (*DeviceMatch)(const char *name, const char *arg);
  46     void (*DeviceClose)(void);
  47     int  (*DeviceRead)(DriverCall *dc, bool block);
  48     int  (*DeviceWrite)(DriverCall *dc);
  49     int  (*DeviceIoctl)(const int opcode, void *args);
  50     void  *SwitcherState;               /* used by switcher interface */
  51 };
  52
  53 /*
  54  *  Function: DeviceOpen
  55  *
  56  *   Purpose: Open a communications device
  57  *
  58  *  Pre-conditions: No previous open is still active
  59  *
  60  *    Params:
  61  *       Input: name    Identifies which device to open.  This can either be
  62  *                      a host specific identifier (e.g. "/dev/ttya",
  63  *                      "COM1:"), or a number which is used to refer to
  64  *                      `standard' interfaces, so "1" would be the first host
  65  *                      interface, "2" the second, and so on.
  66  *
  67  *              arg     Driver specific arguments.  For example, some serial
  68  *                      drivers accept speed and control arguments such as
  69  *                      "9600" or "19200/NO_BREAK".  These arguments are
  70  *                      completely free-form: it is the individual drivers
  71  *                      which do the necessary interpretation.
  72  *
  73  *   Returns:
  74  *          OK: 0
  75  *       Error: -1
  76  */
  77 extern int DeviceOpen(const char *name, const char *arg);
  78
  79 /*
  80  *  Function: DeviceMatch
  81  *
  82  *   Purpose: Check whether parameters are OK to be passed to DeviceOpen
  83  *
  84  *    Params:
  85  *       Input: name    Identifies which device to open.  This can either be
  86  *                      a host specific identifier (e.g. "/dev/ttya",
  87  *                      "COM1:"), or a number which is used to refer to
  88  *                      `standard' interfaces, so "1" would be the first host
  89  *                      interface, "2" the second, and so on.
  90  *
  91  *              arg     Driver specific arguments.  For example, some serial
  92  *                      drivers accept speed and control arguments such as
  93  *                      "9600" or "19200/NO_BREAK".  These arguments are
  94  *                      completely free-form: it is the individual drivers
  95  *                      which do the necessary interpretation.
  96  *
  97  *   Returns:
  98  *          OK: 0
  99  *       Error: -1
 100  */
 101 extern int DeviceMatch(const char *name, const char *arg);
 102
 103 /*
 104  *  Function: DeviceClose
 105  *
 106  *   Purpose: Close a communications device
 107  *
 108  *  Pre-conditions: Device must have been previously opened
 109  *
 110  *    Params: None
 111  *
 112  *   Returns: Nothing
 113  */
 114 extern void DeviceClose(void);
 115
 116 /*
 117  *  Function: DeviceRead
 118  *
 119  *   Purpose: Try to read a complete packet from a communications device.
 120  *              This read must usually be non-blocking, i.e. it should read as
 121  *              many data from the device as needed to complete the packet,
 122  *              but it should not wait if the packet is not complete, and no
 123  *              more data are currently available from the device.
 124  *            As an optimisation the read can optionally block when 'block'
 125  *              is TRUE, but only for a short time.  It is acceptable for the
 126  *              'block' parameter to be ignored in which case all reads
 127  *              should be non-blocking.
 128  *
 129  *  Pre-conditions: Device has been opened via DeviceOpen()
 130  *
 131  *    Params:
 132  *      In/Out: dc      Describes the packet being read (dc->dc_packet);
 133  *                      dc->dc_context is for the driver to store private
 134  *                      context, and is guaranteed to be NULL the first
 135  *                      time DeviceRead is called for a given packet.
 136  *
 137  *          In: block   If TRUE, read may safely block for a short period
 138  *                      of time (say up to 20ms), to avoid high CPU load
 139  *                      whilst waiting for a reply.
 140  *                      If FALSE, read MUST NOT block.
 141  *
 142  *   Returns:
 143  *          OK:  1 (packet is complete)
 144  *               0 (packet is not yet complete)
 145  *       Error: -1 bad packet
 146  *
 147  *   Post-conditions: should a calamatous error occur panic() will be called
 148  */
 149 extern int DeviceRead(DriverCall *dc, bool block);
 150
 151 /*
 152  *  Function: DeviceWrite
 153  *
 154  *   Purpose: Try to write a packet to a communications device.  This write
 155  *              must be non-blocking, i.e. it should write as many data to
 156  *              the device as is immediately possible, but should not wait
 157  *              for space to send any more after that.
 158  *
 159  *  Pre-conditions: Device has been opened via DeviceOpen()
 160  *
 161  *    Params:
 162  *      In/Out: dc      Describes the packet being written (dc->dc_packet);
 163  *                      dc->dc_context is for the driver to store private
 164  *                      context, and is guaranteed to be NULL the first
 165  *                      time DeviceWrite is called for a given packet.
 166  *
 167  *   Returns:
 168  *          OK:  1 (all of the packet has been written)
 169  *               0 (some of the packet remains to be written)
 170  *       Error: -1
 171  */
 172 extern int DeviceWrite(DriverCall *dc);
 173
 174 /*
 175  *  Function: DeviceIoctl
 176  *
 177  *   Purpose: Perform miscellaneous driver operations
 178  *
 179  *  Pre-conditions: Device has been open via DeviceOpen()
 180  *
 181  *    Params:
 182  *       Input: opcode  Reason code indicating the operation to perform
 183  *      In/Out: args    Pointer to opcode-sensitive arguments/result space
 184  *
 185  *   Returns:
 186  *          OK: 0
 187  *       Error: -1
 188  */
 189 extern int DeviceIoctl(const int opcode, void *args);
 190
 191 #endif /* !defined(angsd_drivers_h) */
 192
 193 /* EOF drivers.h */