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.2 $
12 *     $Date: 1998/01/08 11:12:03 $
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
25typedef struct DeviceDescr DeviceDescr;
26typedef struct DriverCall DriverCall;
27#endif
28
29/*
30 * used to pass packets across the driver interface
31 */
32struct DriverCall
33{
34    struct data_packet  dc_packet;
35    void               *dc_context;
36};
37
38/*
39 * used to describe a device driver
40 */
41struct 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 */
77extern 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 */
101extern 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 */
114extern 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 */
149extern 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 */
172extern 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 */
189extern int DeviceIoctl(const int opcode, void *args);
190
191#endif /* !defined(angsd_drivers_h) */
192
193/* EOF drivers.h */
194