Deleted Added
sdiff udiff text old ( 165213 ) new ( 194860 )
full compact
usbdi.9 (165213) usbdi.9 (194860)
1.\"
2.\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright

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

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

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

18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD: head/share/man/man9/usbdi.9 165213 2006-12-14 14:33:13Z mpp $
27.Dd December 30, 2005
26.\" $FreeBSD: head/share/man/man9/usbdi.9 194860 2009-06-24 17:01:17Z thompsa $
27.Dd June 24, 2009
28.Os
29.Dt USBDI 9
30.Sh NAME
28.Os
29.Dt USBDI 9
30.Sh NAME
31.Nm usb_detach_wait ,
32.Nm usb_detach_wakeup ,
33.Nm usb_find_desc ,
34.Nm usbd_abort_default_pipe ,
35.Nm usbd_abort_pipe ,
36.Nm usbd_alloc_buffer ,
37.Nm usbd_alloc_xfer ,
38.Nm usbd_bulk_transfer ,
39.Nm usbd_clear_endpoint_stall ,
40.Nm usbd_clear_endpoint_stall_async ,
41.Nm usbd_clear_endpoint_toggle ,
42.Nm usbd_close_pipe ,
43.Nm usbd_device2interface_handle ,
44.Nm usbd_devinfo ,
31.Nm usb_fifo_alloc_buffer ,
32.Nm usb_fifo_attach ,
33.Nm usb_fifo_detach ,
34.Nm usb_fifo_free_buffer ,
35.Nm usb_fifo_get_data ,
36.Nm usb_fifo_get_data_buffer ,
37.Nm usb_fifo_get_data_error ,
38.Nm usb_fifo_get_data_linear ,
39.Nm usb_fifo_put_bytes_max ,
40.Nm usb_fifo_put_data ,
41.Nm usb_fifo_put_data_buffer ,
42.Nm usb_fifo_put_data_error ,
43.Nm usb_fifo_put_data_linear ,
44.Nm usb_fifo_reset ,
45.Nm usb_fifo_softc ,
46.Nm usb_fifo_wakeup ,
45.Nm usbd_do_request ,
47.Nm usbd_do_request ,
46.Nm usbd_do_request_async ,
47.Nm usbd_do_request_flags ,
48.Nm usbd_do_request_flags ,
48.Nm usbd_do_request_flags_pipe ,
49.Nm usbd_dopoll ,
50.Nm usbd_endpoint_count ,
51.Nm usbd_errstr ,
49.Nm usbd_errstr ,
52.Nm usbd_fill_deviceinfo ,
53.Nm usbd_find_edesc ,
54.Nm usbd_find_idesc ,
55.Nm usbd_free_buffer ,
56.Nm usbd_free_xfer ,
57.Nm usbd_get_buffer ,
58.Nm usbd_get_config ,
59.Nm usbd_get_config_desc ,
60.Nm usbd_get_config_desc_full ,
61.Nm usbd_get_config_descriptor ,
62.Nm usbd_get_device_descriptor ,
63.Nm usbd_get_endpoint_descriptor ,
64.Nm usbd_get_interface_altindex ,
65.Nm usbd_get_interface_descriptor ,
66.Nm usbd_get_no_alts ,
67.Nm usbd_get_quirks ,
68.Nm usbd_get_speed ,
69.Nm usbd_get_string ,
70.Nm usbd_get_string_desc ,
71.Nm usbd_get_xfer_status ,
72.Nm usbd_interface2device_handle ,
73.Nm usbd_interface2endpoint_descriptor ,
74.Nm usbd_interface_count ,
75.Nm usbd_intr_transfer ,
76.Nm usbd_open_pipe ,
77.Nm usbd_open_pipe_intr ,
78.Nm usbd_pipe2device_handle ,
79.Nm usbd_ratecheck ,
80.Nm usbd_set_config_index ,
81.Nm usbd_set_config_no ,
82.Nm usbd_set_interface ,
83.Nm usbd_set_polling ,
84.Nm usbd_setup_default_xfer ,
85.Nm usbd_setup_isoc_xfer ,
86.Nm usbd_setup_xfer ,
87.Nm usbd_sync_transfer ,
88.Nm usbd_transfer
50.Nm usbd_lookup_id_by_info ,
51.Nm usbd_lookup_id_by_uaa ,
52.Nm usbd_transfer_clear_stall ,
53.Nm usbd_transfer_drain ,
54.Nm usbd_transfer_pending ,
55.Nm usbd_transfer_poll ,
56.Nm usbd_transfer_setup ,
57.Nm usbd_transfer_start ,
58.Nm usbd_transfer_stop ,
59.Nm usbd_transfer_submit ,
60.Nm usbd_transfer_unsetup ,
61.Nm usbd_xfer_clr_flag ,
62.Nm usbd_xfer_frame_data ,
63.Nm usbd_xfer_frame_len ,
64.Nm usbd_xfer_get_frame ,
65.Nm usbd_xfer_get_priv ,
66.Nm usbd_xfer_is_stalled ,
67.Nm usbd_xfer_max_framelen ,
68.Nm usbd_xfer_max_frames ,
69.Nm usbd_xfer_max_len ,
70.Nm usbd_xfer_set_flag ,
71.Nm usbd_xfer_set_frame_data ,
72.Nm usbd_xfer_set_frame_len ,
73.Nm usbd_xfer_set_frame_offset ,
74.Nm usbd_xfer_set_frames ,
75.Nm usbd_xfer_set_interval ,
76.Nm usbd_xfer_set_priv ,
77.Nm usbd_xfer_set_stall ,
78.Nm usbd_xfer_set_timeout ,
79.Nm usbd_xfer_softc ,
80.Nm usbd_xfer_state ,
81.Nm usbd_xfer_state ,
82.Nm usbd_xfer_status
89.Nd Universal Serial Bus driver programming interface
90.Sh SYNOPSIS
91.In dev/usb/usb.h
92.In dev/usb/usbdi.h
93.In dev/usb/usbdi_util.h
83.Nd Universal Serial Bus driver programming interface
84.Sh SYNOPSIS
85.In dev/usb/usb.h
86.In dev/usb/usbdi.h
87.In dev/usb/usbdi_util.h
94.Pp
95.Ft void
96.Fn usb_detach_wait "device_ptr_t dv"
97.Ft void
98.Fn usb_detach_wakeup "device_ptr_t dv"
99.Ft "const usb_descriptor_t *"
100.Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
101.Ft usbd_status
102.Fn usbd_abort_default_pipe "usbd_device_handle dev"
103.Ft usbd_status
104.Fn usbd_abort_pipe "usbd_pipe_handle pipe"
105.Ft "void *"
106.Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
107.Ft usbd_xfer_handle
108.Fn usbd_alloc_xfer "usbd_device_handle dev"
109.Ft usbd_status
110.Fo usbd_bulk_transfer
111.Fa "usbd_xfer_handle xfer"
112.Fa "usbd_pipe_handle pipe"
113.Fa "u_int16_t flags"
114.Fa "u_int32_t timeout"
115.Fa "void *buf"
116.Fa "u_int32_t *size"
117.Fa "char *lbl"
118.Fc
119.Ft usbd_status
120.Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
121.Ft usbd_status
122.Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle"
123.Ft void
124.Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
125.Ft usbd_status
126.Fn usbd_close_pipe "usbd_pipe_handle pipe"
127.Ft usbd_status
128.Fo usbd_device2interface_handle
129.Fa "usbd_device_handle dev"
130.Fa "u_int8_t ifaceno"
131.Fa "usbd_interface_handle *iface"
132.Fc
133.Ft void
134.Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
135.Ft usbd_status
136.Fo usbd_do_request
137.Fa "usbd_device_handle dev"
138.Fa "usb_device_request_t *req"
139.Fa "void *data"
140.Fc
141.Ft usbd_status
142.Fo usbd_do_request_async
143.Fa "usbd_device_handle dev"
144.Fa "usb_device_request_t *req"
145.Fa "void *data"
146.Fc
147.Ft usbd_status
148.Fo usbd_do_request_flags
149.Fa "usbd_device_handle dev"
150.Fa "usb_device_request_t *req"
151.Fa "void *data"
152.Fa "u_int16_t flags"
153.Fa "int *actlen"
154.Fa "u_int32_t timo"
155.Fc
156.Ft usbd_status
157.Fo usbd_do_request_flags_pipe
158.Fa "usbd_device_handle dev"
159.Fa "usbd_pipe_handle pipe"
160.Fa "usb_device_request_t *req"
161.Fa "void *data"
162.Fa "u_int16_t flags"
163.Fa "int *actlen"
164.Fa "u_int32_t timeout"
165.Fc
166.Ft void
167.Fn usbd_dopoll "usbd_interface_handle iface"
168.Ft usbd_status
169.Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
170.Ft "const char *"
171.Fn usbd_errstr "usbd_status err"
172.Ft void
173.Fo usbd_fill_deviceinfo
174.Fa "usbd_device_handle dev"
175.Fa "struct usb_device_info *di"
176.Fa "int usedev"
177.Fc
178.Ft "usb_endpoint_descriptor_t *"
179.Fo usbd_find_edesc
180.Fa "usb_config_descriptor_t *cd"
181.Fa "int ifaceidx"
182.Fa "int altidx"
183.Fa "int endptidx"
184.Fc
185.Ft "usb_interface_descriptor_t *"
186.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
187.Ft void
188.Fn usbd_free_buffer "usbd_xfer_handle xfer"
189.Ft usbd_status
190.Fn usbd_free_xfer "usbd_xfer_handle xfer"
191.Ft "void *"
192.Fn usbd_get_buffer "usbd_xfer_handle xfer"
193.Ft usbd_status
194.Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
195.Ft usbd_status
196.Fo usbd_get_config_desc
197.Fa "usbd_device_handle dev"
198.Fa "int confidx"
199.Fa "usb_config_descriptor_t *d"
200.Fc
201.Ft usbd_status
202.Fo usbd_get_config_desc_full
203.Fa "usbd_device_handle dev"
204.Fa "int conf"
205.Fa "void *d"
206.Fa "int size"
207.Fc
208.Ft "usb_config_descriptor_t *"
209.Fn usbd_get_config_descriptor "usbd_device_handle dev"
210.Ft "usb_device_descriptor_t *"
211.Fn usbd_get_device_descriptor "usbd_device_handle dev"
212.Ft "usb_endpoint_descriptor_t *"
213.Fo usbd_get_endpoint_descriptor
214.Fa "usbd_interface_handle iface"
215.Fa "u_int8_t address"
216.Fc
217.Ft int
218.Fn usbd_get_interface_altindex "usbd_interface_handle iface"
219.Ft "usb_interface_descriptor_t *"
220.Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
221.Ft int
222.Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
223.Ft "const struct usbd_quirks *"
224.Fn usbd_get_quirks "usbd_device_handle dev"
225.Ft int
226.Fn usbd_get_speed "usbd_device_handle dev"
227.Ft usbd_status
228.Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
229.Ft usbd_status
230.Fo usbd_get_string_desc
231.Fa "usbd_device_handle dev"
232.Fa "int sindex"
233.Fa "int langid"
234.Fa "usb_string_descriptor_t *sdesc"
235.Fa "int *sizep"
236.Fc
237.Ft void
238.Fo usbd_get_xfer_status
239.Fa "usbd_xfer_handle xfer"
240.Fa "usbd_private_handle *priv"
241.Fa "void **buffer"
242.Fa "u_int32_t *count"
243.Fa "usbd_status *status"
244.Fc
245.Ft void
246.Fo usbd_interface2device_handle
247.Fa "usbd_interface_handle iface"
248.Fa "usbd_device_handle *dev"
249.Fc
250.Ft "usb_endpoint_descriptor_t *"
251.Fo usbd_interface2endpoint_descriptor
252.Fa "usbd_interface_handle iface"
253.Fa "u_int8_t index"
254.Fc
255.Ft usbd_status
256.Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
257.Ft usbd_status
258.Fo usbd_intr_transfer
259.Fa "usbd_xfer_handle xfer"
260.Fa "usbd_pipe_handle pipe"
261.Fa "u_int16_t flags"
262.Fa "u_int32_t timeout"
263.Fa "void *buf"
264.Fa "u_int32_t *size"
265.Fa "char *lbl"
266.Fc
267.Ft usbd_status
268.Fo usbd_open_pipe
269.Fa "usbd_interface_handle iface"
270.Fa "u_int8_t address"
271.Fa "u_int8_t flags"
272.Fa "usbd_pipe_handle *pipe"
273.Fc
274.Ft usbd_status
275.Fo usbd_open_pipe_intr
276.Fa "usbd_interface_handle iface"
277.Fa "u_int8_t address"
278.Fa "u_int8_t flags"
279.Fa "usbd_pipe_handle *pipe"
280.Fa "usbd_private_handle priv"
281.Fa "void *buffer"
282.Fa "u_int32_t len"
283.Fa "usbd_callback cb"
284.Fa "int ival"
285.Fc
286.Ft usbd_device_handle
287.Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
288.Ft int
289.Fn usbd_ratecheck "struct timeval *last"
290.Ft usbd_status
291.Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
292.Ft usbd_status
293.Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
294.Ft usbd_status
295.Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
296.Ft void
297.Fn usbd_set_polling "usbd_device_handle dev" "int on"
298.Ft void
299.Fo usbd_setup_default_xfer
300.Fa "usbd_xfer_handle xfer"
301.Fa "usbd_device_handle dev"
302.Fa "usbd_private_handle priv"
303.Fa "u_int32_t timeout"
304.Fa "usb_device_request_t *req"
305.Fa "void *buffer"
306.Fa "u_int32_t length"
307.Fa "u_int16_t flags"
308.Fa "usbd_callback callback"
309.Fc
310.Ft void
311.Fo usbd_setup_isoc_xfer
312.Fa "usbd_xfer_handle xfer"
313.Fa "usbd_pipe_handle pipe"
314.Fa "usbd_private_handle priv"
315.Fa "u_int16_t *frlengths"
316.Fa "u_int32_t nframes"
317.Fa "u_int16_t flags"
318.Fa "usbd_callback callback"
319.Fc
320.Ft void
321.Fo usbd_setup_xfer
322.Fa "usbd_xfer_handle xfer"
323.Fa "usbd_pipe_handle pipe"
324.Fa "usbd_private_handle priv"
325.Fa "void *buffer"
326.Fa "u_int32_t length"
327.Fa "u_int16_t flags"
328.Fa "u_int32_t timeout"
329.Fa "usbd_callback callback"
330.Fc
331.Ft usbd_status
332.Fn usbd_sync_transfer "usbd_xfer_handle xfer"
333.Ft usbd_status
334.Fn usbd_transfer "usbd_xfer_handle xfer"
335.Sh DESCRIPTION
336The Universal Serial Bus (USB) driver programming interface provides
337USB peripheral drivers with a host controller independent API for
338controlling and communicating with USB peripherals.
88.Sh DESCRIPTION
89The Universal Serial Bus (USB) driver programming interface provides
90USB peripheral drivers with a host controller independent API for
91controlling and communicating with USB peripherals.
339.Pp
340Typically, drivers will first use some combination of the functions
341.Fn usbd_set_config_no ,
342.Fn usbd_get_config_descriptor ,
343.Fn usbd_set_interface ,
344.Fn usbd_get_interface_descriptor ,
345.Fn usbd_device2interface_handle ,
346.Fn usbd_endpoint_count
347and
348.Fn usbd_interface2endpoint_descriptor
349to query the device's properties and prepare it for use.
350Drivers can then perform requests on the USB control pipe using
351.Fn usbd_do_request ,
352they can open pipes using the functions
353.Fn usbd_open_pipe
354and
355.Fn usbd_open_pipe_intr ,
356and perform transfers over these pipes using
357.Fn usbd_alloc_xfer ,
358.Fn usbd_setup_xfer
359and
360.Fn usbd_transfer .
361Finally, the functions
362.Fn usbd_abort_pipe ,
363.Fn usbd_close_pipe
364and
365.Fn usbd_free_xfer
366are used to cancel outstanding transfers, close open pipes and deallocate
367transfer structures.
368.Pp
369The
92The
370.Fn usbd_get_device_descriptor
371function returns a pointer to the USB device descriptor for
372.Fa dev .
373See
374.Sx "USB Descriptors"
375below for information about the USB device descriptor.
93.Nm usb
94module supports both USB Host and USB Device side mode.
95.
96.Sh USB KERNEL PROGRAMMING
97Here is a list of commonly used functions:
376.Pp
98.Pp
377The
378.Fn usbd_get_config_desc
379function retrieves the specified configuration descriptor from the device.
380The
381.Fa confidx
382parameter specifies the configuration descriptor index, which must be less
383than the
384.Fa bNumConfigurations
385value in the device descriptor.
386The function
387.Fn usbd_get_config_desc_full
388retrieves a full configuration descriptor, which has all related interface
389and endpoint descriptors appended to a normal configuration descriptor.
390The parameter
391.Fa d
392should point to memory that is at least
393.Fa size
394bytes in length, and this should be at least as long as the
395.Fa wTotalLength
396value from the configuration descriptor.
397See
398.Sx "USB Descriptors"
399below for information about the USB configuration descriptor.
99.
100.Ft "usb_error_t"
101.Fo "usbd_transfer_setup"
102.Fa "udev"
103.Fa "ifaces"
104.Fa "pxfer"
105.Fa "setup_start"
106.Fa "n_setup"
107.Fa "priv_sc"
108.Fa "priv_mtx"
109.Fc
110.
400.Pp
111.Pp
401The
402.Fn usbd_get_config
403function retrieves the current configuration number from the device, i.e.\&
404the
405.Fa bConfigurationValue
406value from the configuration that is active.
407If the device is unconfigured then
408.Dv USB_UNCONFIG_NO
409is returned.
410The current configuration can be changed by calling either
411.Fn usbd_set_config_index
412or
413.Fn usbd_set_config_no .
414The difference between these functions is that
415.Fn usbd_set_config_index
416accepts a configuration index number that is less than the
417.Fa bNumConfigurations
418value from the device descriptor, whereas
419.Fn usbd_set_config_no
420requires the
421.Fa bConfigurationValue
422value of the desired configuration to be provided instead.
423To unconfigure the device, supply a configuration index of
424.Dv USB_UNCONFIG_INDEX
425to
426.Fn usbd_set_config_index ,
427or else specify a configuration number of
428.Dv USB_UNCONFIG_NO
429to
430.Fn usbd_set_config_no .
112.
113.Ft "void"
114.Fo "usbd_transfer_unsetup"
115.Fa "pxfer"
116.Fa "n_setup"
117.Fc
118.
431.Pp
119.Pp
432The
433.Fn usbd_get_config_descriptor
434function returns a pointer to an in-memory copy of the full configuration
435descriptor of the configuration that is currently active.
436The returned pointer remains valid until the device configuration
437is changed using
438.Fn usbd_set_config_index
439or
440.Fn usbd_set_config_no .
441If the device is unconfigured then
442.Dv NULL
443is returned instead.
120.
121.Ft "void"
122.Fo "usbd_transfer_start"
123.Fa "xfer"
124.Fc
125.
444.Pp
126.Pp
445The function
446.Fn usbd_interface_count
447returns the number of interfaces available in the current device
448configuration.
449The
450.Fn usbd_get_no_alts
451function determines the number of alternate interfaces in a full
452configuration descriptor by counting the interface descriptors with
453.Fa bInterfaceNumber
454equal to
455.Fa ifaceno
456(the count includes alternate index zero).
457The
458.Fn usbd_find_idesc
459function locates an interface descriptor within a full configuration
460descriptor.
461The
462.Fa ifaceidx
463parameter specifies the interface index number, which should be less than
464the number of interfaces in the configuration descriptor (i.e.\& the value
465returned by
466.Fn usbd_interface_count
467or the
468.Fa bNumInterface
469field from the configuration descriptor).
470An alternate interface can be specified using a non-zero
471.Fa altidx ,
472which should be less than the value returned by
473.Fn usbd_get_no_alts .
474The return value is a pointer to the requested interface descriptor
475within the full configuration descriptor, or
476.Dv NULL
477if the specified interface descriptor does not exist.
478Note that the
479.Fa altidx
480parameter specifies the alternate setting by index number starting
481at zero; it is not the alternate setting number defined in the
482interface descriptor.
127.
128.Ft "void"
129.Fo "usbd_transfer_stop"
130.Fa "xfer"
131.Fc
132.
483.Pp
133.Pp
484The function
485.Fn usbd_find_edesc
486locates an endpoint descriptor within a full configuration descriptor.
487The
488.Fa ifaceidx
489and
490.Fa altidx
491parameters are the same as described for
492.Fn usbd_find_idesc ,
493and the
494.Fa endptidx
495parameter is an endpoint index number that should be less than the
496.Fa bNumEndpoints
497field in the interface descriptor.
498The return value is a pointer to the requested endpoint descriptor
499within the full configuration descriptor, or
500.Dv NULL
501if the specified endpoint descriptor does not exist.
502Note that the
503.Fa altidx
504and
505.Fa endptidx
506parameters are index numbers starting at zero; they are not the
507alternate setting and endpoint address defined in the descriptors.
134.
135.Ft "void"
136.Fo "usbd_transfer_drain"
137.Fa "xfer"
138.Fc
139.
140.
141.
142.Sh USB TRANSFER MANAGEMENT FUNCTIONS
143The USB standard defines four types of USB transfers.
144.
145Control transfers, Bulk transfers, Interrupt transfers and Isochronous
146transfers.
147.
148All the transfer types are managed using the following five functions:
149.
508.Pp
150.Pp
509The
510.Fn usbd_get_speed
511function returns the device speed.
512This can be
513.Dv USB_SPEED_LOW ,
514.Dv USB_SPEED_FULL
515or
516.Dv USB_SPEED_HIGH .
151.
152.Fn usbd_transfer_setup
153This function will allocate memory for and initialise an array of USB
154transfers and all required DMA memory.
155.
156This function can sleep or block waiting for resources to become
157available.
158.Fa udev
159is a pointer to "struct usb_device".
160.Fa ifaces
161is an array of interface index numbers to use. See "if_index".
162.Fa pxfer
163is a pointer to an array of USB transfer pointers that are initialized
164to NULL, and then pointed to allocated USB transfers.
165.Fa setup_start
166is a pointer to an array of USB config structures.
167.Fa n_setup
168is a number telling the USB system how many USB transfers should be
169setup.
170.Fa priv_sc
171is the private softc pointer, which will be used to initialize
172"xfer->priv_sc".
173.Fa priv_mtx
174is the private mutex protecting the transfer structure and the
175softc. This pointer is used to initialize "xfer->priv_mtx".
176This function returns
177zero upon success. A non-zero return value indicates failure.
178.
517.Pp
179.Pp
518USB devices optionally support string descriptors, which can be
519retrieved using the
520.Fn usbd_get_string
521or
522.Fn usbd_get_string_desc
523functions.
524Device, configuration and interface descriptors reference strings by
525an index number that can be supplied to these functions.
526The
527.Fn usbd_get_string
528function should be used unless a non-default language is required.
529It requires that
530.Fa buf
531points to a buffer of at least
532.Dv USB_MAX_STRING_LEN
533bytes in size.
534The
535.Fa si
536parameter specified which string to retrieve.
180.
181.Fn usbd_transfer_unsetup
182This function will release the given USB transfers and all allocated
183resources associated with these USB transfers.
184.Fa pxfer
185is a pointer to an array of USB transfer pointers, that may be NULL,
186that should be freed by the USB system.
187.Fa n_setup
188is a number telling the USB system how many USB transfers should be
189unsetup.
190.
191This function can sleep waiting for USB transfers to complete.
192.
193This function is NULL safe with regard to the USB transfer structure
194pointer.
195.
196It is not allowed to call this function from the USB transfer
197callback.
198.
537.Pp
199.Pp
538The
539.Fn usb_find_desc
540function searches through the in-memory full configuration descriptor
541for the active configuration and finds the first descriptor that has a
542.Fa bDescriptorType
543equal to
544.Fa type ,
545and if
546.Fa subtype
547is not equal to
548.Dv USBD_SUBTYPE_ANY ,
549the descriptor must also have a
550.Fa bDescriptorSubtype
551equal to
552.Fa subtype .
553If found, then a pointer to the descriptor is returned.
554Otherwise,
555.Fn usb_find_desc
556returns
557.Dv NULL .
558The returned pointer is valid until the device configuration is changed using
559.Fn usbd_set_config_index
560or
561.Fn usbd_set_config_no .
200.
201.Fn usbd_transfer_start
202This function will start the USB transfer pointed to by
203.Fa xfer,
204if not already started.
205.
206This function is always non-blocking and must be called with the
207so-called private USB mutex locked.
208.
209This function is NULL safe with regard to the USB transfer structure
210pointer.
211.
562.Pp
212.Pp
563The USB driver interface uses opaque interface handles to refer to
564configuration interfaces.
565These handles remain valid until the device configuration is changed using
566.Fn usbd_set_config_index
567or
568.Fn usbd_set_config_no .
569The
570.Fn usbd_device2interface_handle
571function retrieves an interface handle.
572The
573.Fa ifaceno
574parameter is an interface index number starting at zero.
575If the device is configured and the specified interface exists, then
576.Dv USBD_NORMAL_COMPLETION
577is returned and the interface handle is stored in
578.Fa *iface .
579Otherwise an error code is returned and
580.Fa *iface
581is not changed.
582The
583.Fn usbd_interface2device_handle
584function retrieves the device handle from an interface handle.
585This is just for convenience to save passing around the device
586handle as well as the interface handle.
587The
588.Fn usbd_set_interface
589function changes the alternate setting number for an interface to
590the alternate setting identified by the zero-based index number
591.Fa altidx .
592This operation invalidates any existing endpoints on this
593interface and their descriptors.
594The
595.Fn usbd_get_interface_altindex
596function returns the current alternative setting index as was
597specified when calling
598.Fn usbd_set_interface .
599The
600.Fn usbd_endpoint_count
601function retrieves the number of endpoints associated with the
602specified interface.
603The
604.Fn usbd_interface2endpoint_descriptor
605function returns a pointer to an in-memory endpoint descriptor for
606the endpoint that has an index number of
607.Fa index .
608This pointer remains valid until the configuration or alternate setting
609number are changed.
610The function
611.Fn usbd_get_endpoint_descriptor
612is like
613.Fn usbd_interface2endpoint_descriptor
614but it accepts a
615.Fa bEndpointAddress
616address value instead of an index.
213.
214.Fn usbd_transfer_stop
215This function will stop the USB transfer pointed to by
216.Fa xfer,
217if not already stopped.
218.
219This function is always non-blocking and must be called with the
220so-called private USB mutex locked.
221.
222This function can return before the USB callback has been called.
223.
224This function is NULL safe with regard to the USB transfer structure
225pointer.
226.
227If the transfer was in progress, the callback will called with
228"USB_ST_ERROR" and "error = USB_ERR_CANCELLED".
229.
617.Pp
230.Pp
618The
619.Fn usbd_fill_deviceinfo
620function fills out a
621.Vt usb_device_info
622structure with information about the device.
623The vendor and product names come from the device itself, falling back to
624a table lookup or just providing the IDs in hexadecimal.
625If
626.Fa usedev
627is zero then
628.Fn usbd_fill_deviceinfo
629will not attempt to retrieve the vendor and product names from the
630device.
631The usb_device_info structure is defined in
632.In dev/usb/usb.h
633as follows:
634.Bd -literal
635struct usb_device_info {
636 u_int8_t udi_bus;
637 u_int8_t udi_addr; /* device address */
638 usb_event_cookie_t udi_cookie;
639 char udi_product[USB_MAX_STRING_LEN];
640 char udi_vendor[USB_MAX_STRING_LEN];
641 char udi_release[8];
642 u_int16_t udi_productNo;
643 u_int16_t udi_vendorNo;
644 u_int16_t udi_releaseNo;
645 u_int8_t udi_class;
646 u_int8_t udi_subclass;
647 u_int8_t udi_protocol;
648 u_int8_t udi_config;
649 u_int8_t udi_speed;
650#define USB_SPEED_LOW 1
651#define USB_SPEED_FULL 2
652#define USB_SPEED_HIGH 3
653 int udi_power; /* power consumption in mA */
654 int udi_nports;
655 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
656 /* hub only: addresses of devices on ports */
657 u_int8_t udi_ports[16];
658#define USB_PORT_ENABLED 0xff
659#define USB_PORT_SUSPENDED 0xfe
660#define USB_PORT_POWERED 0xfd
231.
232.Fn usbd_transfer_drain
233This function will stop an USB transfer, if not already stopped and
234wait for any additional USB hardware operations to complete.
235.
236Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can
237safely be freed after that this function has returned.
238.
239This function can block the caller and will not return before the USB
240callback has been called.
241.
242This function is NULL safe with regard to the USB transfer structure
243pointer.
244.
245.Sh USB TRANSFER CALLBACK
246.
247The USB callback has three states.
248.
249USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
250initial state.
251.
252After the callback has been called with this state it will always be
253called back at a later stage in one of the other two states.
254.
255The USB callback should not restart the USB transfer in case the error
256cause is USB_ERR_CANCELLED.
257.
258The USB callback is protected from recursion.
259.
260That means one can start and stop whatever transfer from the callback
261of another transfer one desires.
262.
263Also the transfer that is currently called back.
264.
265Recursion is handled like this that when the callback that wants to
266recurse returns it is called one more time.
267.
268.
269.Pp
270.
271.Fn usbd_transfer_submit
272This function should only be called from within the USB callback and
273is used to start the USB hardware.
274.
275An USB transfer can have multiple frames consisting of one or more USB
276packets making up an I/O vector for all USB transfer types.
277.
278.Bd -literal -offset indent
279void
280usb_default_callback(struct usb_xfer *xfer, usb_error_t error)
281{
282 int actlen;
283
284 usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);
285
286 switch (USB_GET_STATE(xfer)) {
287 case USB_ST_SETUP:
288 /*
289 * Setup xfer frame lengths/count and data
290 */
291 usbd_transfer_submit(xfer);
292 break;
293
294 case USB_ST_TRANSFERRED:
295 /*
296 * Read usb frame data, if any.
297 * "actlen" has the total length for all frames
298 * transfered.
299 */
300 break;
301
302 default: /* Error */
303 /*
304 * Print error message and clear stall
305 * for example.
306 */
307 break;
308 }
309 /*
310 * Here it is safe to do something without the private
311 * USB mutex locked.
312 */
313 return;
661}
662.Ed
314}
315.Ed
663.Pp
664The
665.Fn usbd_devinfo
666function generates a string description of the USB device.
667The
668.Fa cp
669argument should point to a 1024-byte buffer (XXX the maximum length
670is approximately 320 chars, but there is no sanity checking and everything uses
6711024-character buffers).
672Device class information is included if the
673.Fa showclass
674parameter is non-zero.
675.Pp
676The
677.Fn usbd_get_quirks
678function returns information from a table of devices that require
679special workarounds in order to function correctly.
680The returned structure is defined in
681.In dev/usb/usb_quirks.h
682as follows:
683.Bd -literal
684struct usbd_quirks {
685 u_int32_t uq_flags; /* Device problems */
316.
317.Sh USB CONTROL TRANSFERS
318An USB control transfer has three parts.
319.
320First the SETUP packet, then DATA packet(s) and then a STATUS
321packet.
322.
323The SETUP packet is always pointed to by frame 0 and the
324length is set by
325.Fn usbd_xfer_frame_len
326also if there should not be
327sent any SETUP packet! If an USB control transfer has no DATA stage,
328then the number of frames should be set to 1.
329.
330Else the default number of frames is 2.
331.
332.Bd -literal -offset indent
333
334Example1: SETUP + STATUS
335 usbd_xfer_set_frames(xfer, 1);
336 usbd_xfer_set_frame_len(xfer, 0, 8);
337 usbd_transfer_submit(xfer);
338
339Example2: SETUP + DATA + STATUS
340 usbd_xfer_set_frames(xfer, 2);
341 usbd_xfer_set_frame_len(xfer, 0, 8);
342 usbd_xfer_set_frame_len(xfer, 1, 1);
343 usbd_transfer_submit(xfer);
344
345Example3: SETUP + DATA + STATUS - split
3461st callback:
347 usbd_xfer_set_frames(xfer, 1);
348 usbd_xfer_set_frame_len(xfer, 0, 8);
349 usbd_transfer_submit(xfer);
350
3512nd callback:
352 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
353 usbd_xfer_set_frames(xfer, 2);
354 usbd_xfer_set_frame_len(xfer, 0, 0);
355 usbd_xfer_set_frame_len(xfer, 1, 1);
356 usbd_transfer_submit(xfer);
357
358Example4: SETUP + STATUS - split
3591st callback:
360 usbd_xfer_set_frames(xfer, 1);
361 usbd_xfer_set_frame_len(xfer, 0, 8);
362 usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS);
363 usbd_transfer_submit(xfer);
364
3652nd callback:
366 usbd_xfer_set_frames(xfer, 1);
367 usbd_xfer_set_frame_len(xfer, 0, 0);
368 usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS);
369 usbd_transfer_submit(xfer);
370
371.Ed
372.Sh USB TRANSFER CONFIG
373To simply the search for endpoints the
374.Nm usb
375module defines a USB config structure where it is possible to specify
376the characteristics of the wanted endpoint.
377.Bd -literal -offset indent
378
379struct usb_config {
380 bufsize,
381 callback
382 direction,
383 endpoint,
384 frames,
385 index flags,
386 interval,
387 timeout,
388 type,
686};
389};
390
687.Ed
391.Ed
392.
688.Pp
393.Pp
689See
690.In dev/usb/usb_quirks.h
691for a list of all currently defined quirks.
394.Fa type
395field selects the USB pipe type.
396.
397Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
398UE_ISOCHRONOUS.
399.
400The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
401.
402This field is mandatory.
403.
692.Pp
404.Pp
693USB control requests are performed via
694.Vt usb_device_request_t
695structures, defined in
696.In dev/usb/usb.h
697as follows:
698.Bd -literal
699typedef struct {
700 uByte bmRequestType;
701 uByte bRequest;
702 uWord wValue;
703 uWord wIndex;
704 uWord wLength;
705} UPACKED usb_device_request_t;
706.Ed
405.Fa endpoint
406field selects the USB endpoint number.
407.
408A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
409endpoint.
410.
411This field is mandatory.
412.
707.Pp
413.Pp
708The
709.Fn usbd_do_request
710function performs a single request synchronously.
711The
712.Fa req
713parameter should point to a properly initialized
714.Vt usb_device_request_t ,
715and when the
716.Fa wLength
717field is non-zero,
718.Fa data
719should point at a buffer that is at least
720.Fa wLength
721bytes in length.
722The request timeout is set to 5 seconds, so the operation will fail
723with
724.Er USBD_TIMEOUT
725if the device does not respond within that time.
726The
727.Fn usbd_do_request_async
728function is like
729.Fn usbd_do_request ,
730but it does not wait for the request to complete before returning.
731This routine does not block so it can be used from contexts where
732sleeping is not allowed.
733Note that there is no notification mechanism to report when the
734operation completed nor is there a way to determine whether the
735request succeeded, so this function is of limited use.
736See
737.Fn usbd_setup_default_xfer
738and
739.Fn usbd_transfer
740for a way to invoke an asynchronous callback upon completion of
741a control request.
742The
743.Fn usbd_do_request_flags
744function is like
745.Fn usbd_do_request ,
746but additional flags can be specified, the timeout is configurable,
747and the actual number of bytes transferred is made available to the
748caller.
749The
750.Fn usbd_do_request_flags_pipe
751function uses a specified pipe instead of the default pipe.
414.Fa direction
415field selects the USB endpoint direction.
416.
417A value of "UE_DIR_ANY" will select the first matching endpoint.
418.
419Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
420.
421"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
422means that the direction will be swapped in case of
423USB_MODE_DEVICE.
424.
425Note that "UE_DIR_IN" refers to the data transfer direction of the
426"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of
427the "OUT" tokens.
428.
429This field is mandatory.
430.
752.Pp
431.Pp
753The function
754.Fn usbd_open_pipe
755creates a pipe connected to a specified endpoint on a specified interface.
756The parameter
757.Fa address
758should be the
759.Fa bEndpointAddress
760value from one of this interface's endpoint descriptors.
761If
762.Fa flags
763contains
764.Dv USBD_EXCLUSIVE_USE
765then the operation will only succeed if there are no open pipes
766already connected to the specified endpoint.
767The
768.Fn usbd_open_pipe_intr
769function creates an interrupt pipe connected to the specified endpoint.
770The parameter
771.Fa address
772should be the
773.Fa bEndpointAddress
774value from one of this interface's endpoint descriptors.
775The
776.Fa flags
777parameter is passed to
778.Fn usbd_setup_xfer .
779The
780.Fa buffer
781and
782.Fa len
783parameters define a buffer that is to be used for the interrupt transfers.
784The callback to be invoked each time a transfer completes is specified by
785.Fa cb ,
786and
787.Fa priv
788is an argument to be passed to the callback function.
789The
790.Fa ival
791parameter specifies the maximum acceptable interval between transfers;
792in practice the transfers may occur more frequently.
793The function
794.Fn usbd_pipe2device_handle
795returns the device associated with the specified
796.Fa pipe .
432.Fa interval
433field selects the interrupt interval.
434.
435The value of this field is given in milliseconds and is independent of
436device speed.
437.
438Depending on the endpoint type, this field has different meaning:
439.Bl -tag
440.It UE_INTERRUPT
441"0" use the default interrupt interval based on endpoint descriptor.
442"Else" use the given value for polling rate.
443.It UE_ISOCHRONOUS
444"0" use default. "Else" the value is ignored.
445.It UE_BULK
446.It UE_CONTROL
447"0" no transfer pre-delay. "Else" a delay as given by this field in
448milliseconds is inserted before the hardware is started when
449"usbd_transfer_submit()" is called.
797.Pp
450.Pp
798The
799.Fn usbd_abort_pipe
800function aborts all active or waiting transfers on the specified pipe.
801Each transfer is aborted with a
802.Dv USBD_CANCELLED
803status; callback routines must detect this error code to ensure that
804they do not attempt to initiate a new transfer in response to one being
805aborted.
806This routine blocks while it is waiting for the hardware to complete
807processing of aborted transfers, so it is only safe to call it in
808contexts where sleeping is allowed.
809The function
810.Fn usbd_abort_default_pipe
811aborts all active or waiting transfers on the default pipe.
812Like
813.Fn usbd_abort_pipe ,
814it blocks waiting for the hardware processing to complete.
815.Pp
816When a pipe has no active or waiting transfers, the pipe may be closed
817using the
818.Fn usbd_close_pipe
819function.
820Once a pipe is closed, its pipe handle becomes invalid and may no longer
821be used.
822.Pp
823USB transfer handles are allocated using the function
824.Fn usbd_alloc_xfer
825and may be freed using
826.Fn usbd_free_xfer .
827.Pp
828The function
829.Fn usbd_setup_xfer
830initializes a transfer handle with the details of a transfer to or from
831a USB device.
832The
833.Fa xfer
834parameter specifies the transfer handle to initialize,
835.Fa pipe
836specifies the pipe on which the transfer is to take place, and
837.Fa priv
838is an argument that will be passed to callback function.
839The arguments
840.Fa buffer
841and
842.Fa length
843define the data buffer for the transfer.
844If
845.Fa length
846is zero then the
847.Fa buffer
848may be
849.Dv NULL .
850The
851.Fa flags
852parameter may contain the following flags:
853.Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
854.It Dv USBD_NO_COPY
855This is used in association with
856.Fn usbd_alloc_buffer
857and
858.Fn usbd_free_buffer
859to use a dedicated DMA-capable buffer for the transfer.
860.It Dv USBD_SYNCHRONOUS
861Wait for the transfer to compete in
862.Fn usbd_transfer .
863.It Dv USBD_SHORT_XFER_OK
864Permit transfers shorter than the requested data length.
865.It Dv USBD_FORCE_SHORT_XFER
866Force a short transfer at the end of a write operation to let the
867device know that the transfer has ended.
451NOTE: The transfer timeout, if any, is started after that the
452pre-delay has elapsed!
868.El
453.El
454.
869.Pp
455.Pp
870The
871.Fa timeout
456.Fa timeout
872parameter specifies a timeout for the transfer in milliseconds.
873A value of
874.Dv USBD_NO_TIMEOUT
875indicates that no timeout should be configured.
876The parameter
877.Fa callback
878specifies the function to call when the transfer completes.
879Note that
880.Fn usbd_setup_xfer
881does not actually initiate the transfer.
882The
883.Fn usbd_setup_default_xfer
884initializes a control transfer for the default pipe.
885The
886.Fa req
887parameter should point at a completed
888.Vt usb_device_request_t
889structure.
890The function
891.Fa usbd_setup_isoc_xfer
892initializes a transfer for an isochronous pipe.
457field, if non-zero, will set the transfer timeout in milliseconds. If
458the "timeout" field is zero and the transfer type is ISOCHRONOUS a
459timeout of 250ms will be used.
460.
893.Pp
461.Pp
894The function
895.Fn usbd_transfer
896initiates a transfer.
897Normally it returns
898.Dv USBD_IN_PROGRESS
899to indicate that the transfer has been queued.
900If the USB stack is operating in polling mode, or if the transfer
901is synchronous, then
902.Dv USBD_NORMAL_COMPLETION
903may be returned.
904Other return values indicate that the transfer could not be
905initiated due to an error.
906The
907.Fn usbd_sync_transfer
908function executes a transfer synchronously.
909It will sleep waiting for the transfer to complete and then return
910the transfer status.
911Note that if the transfer has a callback routine, this will be
912invoked before
913.Fn usbd_sync_transfer
914returns.
462.Fa frames
463field sets the maximum number of frames. If zero is specified it will
464yield the following results:
465.Bl -tag
466.It UE_BULK
467xfer->nframes = 1;
468.It UE_INTERRUPT
469xfer->nframes = 1;
470.It UE_CONTROL
471xfer->nframes = 2;
472.It UE_ISOCHRONOUS
473Not allowed. Will cause an error.
474.El
475.
915.Pp
476.Pp
916The
917.Fn usbd_intr_transfer
918and
919.Fn usbd_bulk_transfer
920functions set up a transfer and wait synchronously for it to complete
921but they allows signals to interrupt the wait.
922They returns
923.Dv USBD_INTERRUPTED
924if the transfer was interrupted by a signal.
925XXX these two functions are identical apart from their names.
477.Fa ep_index
478field allows you to give a number, in case more endpoints match the
479description, that selects which matching "ep_index" should be used.
480.
926.Pp
481.Pp
927The function
928.Fn usbd_get_xfer_status
929retrieves various information from a completed transfer.
930If the
931.Fa priv
932parameter is not NULL then the callback private argument is
933stored in
934.Fa *priv .
935If
936.Fa buffer
937is not NULL then the transfer buffer pointer is stored in
938.Fa *buffer .
939The actual number of bytes transferred is stored in
940.Fa *count
941if
942.Fa count is not NULL.
943Finally, the transfer status is stored in
944.Fa *status
945if
946.Fa status
947is not NULL.
482.Fa if_index
483field allows you to select which of the interface numbers in the
484"ifaces" array parameter passed to "usbd_transfer_setup" that should
485be used when setting up the given USB transfer.
486.
948.Pp
487.Pp
949The
950.Fn usbd_clear_endpoint_stall
951function clears an endpoint stall condition synchronously, i.e.\&
952it sleeps waiting for the stall clear request to complete.
953The function
954.Fn usbd_clear_endpoint_stall_async
955performs the same function asynchronously, but it provides no
956way to determine when the request completed, or whether it was
957successful.
958The
959.Fn usbd_clear_endpoint_toggle
960function instructs the host controller driver to reset the toggle bit
961on a pipe.
962This is used when manually clearing an endpoint stall using a
963control pipe request, in order to ensure that the host controller
964driver and the USB device restart with the same toggle value.
488.Fa flags
489field has type "struct usb_xfer_flags" and allows one to set initial
490flags an USB transfer. Valid flags are:
491.Bl -tag
492.It force_short_xfer
493This flag forces the last transmitted USB packet to be short. A short
494packet has a length of less than "xfer->max_packet_size", which
495derives from "wMaxPacketSize". This flag can be changed during
496operation.
497.It short_xfer_ok
498This flag allows the received transfer length, "xfer->actlen" to be
499less than "xfer->sumlen" upon completion of a transfer. This flag can
500be changed during operation.
501.It short_frames_ok
502This flag allows the reception of multiple short USB frames. This flag
503only has effect for BULK and INTERRUPT endpoints and if the number of
504frames received is greater than 1. This flag can be changed during
505operation.
506.It pipe_bof
507This flag causes a failing USB transfer to remain first in the PIPE
508queue except in the case of "xfer->error" equal to
509"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
510will be started until either:
511.Bl -tag
512.It 1
513The failing USB transfer is stopped using "usbd_transfer_stop()".
514.It 2
515The failing USB transfer performs a successful transfer.
516.El
517The purpose of this flag is to avoid races when multiple transfers are
518queued for execution on an USB endpoint, and the first executing
519transfer fails leading to the need for clearing of stall for
520example.
521.
522In this case this flag is used to prevent the following USB transfers
523from being executed at the same time the clear-stall command is
524executed on the USB control endpoint.
525.
526This flag can be changed during operation.
965.Pp
527.Pp
966Normally the USB subsystem maps and copies data to and from
967DMA-capable memory each time a transfer is performed.
968The function
969.Fn usbd_alloc_buffer
970allocates a permanent DMA-capable buffer associated with the
971transfer to avoid this overhead.
972The return value is the virtual address of the buffer.
973Any time that
974.Fn usbd_setup_xfer
975is called on the transfer with the
976.Dv USBD_NO_COPY
977flag enabled, the allocated buffer will be used directly and
978the
979.Fa buffer
980argument passed to
981.Fn usbd_setup_xfer
982will be ignored.
983The
984.Fn usbd_get_buffer
985function returns a pointer to the virtual address of a buffer previously
986allocated by
987.Fn usbd_alloc_buffer .
988Finally,
989.Fn usbd_free_buffer
990deallocates the buffer.
528"BOF" is short for "Block On Failure"
991.Pp
529.Pp
992The
993.Fn usbd_errstr
994function converts a status code into a string for display.
530NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
531which use an endpoint that can be shared between userland and kernel.
532.
533.
534.It proxy_buffer
535Setting this flag will cause that the total buffer size will be
536rounded up to the nearest atomic hardware transfer size.
537.
538The maximum data length of any USB transfer is always stored in the
539"xfer->max_data_length".
540.
541For control transfers the USB kernel will allocate additional space
542for the 8-bytes of SETUP header.
543.
544These 8-bytes are not counted by the "xfer->max_data_length"
545variable.
546.
547This flag can not be changed during operation.
548.
549.
550.It ext_buffer
551Setting this flag will cause that no data buffer will be
552allocated.
553.
554Instead the USB client must supply a data buffer.
555.
556This flag can not be changed during operation.
557.
558.
559.It manual_status
560Setting this flag prevents an USB STATUS stage to be appended to the
561end of the USB control transfer.
562.
563If no control data is transferred this flag must be cleared.
564.
565Else an error will be returned to the USB callback.
566.
567This flag is mostly useful for the USB device side.
568.
569This flag can be changed during operation.
570.
571.
572.It no_pipe_ok
573Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
574flag can not be changed during operation.
575.
576.
577.It stall_pipe
578.Bl -tag
579.It Device Side Mode
580Setting this flag will cause STALL pids to be sent to the endpoint
581belonging to this transfer before the transfer is started.
582.
583The transfer is started at the moment the host issues a clear-stall
584command on the STALL'ed endpoint.
585.
586This flag can be changed during operation.
587.It Host Side Mode
588Setting this flag will cause a clear-stall control request to be
589executed on the endpoint before the USB transfer is started.
590.El
995.Pp
591.Pp
996The function
997.Fn usbd_set_polling
998enables or disables polling mode.
999In polling mode, all operations will busy-wait for the device to
1000respond, so its use is effectively limited to boot time and kernel
1001debuggers.
1002It is important to match up calls that enable and disable polling
1003mode, because the implementation just increments a polling reference
1004count when
1005.Fa on
1006is non-zero and decrements it when
1007.Fa on
1008is zero.
1009The
1010.Fn usbd_dopoll
1011causes the host controller driver to poll for any activity.
1012This should only be used when polling mode is enabled.
592If this flag is changed outside the USB callback function you have to
593use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()"
594functions! This flag is automatically cleared after that the stall or
595clear stall has been executed.
596.
597.El
1013.Pp
598.Pp
1014The
1015.Fn usbd_ratecheck
1016function is used to limit the rate at which error messages are
1017printed to approximately once per second.
1018The
1019.Fa last
1020argument should point at a persistent
1021.Vt "struct timeval" .
1022A value of 1 will be returned if a message should be printed, but if
1023.Fn usbd_ratecheck
1024has already been called with the same
1025.Vt "struct timeval"
1026parameter in the last second then 0 is returned and the error message
1027should be suppressed.
599.Fa bufsize
600field sets the total buffer size in bytes.
601.
602If this field is zero, "wMaxPacketSize" will be used, multiplied by
603the "frames" field if the transfer type is ISOCHRONOUS.
604.
605This is useful for setting up interrupt pipes.
606.
607This field is mandatory.
1028.Pp
608.Pp
1029The functions
1030.Fn usb_detach_wait
1031and
1032.Fn usb_detach_wakeup
1033are used to wait for references to drain before completing the
1034detachment of a device.
1035The
1036.Fn usb_detach_wait
1037function will wait up to 60 seconds to receive a signal from
1038.Fn usb_detach_wait .
1039.Ss "USB Descriptors"
1040The USB specification defines a number of standard descriptors by
1041which USB devices report their attributes.
1042These descriptors are fixed-format structures that all USB devices
1043make available through USB control pipe requests.
609NOTE: For control transfers "bufsize" includes the length of the
610request structure.
611.
1044.Pp
612.Pp
1045Every USB device has exactly one USB device descriptor.
1046The USB subsystem retrieves this automatically when a device is
1047attached, and a copy of the descriptor is kept in memory.
613.Fa callback
614pointer sets the USB callback. This field is mandatory.
615.
616.
617.Sh USB LINUX COMPAT LAYER
1048The
618The
1049.Fn usbd_get_device_descriptor
1050function returns a pointer to the descriptor.
1051The device descriptor structure is defined in
1052.In dev/usb/usb.h
1053as follows:
1054.Bd -literal
1055typedef struct {
1056 uByte bLength;
1057 uByte bDescriptorType;
1058 uWord bcdUSB;
1059#define UD_USB_2_0 0x0200
1060#define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
1061 uByte bDeviceClass;
1062 uByte bDeviceSubClass;
1063 uByte bDeviceProtocol;
1064 uByte bMaxPacketSize;
1065 /* The fields below are not part of the initial descriptor. */
1066 uWord idVendor;
1067 uWord idProduct;
1068 uWord bcdDevice;
1069 uByte iManufacturer;
1070 uByte iProduct;
1071 uByte iSerialNumber;
1072 uByte bNumConfigurations;
1073} UPACKED usb_device_descriptor_t;
1074#define USB_DEVICE_DESCRIPTOR_SIZE 18
1075.Ed
1076.Pp
1077USB devices have at least one configuration descriptor.
1078The
1079.Fa bNumConfigurations
1080field of the device descriptor specifies the number of configuration
1081descriptors that a device supports.
1082The
1083.Fn usbd_get_config_desc
1084function retrieves a particular configuration descriptor from the device
1085and the
1086.Fn usbd_get_config_desc_full
1087function retrieves a full
1088.Fa wTotalLength
1089length configuration descriptor, which includes all related interface
1090and endpoint descriptors.
1091Only one configuration may be active at a time.
1092The
1093.Fn usbd_set_config_index
1094function activates a specified configuration.
1095The configuration descriptor structure is defined in
1096.In dev/usb/usb.h
1097as follows:
1098.Bd -literal
1099typedef struct {
1100 uByte bLength;
1101 uByte bDescriptorType;
1102 uWord wTotalLength;
1103 uByte bNumInterface;
1104 uByte bConfigurationValue;
1105 uByte iConfiguration;
1106 uByte bmAttributes;
1107#define UC_BUS_POWERED 0x80
1108#define UC_SELF_POWERED 0x40
1109#define UC_REMOTE_WAKEUP 0x20
1110 uByte bMaxPower; /* max current in 2 mA units */
1111#define UC_POWER_FACTOR 2
1112} UPACKED usb_config_descriptor_t;
1113#define USB_CONFIG_DESCRIPTOR_SIZE 9
1114.Ed
1115.Pp
1116Each device configuration provides one or more interfaces.
1117The
1118.Fa bNumInterface
1119field of the configuration descriptor specifies the number of
1120interfaces associated with a device configuration.
1121Interfaces are described by an interface descriptor, which is defined in
1122.In dev/usb/usb.h
1123as follows:
1124.Bd -literal
1125typedef struct {
1126 uByte bLength;
1127 uByte bDescriptorType;
1128 uByte bInterfaceNumber;
1129 uByte bAlternateSetting;
1130 uByte bNumEndpoints;
1131 uByte bInterfaceClass;
1132 uByte bInterfaceSubClass;
1133 uByte bInterfaceProtocol;
1134 uByte iInterface;
1135} UPACKED usb_interface_descriptor_t;
1136#define USB_INTERFACE_DESCRIPTOR_SIZE 9
1137.Ed
1138.Pp
1139Configurations may also have alternate interfaces with the same
1140.Fa bInterfaceNumber
1141but different
1142.Fa bAlternateSetting
1143values.
1144These alternate interface settings may be selected by passing a
1145non-zero
1146.Fa altidx
1147parameter to
1148.Fn usbd_set_interface .
1149.Pp
1150Interfaces have zero or more endpoints, and each endpoint has an
1151endpoint descriptor.
1152Note that endpoint zero, which is always present, does not have an
1153endpoint descriptor, and it is never included in the
1154.Fa bNumEndpoints
1155count of endpoints.
1156The endpoint descriptor is defined in
1157.In dev/usb/usb.h
1158as follows:
1159.Bd -literal
1160typedef struct {
1161 uByte bLength;
1162 uByte bDescriptorType;
1163 uByte bEndpointAddress;
1164#define UE_GET_DIR(a) ((a) & 0x80)
1165#define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
1166#define UE_DIR_IN 0x80
1167#define UE_DIR_OUT 0x00
1168#define UE_ADDR 0x0f
1169#define UE_GET_ADDR(a) ((a) & UE_ADDR)
1170 uByte bmAttributes;
1171#define UE_XFERTYPE 0x03
1172#define UE_CONTROL 0x00
1173#define UE_ISOCHRONOUS 0x01
1174#define UE_BULK 0x02
1175#define UE_INTERRUPT 0x03
1176#define UE_GET_XFERTYPE(a) ((a) & UE_XFERTYPE)
1177#define UE_ISO_TYPE 0x0c
1178#define UE_ISO_ASYNC 0x04
1179#define UE_ISO_ADAPT 0x08
1180#define UE_ISO_SYNC 0x0c
1181#define UE_GET_ISO_TYPE(a) ((a) & UE_ISO_TYPE)
1182 uWord wMaxPacketSize;
1183 uByte bInterval;
1184} UPACKED usb_endpoint_descriptor_t;
1185#define USB_ENDPOINT_DESCRIPTOR_SIZE 7
1186.Ed
1187.Sh RETURN VALUES
1188Many functions return a
1189.Vt usbd_status
1190type to indicate the outcome of the operation.
1191If the operation completed successfully then
1192.Dv USBD_NORMAL_COMPLETION
1193is returned.
1194Operations that have been started but not yet completed will return
1195.Dv USBD_IN_PROGRESS .
1196Other errors usually indicate a problem.
1197Error codes can be converted to strings using
1198.Fn usbd_errstr .
1199.Sh ERRORS
1200.Bl -tag -width ".Er USBD_PENDING_REQUESTS"
1201.It Bq Er USBD_PENDING_REQUESTS
1202A pipe could not be closed because there are active requests.
1203.It Bq Er USBD_NOT_STARTED
1204The transfer has not yet been started.
1205.It Bq Er USBD_INVAL
1206An invalid value was supplied.
1207.It Bq Er USBD_NOMEM
1208An attempt to allocate memory failed.
1209.It Bq Er USBD_CANCELLED
1210The transfer was aborted.
1211.It Bq Er USBD_BAD_ADDRESS
1212The specified endpoint address was not found.
1213.It Bq Er USBD_IN_USE
1214The endpoint is already in use, or the configuration cannot be changed
1215because some of its endpoints are in use.
1216.It Bq Er USBD_NO_ADDR
1217No free USB devices addresses were found to assign to the device.
1218.It Bq Er USBD_SET_ADDR_FAILED
1219The device address could not be set.
1220.It Bq Er USBD_NO_POWER
1221Insufficient power was available for the device.
1222.It Bq Er USBD_TOO_DEEP
1223Too many levels of chained hubs were found.
1224.It Bq Er USBD_IOERROR
1225There was an error communicating with the device.
1226.It Bq Er USBD_NOT_CONFIGURED
1227An operation that requires an active configuration was attempted while
1228the device was in an unconfigured state.
1229.It Bq Er USBD_TIMEOUT
1230A transfer timed out.
1231.It Bq Er USBD_SHORT_XFER
1232A transfer that disallowed short data lengths completed with less than
1233the requested length transferred.
1234.It Bq Er USBD_STALLED
1235A transfer failed because the pipe is stalled.
1236.It Bq Er USBD_INTERRUPTED
1237An interruptible operation caught a signal.
1238.El
619.Nm usb
620module supports the Linux USB API.
621.
622.
1239.Sh SEE ALSO
623.Sh SEE ALSO
1240.Xr usb 4
624.Xr libusb 3 ,
625.Xr usb 4 ,
626.Xr usbconfig 8
627.Sh STANDARDS
628The
629.Nm usb
630module complies with the USB 2.0 standard.
1241.Sh HISTORY
631.Sh HISTORY
1242The USB driver interface first appeared in
1243.Fx 3.0 .
1244.Sh AUTHORS
1245The USB driver was written by
1246.An Lennart Augustsson
1247for the
1248.Nx
1249project.
1250.Pp
1251.An -nosplit
1252This manual page was written by
1253.An Ian Dowse Aq iedowse@FreeBSD.org .
632The
633.Nm usb
634module has been inspired by the NetBSD USB stack initially written by
635Lennart Augustsson. The
636.Nm usb
637module was written by
638.An Hans Petter Selasky Aq hselasky@freebsd.org .