Deleted Added
sdiff udiff text old ( 190100 ) new ( 192551 )
full compact
usb.4 (190100) usb.4 (192551)
1.\" Copyright (c) 1997, 1998
2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.

--- 11 unchanged lines hidden (view full) ---

20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
26.\" THE POSSIBILITY OF SUCH DAMAGE.
27.\"
1.\" Copyright (c) 1997, 1998
2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.

--- 11 unchanged lines hidden (view full) ---

20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
26.\" THE POSSIBILITY OF SUCH DAMAGE.
27.\"
28.\" $FreeBSD: head/share/man/man4/usb.4 190100 2009-03-19 20:33:26Z thompsa $
28.\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
29.\"
29.\"
30.Dd November 22, 2006
30.\" Redistribution and use in source and binary forms, with or without
31.\" modification, are permitted provided that the following conditions
32.\" are met:
33.\" 1. Redistributions of source code must retain the above copyright
34.\" notice, this list of conditions and the following disclaimer.
35.\" 2. Redistributions in binary form must reproduce the above copyright
36.\" notice, this list of conditions and the following disclaimer in the
37.\" documentation and/or other materials provided with the distribution.
38.\"
39.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
40.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
42.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
43.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
45.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
48.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49.\" SUCH DAMAGE.
50.\"
51.\" $FreeBSD: head/share/man/man4/usb.4 192551 2009-05-21 17:26:20Z thompsa $
52.\"
53.Dd May 20, 2009
31.Dt USB 4
32.Os
33.Sh NAME
34.Nm usb
35.Nd Universal Serial Bus
36.Sh SYNOPSIS
37To compile this driver into the kernel,
38place the following line in your
39kernel configuration file:
40.Bd -ragged -offset indent
41.Cd "device usb"
42.Ed
43.Pp
44Alternatively, to load the driver as a
45module at boot time, place the following line in
46.Xr loader.conf 5 :
47.Bd -literal -offset indent
48usb_load="YES"
49.Ed
54.Dt USB 4
55.Os
56.Sh NAME
57.Nm usb
58.Nd Universal Serial Bus
59.Sh SYNOPSIS
60To compile this driver into the kernel,
61place the following line in your
62kernel configuration file:
63.Bd -ragged -offset indent
64.Cd "device usb"
65.Ed
66.Pp
67Alternatively, to load the driver as a
68module at boot time, place the following line in
69.Xr loader.conf 5 :
70.Bd -literal -offset indent
71usb_load="YES"
72.Ed
50.Pp
51.In dev/usb/usb.h
52.In dev/usb/usbhid.h
73.Sh USERLAND PROGRAMMING
74USB functions can be accessed from userland through the libusb library.
75See
76.Xr libusb 3
77for more information.
53.Sh DESCRIPTION
54.Fx
55provides machine-independent bus support and drivers for
56.Tn USB
78.Sh DESCRIPTION
79.Fx
80provides machine-independent bus support and drivers for
81.Tn USB
57devices.
82devices in host and device side mode.
58.Pp
59The
60.Nm
83.Pp
84The
85.Nm
61driver has three layers: the controller, the bus, and the
62device layer.
86driver has three layers:
87.Bl -tag
88.It USB Controller (Bus)
89.It USB Device
90.It USB Driver
91.El
92.Pp
63The controller attaches to a physical bus
93The controller attaches to a physical bus
64(like
65.Xr pci 4 ) .
94like
95.Xr pci 4 .
66The
67.Tn USB
68bus attaches to the controller, and the root hub attaches
69to the controller.
70Any devices attached to the bus will attach to the root hub
71or another hub attached to the
72.Tn USB
73bus.
74.Pp
75The
76.Nm uhub
77device will always be present as it is needed for the
78root hub.
79.Sh INTRODUCTION TO USB
80The
81.Tn USB
96The
97.Tn USB
98bus attaches to the controller, and the root hub attaches
99to the controller.
100Any devices attached to the bus will attach to the root hub
101or another hub attached to the
102.Tn USB
103bus.
104.Pp
105The
106.Nm uhub
107device will always be present as it is needed for the
108root hub.
109.Sh INTRODUCTION TO USB
110The
111.Tn USB
82is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
112is a system where external devices can be connected to a PC.
113The most common USB speeds are:
114.Bl -tag
115.It Low Speed (1.5MBit/sec)
116.It Full Speed (12MBit/sec)
117.It High Speed (480MBit/sec)
118.El
119.Pp
83Each
84.Tn USB
120Each
121.Tn USB
85has a host controller that is the master of the bus;
86all other devices on the bus only speak when spoken to.
122has a USB controller that is the master of the bus.
123The physical communication is simplex which means the host controller only communicates with one USB device at a time.
87.Pp
124.Pp
88There can be up to 127 devices (apart from the host controller)
89on a bus, each with its own address.
125There can be up to 127 devices connected to an USB HUB tree.
90The addresses are assigned
91dynamically by the host when each device is attached to the bus.
92.Pp
93Within each device there can be up to 16 endpoints.
94Each endpoint
95is individually addressed and the addresses are static.
96Each of these endpoints will communicate in one of four different modes:
97.Em control , isochronous , bulk ,

--- 13 unchanged lines hidden (view full) ---

111called alternate settings, which affects how it operates.
112Different alternate settings can have different endpoints
113within it.
114.Pp
115A device may operate in different configurations.
116Depending on the
117configuration, the device may present different sets of endpoints
118and interfaces.
126The addresses are assigned
127dynamically by the host when each device is attached to the bus.
128.Pp
129Within each device there can be up to 16 endpoints.
130Each endpoint
131is individually addressed and the addresses are static.
132Each of these endpoints will communicate in one of four different modes:
133.Em control , isochronous , bulk ,

--- 13 unchanged lines hidden (view full) ---

147called alternate settings, which affects how it operates.
148Different alternate settings can have different endpoints
149within it.
150.Pp
151A device may operate in different configurations.
152Depending on the
153configuration, the device may present different sets of endpoints
154and interfaces.
119.\" .Pp
120.\" Each device located on a hub has several
121.\" .Xr config 8
122.\" locators:
123.\" .Bl -tag -compact -width xxxxxx
124.\" .It Cd port
125.\" this is the number of the port on the closest upstream hub.
126.\" .It Cd configuration
127.\" this is the configuration the device must be in for this driver to attach.
128.\" This locator does not set the configuration; it is iterated by the bus
129.\" enumeration.
130.\" .It Cd interface
131.\" this is the interface number within a device that an interface driver
132.\" attaches to.
133.\" .It Cd vendor
134.\" this is the 16 bit vendor id of the device.
135.\" .It Cd product
136.\" this is the 16 bit product id of the device.
137.\" .It Cd release
138.\" this is the 16 bit release (revision) number of the device.
139.\" .El
140.\" The first locator can be used to pin down a particular device
141.\" according to its physical position in the device tree.
142.\" The last three locators can be used to pin down a particular
143.\" device according to what device it actually is.
144.Pp
145The bus enumeration of the
146.Tn USB
147bus proceeds in several steps:
148.Bl -enum
149.It
155.Pp
156The bus enumeration of the
157.Tn USB
158bus proceeds in several steps:
159.Bl -enum
160.It
150Any device specific driver can attach to the device.
161Any interface specific driver can attach to the device.
151.It
162.It
152If none is found, any device class specific driver can attach.
153.It
154If none is found, all configurations are iterated over.
155For each configuration, all the interfaces are iterated over, and interface
156drivers can attach.
157If any interface driver attached in a certain
158configuration, the iteration over configurations is stopped.
159.It
160If still no drivers have been found, the generic
161.Tn USB
162driver can attach.
163If none is found, generic interface class drivers can attach.
163.El
164.El
164.Sh USB CONTROLLER INTERFACE
165Use the following to get access to the
166.Tn USB
167specific structures and defines.
165.Sh USB KERNEL PROGRAMMING
166Here is a list of commonly used functions:
168.Pp
167.Pp
169The
170.Pa /dev/usb Ns Ar N
171can be opened and a few operations can be performed on it.
172The
173.Xr poll 2
174system call will say that I/O is possible on the controller device when a
175.Tn USB
176device has been connected or disconnected to the bus.
168.
169.Ft "usb2_error_t"
170.Fo "usb2_transfer_setup"
171.Fa "udev"
172.Fa "ifaces"
173.Fa "pxfer"
174.Fa "setup_start"
175.Fa "n_setup"
176.Fa "priv_sc"
177.Fa "priv_mtx"
178.Fc
179.
177.Pp
180.Pp
178The following
179.Xr ioctl 2
180commands are supported on the controller device:
181.Bl -tag -width xxxxxx
182.It Dv USB_DISCOVER
183This command will cause a complete bus discovery to be initiated.
184If any devices attached or detached from the bus they will be
185processed during this command.
186This is the only way that new devices are found on the bus.
187.It Dv USB_DEVICEINFO Vt "struct usb_device_info"
188This command can be used to retrieve some information about a device
189on the bus.
190The
191.Va udi_addr
192field should be filled before the call and the other fields will
193be filled by information about the device on that address.
194Should no such device exist, an error is reported.
195.Bd -literal
196#define USB_MAX_DEVNAMES 4
197#define USB_MAX_DEVNAMELEN 16
198struct usb_device_info {
199 u_int8_t udi_bus;
200 u_int8_t udi_addr; /* device address */
201 usb_event_cookie_t udi_cookie;
202 char udi_product[USB_MAX_STRING_LEN];
203 char udi_vendor[USB_MAX_STRING_LEN];
204 char udi_release[8];
205 u_int16_t udi_productNo;
206 u_int16_t udi_vendorNo;
207 u_int16_t udi_releaseNo;
208 u_int8_t udi_class;
209 u_int8_t udi_subclass;
210 u_int8_t udi_protocol;
211 u_int8_t udi_config;
212 u_int8_t udi_speed;
213#define USB_SPEED_LOW 1
214#define USB_SPEED_FULL 2
215#define USB_SPEED_HIGH 3
216 int udi_power;/* power consumption in mA, 0 if selfpowered */
217 int udi_nports;
218 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
219 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */
220#define USB_PORT_ENABLED 0xff
221#define USB_PORT_SUSPENDED 0xfe
222#define USB_PORT_POWERED 0xfd
223#define USB_PORT_DISABLED 0xfc
224};
225.Ed
181.
182.Ft "void"
183.Fo "usb2_transfer_unsetup"
184.Fa "pxfer"
185.Fa "n_setup"
186.Fc
187.
226.Pp
188.Pp
227.Va udi_bus
228and
229.Va udi_addr
230contain the topological information for the device.
231.Va udi_devnames
232contains the device names of the connected drivers.
233For example, the
234third
235.Tn USB
236Zip drive connected will be
237.Li umass2 .
189.
190.Ft "void"
191.Fo "usb2_transfer_start"
192.Fa "xfer"
193.Fc
194.
195.Pp
196.
197.Ft "void"
198.Fo "usb2_transfer_stop"
199.Fa "xfer"
200.Fc
201.
202.Pp
203.
204.Ft "void"
205.Fo "usb2_transfer_drain"
206.Fa "xfer"
207.Fc
208.
209.
210.Sh DESCRIPTION
238The
211The
239.Va udi_product , udi_vendor
240and
241.Va udi_release
242fields contain self-explanatory descriptions of the device.
243.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
244and
245.Va udi_protocol
246contain the corresponding values from the device descriptors.
212.Nm
213module implements the core functionality of the USB standard and many
214helper functions to make USB device driver programming easier and more
215safe.
216.
247The
217The
248.Va udi_config
249field shows the current configuration of the device.
218.Nm
219module supports both USB Host and USB Device side mode!
220.
221.Sh USB TRANSFER MANAGEMENT FUNCTIONS
222The USB standard defines four types of USB transfers.
223.
224Control transfers, Bulk transfers, Interrupt transfers and Isochronous
225transfers.
226.
227All the transfer types are managed using the following five functions:
228.
250.Pp
229.Pp
251.Va udi_speed
252indicates whether the device is at low speed
253.Pq Dv USB_SPEED_LOW ,
254full speed
255.Pq Dv USB_SPEED_FULL
256or high speed
257.Pq Dv USB_SPEED_HIGH .
258The
259.Va udi_power
260field shows the power consumption in milli-amps drawn at 5 volts,
261or zero if the device is self powered.
230.
231.Fn usb2_transfer_setup
232This function will allocate memory for and initialise an array of USB
233transfers and all required DMA memory.
234.
235This function can sleep or block waiting for resources to become
236available.
237.Fa udev
238is a pointer to "struct usb2_device".
239.Fa ifaces
240is an array of interface index numbers to use. See "if_index".
241.Fa pxfer
242is a pointer to an array of USB transfer pointers that are initialized
243to NULL, and then pointed to allocated USB transfers.
244.Fa setup_start
245is a pointer to an array of USB config structures.
246.Fa n_setup
247is a number telling the USB system how many USB transfers should be
248setup.
249.Fa priv_sc
250is the private softc pointer, which will be used to initialize
251"xfer->priv_sc".
252.Fa priv_mtx
253is the private mutex protecting the transfer structure and the
254softc. This pointer is used to initialize "xfer->priv_mtx".
255This function returns
256zero upon success. A non-zero return value indicates failure.
257.
262.Pp
258.Pp
263If the device is a hub, the
264.Va udi_nports
265field is non-zero, and the
266.Va udi_ports
267field contains the addresses of the connected devices.
268If no device is connected to a port, one of the
269.Dv USB_PORT_*
270values indicates its status.
271.It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
272This command retrieves statistics about the controller.
273.Bd -literal
274struct usb_device_stats {
275 u_long uds_requests[4];
259.
260.Fn usb2_transfer_unsetup
261This function will release the given USB transfers and all allocated
262resources associated with these USB transfers.
263.Fa pxfer
264is a pointer to an array of USB transfer pointers, that may be NULL,
265that should be freed by the USB system.
266.Fa n_setup
267is a number telling the USB system how many USB transfers should be
268unsetup.
269.
270This function can sleep waiting for USB transfers to complete.
271.
272This function is NULL safe with regard to the USB transfer structure
273pointer.
274.
275It is not allowed to call this function from the USB transfer
276callback.
277.
278.Pp
279.
280.Fn usb2_transfer_start
281This function will start the USB transfer pointed to by
282.Fa xfer,
283if not already started.
284.
285This function is always non-blocking and must be called with the
286so-called private USB mutex locked.
287.
288This function is NULL safe with regard to the USB transfer structure
289pointer.
290.
291.Pp
292.
293.Fn usb2_transfer_stop
294This function will stop the USB transfer pointed to by
295.Fa xfer,
296if not already stopped.
297.
298This function is always non-blocking and must be called with the
299so-called private USB mutex locked.
300.
301This function can return before the USB callback has been called.
302.
303This function is NULL safe with regard to the USB transfer structure
304pointer.
305.
306If the transfer was in progress, the callback will called with
307"USB_ST_ERROR" and "xfer->error = USB_ERR_CANCELLED".
308.
309.Pp
310.
311.Fn usb2_transfer_drain
312This function will stop an USB transfer, if not already stopped and
313wait for any additional USB hardware operations to complete.
314.
315Buffers that are loaded into DMA using "usb2_set_frame_data()" can
316safely be freed after that this function has returned.
317.
318This function can block the caller and will not return before the USB
319callback has been called.
320.
321This function is NULL safe with regard to the USB transfer structure
322pointer.
323.
324.Sh USB TRANSFER CALLBACK
325.
326The USB callback has three states.
327.
328USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
329initial state.
330.
331After the callback has been called with this state it will always be
332called back at a later stage in one of the other two states.
333.
334In the USB_ST_ERROR state the "error" field of the USB transfer
335structure is set to the error cause.
336.
337The USB callback should not restart the USB transfer in case the error
338cause is USB_ERR_CANCELLED.
339.
340The USB callback is protected from recursion.
341.
342That means one can start and stop whatever transfer from the callback
343of another transfer one desires.
344.
345Also the transfer that is currently called back.
346.
347Recursion is handled like this that when the callback that wants to
348recurse returns it is called one more time.
349.
350.
351.Pp
352.
353.Fn usb2_start_hardware
354This function should only be called from within the USB callback and
355is used to start the USB hardware.
356.
357Typical parameters that should be set in the USB transfer structure
358before this function is called are "frlengths[]", "nframes" and
359"frbuffers[]".
360.
361An USB transfer can have multiple frames consisting of one or more USB
362packets making up an I/O vector for all USB transfer types.
363.
364After the USB transfer is complete "frlengths[]" is updated to the
365actual USB transfer length for the given frame.
366.Bd -literal -offset indent
367void
368usb2_default_callback(struct usb2_xfer *xfer)
369{
370 switch (USB_GET_STATE(xfer)) {
371 case USB_ST_SETUP:
372 /*
373 * Setup xfer->frlengths[], xfer->nframes
374 * and write data to xfer->frbuffers[], if any
375 */
376 usb2_start_hardware(xfer);
377 break;
378
379 case USB_ST_TRANSFERRED:
380 /*
381 * Read data from xfer->frbuffers[], if any.
382 * "xfer->frlengths[]" should now have been
383 * updated to the actual length.
384 */
385 break;
386
387 default: /* Error */
388 /*
389 * Print error message and clear stall
390 * for example.
391 */
392 break;
393 }
394 /*
395 * Here it is safe to do something without the private
396 * USB mutex locked.
397 */
398 return;
399}
400.Ed
401.
402.Sh USB CONTROL TRANSFERS
403An USB control transfer has three parts.
404.
405First the SETUP packet, then DATA packet(s) and then a STATUS
406packet.
407.
408The SETUP packet is always pointed to by "xfer->frbuffers[0]" and the
409length is stored in "xfer->frlengths[0]" also if there should not be
410sent any SETUP packet! If an USB control transfer has no DATA stage,
411then "xfer->nframes" should be set to 1.
412.
413Else the default value is "xfer->nframes" equal to 2.
414.
415.Bd -literal -offset indent
416
417Example1: SETUP + STATUS
418 xfer->nframes = 1;
419 xfer->frlenghts[0] = 8;
420 usb2_start_hardware(xfer);
421
422Example2: SETUP + DATA + STATUS
423 xfer->nframes = 2;
424 xfer->frlenghts[0] = 8;
425 xfer->frlenghts[1] = 1;
426 usb2_start_hardware(xfer);
427
428Example3: SETUP + DATA + STATUS - split
4291st callback:
430 xfer->nframes = 1;
431 xfer->frlenghts[0] = 8;
432 usb2_start_hardware(xfer);
433
4342nd callback:
435 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
436 xfer->nframes = 2;
437 xfer->frlenghts[0] = 0;
438 xfer->frlenghts[1] = 1;
439 usb2_start_hardware(xfer);
440
441Example4: SETUP + STATUS - split
4421st callback:
443 xfer->nframes = 1;
444 xfer->frlenghts[0] = 8;
445 xfer->flags.manual_status = 1;
446 usb2_start_hardware(xfer);
447
4482nd callback:
449 xfer->nframes = 1;
450 xfer->frlenghts[0] = 0;
451 xfer->flags.manual_status = 0;
452 usb2_start_hardware(xfer);
453
454.Ed
455.Sh USB TRANSFER CONFIG
456To simply the search for endpoints the
457.Nm
458module defines a USB config structure where it is possible to specify
459the characteristics of the wanted endpoint.
460.Bd -literal -offset indent
461
462struct usb2_config {
463 bufsize,
464 callback
465 direction,
466 endpoint,
467 frames,
468 index flags,
469 interval,
470 timeout,
471 type,
276};
472};
473
277.Ed
474.Ed
475.
278.Pp
476.Pp
279The
280.Va udi_requests
281field is indexed by the transfer kind, i.e.\&
282.Dv UE_* ,
283and indicates how many transfers of each kind that has been completed
284by the controller.
285.It Dv USB_REQUEST Vt "struct usb_ctl_request"
286This command can be used to execute arbitrary requests on the control pipe.
287This is
288.Em DANGEROUS
289and should be used with great care since it
290can destroy the bus integrity.
477.Fa type
478field selects the USB pipe type.
479.
480Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
481UE_ISOCHRONOUS.
482.
483The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
484.
485This field is mandatory.
486.
487.Pp
488.Fa endpoint
489field selects the USB endpoint number.
490.
491A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
492endpoint.
493.
494This field is mandatory.
495.
496.Pp
497.Fa direction
498field selects the USB endpoint direction.
499.
500A value of "UE_DIR_ANY" will select the first matching endpoint.
501.
502Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
503.
504"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
505means that the direction will be swapped in case of
506USB_MODE_DEVICE.
507.
508Note that "UE_DIR_IN" refers to the data transfer direction of the
509"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of
510the "OUT" tokens.
511.
512This field is mandatory.
513.
514.Pp
515.Fa interval
516field selects the interrupt interval.
517.
518The value of this field is given in milliseconds and is independent of
519device speed.
520.
521Depending on the endpoint type, this field has different meaning:
522.Bl -tag
523.It UE_INTERRUPT
524"0" use the default interrupt interval based on endpoint descriptor.
525"Else" use the given value for polling rate.
526.It UE_ISOCHRONOUS
527"0" use default. "Else" the value is ignored.
528.It UE_BULK
529.It UE_CONTROL
530"0" no transfer pre-delay. "Else" a delay as given by this field in
531milliseconds is inserted before the hardware is started when
532"usb2_start_hardware()" is called.
533.Pp
534NOTE: The transfer timeout, if any, is started after that the
535pre-delay has elapsed!
291.El
536.El
537.
292.Pp
538.Pp
293The include file
294.In dev/usb/usb.h
295contains definitions for the types used by the various
296.Xr ioctl 2
297calls.
298The naming convention of the fields for the various
299.Tn USB
300descriptors exactly follows the naming in the
301.Tn USB
302specification.
303Byte sized fields can be accessed directly, but word (16 bit)
304sized fields must be access by the
305.Fn UGETW field
306and
307.Fn USETW field value
308macros to handle byte order and alignment properly.
539.Fa timeout
540field, if non-zero, will set the transfer timeout in milliseconds. If
541the "timeout" field is zero and the transfer type is ISOCHRONOUS a
542timeout of 250ms will be used.
543.
309.Pp
544.Pp
310The include file
311.In dev/usb/usbhid.h
312similarly contains the definitions for
313Human Interface Devices
314.Pq Tn HID .
315.Sh USB EVENT INTERFACE
316All
317.Tn USB
318events are reported via the
319.Pa /dev/usb
320device.
321This device can be opened for reading and each
322.Xr read 2
323will yield an event record (if something has happened).
324The
325.Xr poll 2
326system call can be used to determine if an event record is available
327for reading.
545.Fa frames
546field sets the maximum number of frames. If zero is specified it will
547yield the following results:
548.Bl -tag
549.It UE_BULK
550xfer->nframes = 1;
551.It UE_INTERRUPT
552xfer->nframes = 1;
553.It UE_CONTROL
554xfer->nframes = 2;
555.It UE_ISOCHRONOUS
556Not allowed. Will cause an error.
557.El
558.
328.Pp
559.Pp
329The event record has the following definition:
330.Bd -literal
331struct usb_event {
332 int ue_type;
333#define USB_EVENT_CTRLR_ATTACH 1
334#define USB_EVENT_CTRLR_DETACH 2
335#define USB_EVENT_DEVICE_ATTACH 3
336#define USB_EVENT_DEVICE_DETACH 4
337#define USB_EVENT_DRIVER_ATTACH 5
338#define USB_EVENT_DRIVER_DETACH 6
339 struct timespec ue_time;
340 union {
341 struct {
342 int ue_bus;
343 } ue_ctrlr;
344 struct usb_device_info ue_device;
345 struct {
346 usb_event_cookie_t ue_cookie;
347 char ue_devname[16];
348 } ue_driver;
349 } u;
350};
351.Ed
352The
353.Va ue_type
354field identifies the type of event that is described.
355The possible events are attach/detach of a host controller,
356a device, or a device driver.
357The union contains information
358pertinent to the different types of events.
359Macros,
360.Fn USB_EVENT_IS_ATTACH "ue_type"
361and
362.Fn USB_EVENT_IS_DETACH "ue_type"
363can be used to determine if an event was an
364.Dq attach
365or a
366.Dq detach
367request.
560.Fa ep_index
561field allows you to give a number, in case more endpoints match the
562description, that selects which matching "ep_index" should be used.
563.
368.Pp
564.Pp
369The
370.Va ue_bus
371contains the number of the
372.Tn USB
373bus for host controller events.
565.Fa if_index
566field allows you to select which of the interface numbers in the
567"ifaces" array parameter passed to "usb2_transfer_setup" that should
568be used when setting up the given USB transfer.
569.
374.Pp
570.Pp
375The
376.Va ue_device
377record contains information about the device in a device event event.
571.Fa flags
572field has type "struct usb2_xfer_flags" and allows one to set initial
573flags an USB transfer. Valid flags are:
574.Bl -tag
575.It force_short_xfer
576This flag forces the last transmitted USB packet to be short. A short
577packet has a length of less than "xfer->max_packet_size", which
578derives from "wMaxPacketSize". This flag can be changed during
579operation.
580.It short_xfer_ok
581This flag allows the received transfer length, "xfer->actlen" to be
582less than "xfer->sumlen" upon completion of a transfer. This flag can
583be changed during operation.
584.It short_frames_ok
585This flag allows the reception of multiple short USB frames. This flag
586only has effect for BULK and INTERRUPT endpoints and if the number of
587frames received is greater than 1. This flag can be changed during
588operation.
589.It pipe_bof
590This flag causes a failing USB transfer to remain first in the PIPE
591queue except in the case of "xfer->error" equal to
592"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
593will be started until either:
594.Bl -tag
595.It 1
596The failing USB transfer is stopped using "usb2_transfer_stop()".
597.It 2
598The failing USB transfer performs a successful transfer.
599.El
600The purpose of this flag is to avoid races when multiple transfers are
601queued for execution on an USB endpoint, and the first executing
602transfer fails leading to the need for clearing of stall for
603example.
604.
605In this case this flag is used to prevent the following USB transfers
606from being executed at the same time the clear-stall command is
607executed on the USB control endpoint.
608.
609This flag can be changed during operation.
378.Pp
610.Pp
379The
380.Va ue_cookie
381is an opaque value that uniquely determines which
382device a device driver has been attached to (i.e., it equals
383the cookie value in the device that the driver attached to).
611"BOF" is short for "Block On Failure"
384.Pp
612.Pp
385The
386.Va ue_devname
387contains the name of the device (driver) as seen in, e.g.,
388kernel messages.
613NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
614which use an endpoint that can be shared between userland and kernel.
615.
616.
617.It proxy_buffer
618Setting this flag will cause that the total buffer size will be
619rounded up to the nearest atomic hardware transfer size.
620.
621The maximum data length of any USB transfer is always stored in the
622"xfer->max_data_length".
623.
624For control transfers the USB kernel will allocate additional space
625for the 8-bytes of SETUP header.
626.
627These 8-bytes are not counted by the "xfer->max_data_length"
628variable.
629.
630This flag can not be changed during operation.
631.
632.
633.It ext_buffer
634Setting this flag will cause that no data buffer will be
635allocated.
636.
637Instead the USB client must supply a data buffer.
638.
639This flag can not be changed during operation.
640.
641.
642.It manual_status
643Setting this flag prevents an USB STATUS stage to be appended to the
644end of the USB control transfer.
645.
646If no control data is transferred this flag must be cleared.
647.
648Else an error will be returned to the USB callback.
649.
650This flag is mostly useful for the USB device side.
651.
652This flag can be changed during operation.
653.
654.
655.It no_pipe_ok
656Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
657flag can not be changed during operation.
658.
659.
660.It stall_pipe
661.Bl -tag
662.It Device Side Mode
663Setting this flag will cause STALL pids to be sent to the endpoint
664belonging to this transfer before the transfer is started.
665.
666The transfer is started at the moment the host issues a clear-stall
667command on the STALL'ed endpoint.
668.
669This flag can be changed during operation.
670.It Host Side Mode
671Setting this flag will cause a clear-stall control request to be
672executed on the endpoint before the USB transfer is started.
673.El
389.Pp
674.Pp
390Note that there is a separation between device and device
391driver events.
392A device event is generated when a physical
393.Tn USB
394device is attached or detached.
395A single
396.Tn USB
397device may
398have zero, one, or many device drivers associated with it.
675If this flag is changed outside the USB callback function you have to
676use the "usb2_transfer_set_stall()" and "usb2_transfer_clear_stall()"
677functions! This flag is automatically cleared after that the stall or
678clear stall has been executed.
679.
680.El
681.Pp
682.Fa bufsize
683field sets the total buffer size in bytes.
684.
685If this field is zero, "wMaxPacketSize" will be used, multiplied by
686the "frames" field if the transfer type is ISOCHRONOUS.
687.
688This is useful for setting up interrupt pipes.
689.
690This field is mandatory.
691.Pp
692NOTE: For control transfers "bufsize" includes the length of the
693request structure.
694.
695.Pp
696.Fa callback
697pointer sets the USB callback. This field is mandatory.
698.
699.
700.Sh USB LINUX COMPAT LAYER
701The
702.Nm
703module supports the Linux USB API.
704.
705.
706.
399.Sh SEE ALSO
400The
401.Tn USB
402specifications can be found at:
403.Pp
404.D1 Pa http://www.usb.org/developers/docs/
405.Pp
707.Sh SEE ALSO
708The
709.Tn USB
710specifications can be found at:
711.Pp
712.D1 Pa http://www.usb.org/developers/docs/
713.Pp
714.Xr libusb 3 ,
406.Xr aue 4 ,
407.Xr axe 4 ,
408.Xr cue 4 ,
409.Xr ehci 4 ,
410.Xr kue 4 ,
411.Xr ohci 4 ,
412.Xr pci 4 ,
413.Xr rue 4 ,
414.Xr ucom 4 ,
415.Xr udav 4 ,
715.Xr aue 4 ,
716.Xr axe 4 ,
717.Xr cue 4 ,
718.Xr ehci 4 ,
719.Xr kue 4 ,
720.Xr ohci 4 ,
721.Xr pci 4 ,
722.Xr rue 4 ,
723.Xr ucom 4 ,
724.Xr udav 4 ,
416.Xr ugen 4 ,
417.Xr uhci 4 ,
418.Xr uhid 4 ,
419.Xr ukbd 4 ,
420.Xr ulpt 4 ,
421.Xr umass 4 ,
422.Xr ums 4 ,
423.Xr uplcom 4 ,
424.Xr urio 4 ,
425.Xr uvscom 4 ,
725.Xr uhci 4 ,
726.Xr uhid 4 ,
727.Xr ukbd 4 ,
728.Xr ulpt 4 ,
729.Xr umass 4 ,
730.Xr ums 4 ,
731.Xr uplcom 4 ,
732.Xr urio 4 ,
733.Xr uvscom 4 ,
426.Xr usbdevs 8
427.Sh HISTORY
734.Xr usbconfig 8
735.Sh STANDARDS
428The
429.Nm
736The
737.Nm
430driver first appeared in
431.Fx 3.0 .
432.Sh AUTHORS
738module complies with the USB 2.0 standard.
739.Sh HISTORY
433The
434.Nm
740The
741.Nm
435driver was written by
436.An Lennart Augustsson Aq augustss@carlstedt.se
437for the
438.Nx
439project.
742module has been inspired by the NetBSD USB stack initially written by
743Lennart Augustsson. The
744.Nm
745module was written by
746.An Hans Petter Selasky Aq hselasky@freebsd.org .