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: 1.3 $ 12 * $Date: 2004/12/27 14:00:54 $ 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 */ 194