13 unstall - USB device driver library
16 .ta 8n +8n +8n +8n +8n +8n +8n
19 #include "../lib/usb.h"
23 char* dir; /* path for the endpoint dir */
24 int id; /* usb id for device or ep. number */
25 int dfd; /* descriptor for the data file */
26 int cfd; /* descriptor for the control file */
27 int maxpkt; /* cached from usb description */
28 Usbdev* usb; /* USB description */
29 void* aux; /* for the device driver */
30 void (*free)(void*); /* idem. to release aux */
34 ulong csp; /* USB class/subclass/proto */
35 int vid; /* vendor id */
36 int did; /* product (device) id */
37 int dno; /* device release number */
41 int ls; /* low speed */
42 int class; /* from descriptor */
43 int nconf; /* from descriptor */
44 Conf* conf[Nconf]; /* configurations */
45 Ep* ep[Nep]; /* all endpoints in device */
46 Desc* ddesc[Nddesc]; /* (raw) device specific descriptors */
50 uchar addr; /* endpt address */
51 uchar dir; /* direction, Ein/Eout */
52 uchar type; /* Econtrol, Eiso, Ebulk, Eintr */
53 uchar isotype; /* Eunknown, Easync, Eadapt, Esync */
55 int maxpkt; /* max. packet size */
56 Conf* conf; /* the endpoint belongs to */
57 Iface* iface; /* the endpoint belongs to */
63 void* aux; /* for the driver program */
67 int id; /* interface number */
68 ulong csp; /* USB class/subclass/proto */
71 void* aux; /* for the driver program */
75 int cval; /* value for set configuration */
77 int milliamps; /* maximum power in this config. */
78 Iface* iface[Niface]; /* up to 16 interfaces */
82 Conf* conf; /* where this descriptor was read */
83 Iface* iface; /* last iface before desc in conf. */
84 Ep* ep; /* last endpt before desc in conf. */
85 Altc* altc; /* last alt.c. before desc in conf. */
86 DDesc data; /* unparsed standard USB descriptor */
91 uchar bDescriptorType;
93 /* extra bytes allocated here to keep the rest of it */
96 #define Class(csp) ((csp)&0xff)
97 #define Subclass(csp) (((csp)>>8)&0xff)
98 #define Proto(csp) (((csp)>>16)&0xff)
99 #define CSP(c, s, p) ((c) | ((s)<<8) | ((p)<<16))
101 #define PUT2(p,v) ...
103 #define PUT4(p,v) ...
104 #define dprint if(usbdebug)fprint
105 #define ddprint if(usbdebug > 1)fprint
108 char* classname(int c);
109 void closedev(Dev *d);
110 int configdev(Dev *d);
111 int devctl(Dev *dev, char *fmt, ...);
112 void* emallocz(ulong size, int zero);
113 char* estrdup(char *s);
114 char* hexstr(void *a, int n);
115 char* loaddevstr(Dev *d, int sid);
116 Dev* opendev(char *fn);
117 int opendevdata(Dev *d, int mode);
118 Dev* openep(Dev *d, int id);
119 int unstall(Dev *dev, Dev *ep, int dir);
120 int usbcmd(Dev *d, int type, int req,
121 int value, int index, uchar *data, int count);
124 extern int usbdebug; /* more messages for bigger values */
127 This library provides convenience structures and functions to write
129 It is not intended for user programs using USB devices.
132 for a description of the interfaces provided for that purpose.
136 to perform I/O through USB as well as on
138 to perform the initial configuration for the device's setup endpoint.
139 The rest of the work is up to the driver and is where this library may help.
141 An endpoint as provided by
146 The setup endpoint for a
147 device represents the USB device, because it is the means to
148 configure and operate the device.
149 This structure is reference counted.
152 adjust the number of references to one, initially.
153 The driver is free to call
157 to add references and
159 to drop references (and release resources when the last one vanishes).
160 As an aid to the driver, the field
162 may keep driver-specific data and the function
164 will be called (if not null) to release the
166 structure when the reference count goes down to zero.
169 holds the path for the endpoint's directory.
173 keeps the device number for setup endpoints and the endpoint number
174 for all other endpoints.
175 For example, it would be
183 It is easy to remember this because the former is created to operate
184 on the device, while the later has been created as a particular endpoint
192 control file descriptors, respectively.
195 is created the control file is open, initially.
197 file requires calling
199 with the appropriate mode.
201 When the device configuration information has been loaded (see below),
203 holds the maximum packet size (in bytes) for the endpoint and
205 keeps the rest of the USB information.
207 Most of the information in
210 various device and configuration descriptors provided by the device,
211 by calling one of the functions described later.
212 Only descriptors unknown
213 to the library are kept unparsed at
215 as an aid for the driver
216 (which should know how to parse them and what to do with the information).
222 for the endpoint with directory
224 Usually, the endpoint is a setup endpoint representing a device. The endpoint
225 control file is open, but the data file is not. The USB description is void.
226 In most cases drivers call
230 and do not call this function directly.
233 opens the data file for the device supplied and
234 loads and parses its configuration information.
235 After calling it, the device is ready for I/O and the USB description in
239 Control requests for an endpoint may be written by calling
243 It is better not to call
245 directly because the control request should be issued as a single
250 for a list of available control requests (not to be confused with
251 USB control transfers performed on a control endpoint).
254 opens the data file for the device according to the given
256 The mode must match that of the endpoint, doing otherwise is considered
258 Actual I/O is performed by reading/writing the descriptor kept in the
263 For control endpoints,
264 it is not necessary to call
271 issues a USB control request to the device
273 (not to be confused with a
275 control request sent to its control file).
277 retries the control request several times upon failure because some devices
279 The format of requests is fixed per the USB standard:
281 is the type of request and
283 identifies the request. Arguments
287 are parameters to the request and the last two arguments,
300 if no transfer (other than the control request) has to take place.
301 The library header file includes numerous symbols defined to help writing
302 the type and arguments for a request.
304 The return value from
306 is the number of bytes transferred, zero to indicate a stall and -1
307 to indicate an error.
309 A common request is to unstall an endpoint that has been stalled
310 due to some reason by the device (eg., when read or write indicate
311 a count of zero bytes read or written on the endpoint). The function
314 It is given the device that stalled the endpoint,
319 and the direction of the stall (one of
323 The function takes care of notifying the device of the unstall as well
324 as notifying the kernel.
327 returns the class part of the number given, representing a CSP.
329 does the same for the device subclass and
334 which builds a CSP from the device class, subclass, and protocol.
337 knows the name (for those with constants in the library header file).
343 get and put a (little-endian) two-byte value and are useful to
344 parse descriptors and replies for control requests.
354 but abort program operation upon failure.
358 is a format routine suitable for
365 returns a string representing a dump (in hexadecimal) of
369 The string is allocated using
371 and memory must be released by the caller.
374 returns the string obtained by reading the device string descriptor number
377 .B /sys/src/cmd/nusb/lib
382 Not heavily exercised yet.