| 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 */ |