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 #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(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 263 /* 264 * set filename and enable/disable logginf of ADP packets 265 */ 266 void DevSW_SetLogfile(const char *filename); 267 void DevSW_SetLogEnable(int logEnableFlag); 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif /* ndef angsd_devsw_h */ 274 275 /* EOF devsw.h */ 276