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.4 $
12 *     $Date: 2000/01/04 14:49:02 $
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
23typedef struct Packet Packet;
24typedef struct DevSWState DevSWState;
25#endif
26
27/*
28 * the basic structure used for passing packets around
29 */
30struct 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 */
40struct 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 */
73Packet *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 */
87void 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 */
117AdpErrs 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 */
143AdpErrs 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 */
163AdpErrs 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 */
190AdpErrs 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 */
214AdpErrs 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 */
227AdpErrs 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 */
245AdpErrs 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 */
260bool DevSW_WriteFinished(const DeviceDescr *device);
261
262
263/*
264 * set filename and enable/disable logginf of ADP packets
265 */
266void DevSW_SetLogfile(const char *filename);
267void DevSW_SetLogEnable(int logEnableFlag);
268
269#ifdef __cplusplus
270    }
271#endif
272
273#endif /* ndef angsd_devsw_h */
274
275/* EOF devsw.h */
276