2 .\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
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
26 .\" $FreeBSD: src/share/man/man9/usbdi.9,v 1.2 2006/12/14 14:33:13 mpp Exp $
33 .Nm usb_detach_wakeup ,
35 .Nm usbd_abort_default_pipe ,
37 .Nm usbd_alloc_buffer ,
39 .Nm usbd_bulk_transfer ,
40 .Nm usbd_clear_endpoint_stall ,
41 .Nm usbd_clear_endpoint_stall_async ,
42 .Nm usbd_clear_endpoint_toggle ,
44 .Nm usbd_device2interface_handle ,
47 .Nm usbd_do_request_async ,
48 .Nm usbd_do_request_flags ,
49 .Nm usbd_do_request_flags_pipe ,
51 .Nm usbd_endpoint_count ,
53 .Nm usbd_fill_deviceinfo ,
56 .Nm usbd_free_buffer ,
60 .Nm usbd_get_config_desc ,
61 .Nm usbd_get_config_desc_full ,
62 .Nm usbd_get_config_descriptor ,
63 .Nm usbd_get_device_descriptor ,
64 .Nm usbd_get_endpoint_descriptor ,
65 .Nm usbd_get_interface_altindex ,
66 .Nm usbd_get_interface_descriptor ,
67 .Nm usbd_get_no_alts ,
71 .Nm usbd_get_string_desc ,
72 .Nm usbd_get_xfer_status ,
73 .Nm usbd_interface2device_handle ,
74 .Nm usbd_interface2endpoint_descriptor ,
75 .Nm usbd_interface_count ,
76 .Nm usbd_intr_transfer ,
78 .Nm usbd_open_pipe_intr ,
79 .Nm usbd_pipe2device_handle ,
81 .Nm usbd_set_config_index ,
82 .Nm usbd_set_config_no ,
83 .Nm usbd_set_interface ,
84 .Nm usbd_set_polling ,
85 .Nm usbd_setup_default_xfer ,
86 .Nm usbd_setup_isoc_xfer ,
88 .Nm usbd_sync_transfer ,
90 .Nd Universal Serial Bus driver programming interface
96 .In bus/usb/usbdi_util.h
99 .Fn usb_detach_wait "device_t dv"
101 .Fn usb_detach_wakeup "device_t dv"
102 .Ft "const usb_descriptor_t *"
103 .Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
105 .Fn usbd_abort_default_pipe "usbd_device_handle dev"
107 .Fn usbd_abort_pipe "usbd_pipe_handle pipe"
109 .Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
111 .Fn usbd_alloc_xfer "usbd_device_handle dev"
113 .Fo usbd_bulk_transfer
114 .Fa "usbd_xfer_handle xfer"
115 .Fa "usbd_pipe_handle pipe"
116 .Fa "u_int16_t flags"
117 .Fa "u_int32_t timeout"
119 .Fa "u_int32_t *size"
123 .Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
125 .Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle pipe"
127 .Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
129 .Fn usbd_close_pipe "usbd_pipe_handle pipe"
131 .Fo usbd_device2interface_handle
132 .Fa "usbd_device_handle dev"
133 .Fa "u_int8_t ifaceno"
134 .Fa "usbd_interface_handle *iface"
137 .Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
140 .Fa "usbd_device_handle dev"
141 .Fa "usb_device_request_t *req"
145 .Fo usbd_do_request_async
146 .Fa "usbd_device_handle dev"
147 .Fa "usb_device_request_t *req"
151 .Fo usbd_do_request_flags
152 .Fa "usbd_device_handle dev"
153 .Fa "usb_device_request_t *req"
155 .Fa "u_int16_t flags"
160 .Fo usbd_do_request_flags_pipe
161 .Fa "usbd_device_handle dev"
162 .Fa "usbd_pipe_handle pipe"
163 .Fa "usb_device_request_t *req"
165 .Fa "u_int16_t flags"
167 .Fa "u_int32_t timeout"
170 .Fn usbd_dopoll "usbd_interface_handle iface"
172 .Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
174 .Fn usbd_errstr "usbd_status err"
176 .Fo usbd_fill_deviceinfo
177 .Fa "usbd_device_handle dev"
178 .Fa "struct usb_device_info *di"
181 .Ft "usb_endpoint_descriptor_t *"
183 .Fa "usb_config_descriptor_t *cd"
188 .Ft "usb_interface_descriptor_t *"
189 .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
191 .Fn usbd_free_buffer "usbd_xfer_handle xfer"
193 .Fn usbd_free_xfer "usbd_xfer_handle xfer"
195 .Fn usbd_get_buffer "usbd_xfer_handle xfer"
197 .Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
199 .Fo usbd_get_config_desc
200 .Fa "usbd_device_handle dev"
202 .Fa "usb_config_descriptor_t *d"
205 .Fo usbd_get_config_desc_full
206 .Fa "usbd_device_handle dev"
211 .Ft "usb_config_descriptor_t *"
212 .Fn usbd_get_config_descriptor "usbd_device_handle dev"
213 .Ft "usb_device_descriptor_t *"
214 .Fn usbd_get_device_descriptor "usbd_device_handle dev"
215 .Ft "usb_endpoint_descriptor_t *"
216 .Fo usbd_get_endpoint_descriptor
217 .Fa "usbd_interface_handle iface"
218 .Fa "u_int8_t address"
221 .Fn usbd_get_interface_altindex "usbd_interface_handle iface"
222 .Ft "usb_interface_descriptor_t *"
223 .Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
225 .Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
226 .Ft "const struct usbd_quirks *"
227 .Fn usbd_get_quirks "usbd_device_handle dev"
229 .Fn usbd_get_speed "usbd_device_handle dev"
231 .Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
233 .Fo usbd_get_string_desc
234 .Fa "usbd_device_handle dev"
237 .Fa "usb_string_descriptor_t *sdesc"
241 .Fo usbd_get_xfer_status
242 .Fa "usbd_xfer_handle xfer"
243 .Fa "usbd_private_handle *priv"
245 .Fa "u_int32_t *count"
246 .Fa "usbd_status *status"
249 .Fo usbd_interface2device_handle
250 .Fa "usbd_interface_handle iface"
251 .Fa "usbd_device_handle *dev"
253 .Ft "usb_endpoint_descriptor_t *"
254 .Fo usbd_interface2endpoint_descriptor
255 .Fa "usbd_interface_handle iface"
259 .Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
261 .Fo usbd_intr_transfer
262 .Fa "usbd_xfer_handle xfer"
263 .Fa "usbd_pipe_handle pipe"
264 .Fa "u_int16_t flags"
265 .Fa "u_int32_t timeout"
267 .Fa "u_int32_t *size"
272 .Fa "usbd_interface_handle iface"
273 .Fa "u_int8_t address"
275 .Fa "usbd_pipe_handle *pipe"
278 .Fo usbd_open_pipe_intr
279 .Fa "usbd_interface_handle iface"
280 .Fa "u_int8_t address"
282 .Fa "usbd_pipe_handle *pipe"
283 .Fa "usbd_private_handle priv"
286 .Fa "usbd_callback cb"
289 .Ft usbd_device_handle
290 .Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
292 .Fn usbd_ratecheck "struct timeval *last"
294 .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
296 .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
298 .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
300 .Fn usbd_set_polling "usbd_device_handle dev" "int on"
302 .Fo usbd_setup_default_xfer
303 .Fa "usbd_xfer_handle xfer"
304 .Fa "usbd_device_handle dev"
305 .Fa "usbd_private_handle priv"
306 .Fa "u_int32_t timeout"
307 .Fa "usb_device_request_t *req"
309 .Fa "u_int32_t length"
310 .Fa "u_int16_t flags"
311 .Fa "usbd_callback callback"
314 .Fo usbd_setup_isoc_xfer
315 .Fa "usbd_xfer_handle xfer"
316 .Fa "usbd_pipe_handle pipe"
317 .Fa "usbd_private_handle priv"
318 .Fa "u_int16_t *frlengths"
319 .Fa "u_int32_t nframes"
320 .Fa "u_int16_t flags"
321 .Fa "usbd_callback callback"
325 .Fa "usbd_xfer_handle xfer"
326 .Fa "usbd_pipe_handle pipe"
327 .Fa "usbd_private_handle priv"
329 .Fa "u_int32_t length"
330 .Fa "u_int16_t flags"
331 .Fa "u_int32_t timeout"
332 .Fa "usbd_callback callback"
335 .Fn usbd_sync_transfer "usbd_xfer_handle xfer"
337 .Fn usbd_transfer "usbd_xfer_handle xfer"
339 The Universal Serial Bus (USB) driver programming interface provides
340 USB peripheral drivers with a host controller independent API for
341 controlling and communicating with USB peripherals.
343 Typically, drivers will first use some combination of the functions
344 .Fn usbd_set_config_no ,
345 .Fn usbd_get_config_descriptor ,
346 .Fn usbd_set_interface ,
347 .Fn usbd_get_interface_descriptor ,
348 .Fn usbd_device2interface_handle ,
349 .Fn usbd_endpoint_count
351 .Fn usbd_interface2endpoint_descriptor
352 to query the device's properties and prepare it for use.
353 Drivers can then perform requests on the USB control pipe using
354 .Fn usbd_do_request ,
355 they can open pipes using the functions
358 .Fn usbd_open_pipe_intr ,
359 and perform transfers over these pipes using
360 .Fn usbd_alloc_xfer ,
364 Finally, the functions
365 .Fn usbd_abort_pipe ,
369 are used to cancel outstanding transfers, close open pipes and deallocate
373 .Fn usbd_get_device_descriptor
374 function returns a pointer to the USB device descriptor for
377 .Sx "USB Descriptors"
378 below for information about the USB device descriptor.
381 .Fn usbd_get_config_desc
382 function retrieves the specified configuration descriptor from the device.
385 parameter specifies the configuration descriptor index, which must be less
387 .Fa bNumConfigurations
388 value in the device descriptor.
390 .Fn usbd_get_config_desc_full
391 retrieves a full configuration descriptor, which has all related interface
392 and endpoint descriptors appended to a normal configuration descriptor.
395 should point to memory that is at least
397 bytes in length, and this should be at least as long as the
399 value from the configuration descriptor.
401 .Sx "USB Descriptors"
402 below for information about the USB configuration descriptor.
406 function retrieves the current configuration number from the device, i.e.\&
408 .Fa bConfigurationValue
409 value from the configuration that is active.
410 If the device is unconfigured then
413 The current configuration can be changed by calling either
414 .Fn usbd_set_config_index
416 .Fn usbd_set_config_no .
417 The difference between these functions is that
418 .Fn usbd_set_config_index
419 accepts a configuration index number that is less than the
420 .Fa bNumConfigurations
421 value from the device descriptor, whereas
422 .Fn usbd_set_config_no
424 .Fa bConfigurationValue
425 value of the desired configuration to be provided instead.
426 To unconfigure the device, supply a configuration index of
427 .Dv USB_UNCONFIG_INDEX
429 .Fn usbd_set_config_index ,
430 or else specify a configuration number of
433 .Fn usbd_set_config_no .
436 .Fn usbd_get_config_descriptor
437 function returns a pointer to an in-memory copy of the full configuration
438 descriptor of the configuration that is currently active.
439 The returned pointer remains valid until the device configuration
441 .Fn usbd_set_config_index
443 .Fn usbd_set_config_no .
444 If the device is unconfigured then
449 .Fn usbd_interface_count
450 returns the number of interfaces available in the current device
454 function determines the number of alternate interfaces in a full
455 configuration descriptor by counting the interface descriptors with
459 (the count includes alternate index zero).
462 function locates an interface descriptor within a full configuration
466 parameter specifies the interface index number, which should be less than
467 the number of interfaces in the configuration descriptor (i.e.\& the value
469 .Fn usbd_interface_count
472 field from the configuration descriptor).
473 An alternate interface can be specified using a non-zero
475 which should be less than the value returned by
476 .Fn usbd_get_no_alts .
477 The return value is a pointer to the requested interface descriptor
478 within the full configuration descriptor, or
480 if the specified interface descriptor does not exist.
483 parameter specifies the alternate setting by index number starting
484 at zero; it is not the alternate setting number defined in the
485 interface descriptor.
489 locates an endpoint descriptor within a full configuration descriptor.
494 parameters are the same as described for
495 .Fn usbd_find_idesc ,
498 parameter is an endpoint index number that should be less than the
500 field in the interface descriptor.
501 The return value is a pointer to the requested endpoint descriptor
502 within the full configuration descriptor, or
504 if the specified endpoint descriptor does not exist.
509 parameters are index numbers starting at zero; they are not the
510 alternate setting and endpoint address defined in the descriptors.
514 function returns the device speed.
521 USB devices optionally support string descriptors, which can be
525 .Fn usbd_get_string_desc
527 Device, configuration and interface descriptors reference strings by
528 an index number that can be supplied to these functions.
531 function should be used unless a non-default language is required.
534 points to a buffer of at least
535 .Dv USB_MAX_STRING_LEN
539 parameter specified which string to retrieve.
543 function searches through the in-memory full configuration descriptor
544 for the active configuration and finds the first descriptor that has a
551 .Dv USBD_SUBTYPE_ANY ,
552 the descriptor must also have a
553 .Fa bDescriptorSubtype
556 If found, then a pointer to the descriptor is returned.
561 The returned pointer is valid until the device configuration is changed using
562 .Fn usbd_set_config_index
564 .Fn usbd_set_config_no .
566 The USB driver interface uses opaque interface handles to refer to
567 configuration interfaces.
568 These handles remain valid until the device configuration is changed using
569 .Fn usbd_set_config_index
571 .Fn usbd_set_config_no .
573 .Fn usbd_device2interface_handle
574 function retrieves an interface handle.
577 parameter is an interface index number starting at zero.
578 If the device is configured and the specified interface exists, then
579 .Dv USBD_NORMAL_COMPLETION
580 is returned and the interface handle is stored in
582 Otherwise an error code is returned and
586 .Fn usbd_interface2device_handle
587 function retrieves the device handle from an interface handle.
588 This is just for convenience to save passing around the device
589 handle as well as the interface handle.
591 .Fn usbd_set_interface
592 function changes the alternate setting number for an interface to
593 the alternate setting identified by the zero-based index number
595 This operation invalidates any existing endpoints on this
596 interface and their descriptors.
598 .Fn usbd_get_interface_altindex
599 function returns the current alternative setting index as was
600 specified when calling
601 .Fn usbd_set_interface .
603 .Fn usbd_endpoint_count
604 function retrieves the number of endpoints associated with the
607 .Fn usbd_interface2endpoint_descriptor
608 function returns a pointer to an in-memory endpoint descriptor for
609 the endpoint that has an index number of
611 This pointer remains valid until the configuration or alternate setting
614 .Fn usbd_get_endpoint_descriptor
616 .Fn usbd_interface2endpoint_descriptor
619 address value instead of an index.
622 .Fn usbd_fill_deviceinfo
625 structure with information about the device.
626 The vendor and product names come from the device itself, falling back to
627 a table lookup or just providing the IDs in hexadecimal.
631 .Fn usbd_fill_deviceinfo
632 will not attempt to retrieve the vendor and product names from the
634 The usb_device_info structure is defined in
638 struct usb_device_info {
640 u_int8_t udi_addr; /* device address */
641 usb_event_cookie_t udi_cookie;
642 char udi_product[USB_MAX_STRING_LEN];
643 char udi_vendor[USB_MAX_STRING_LEN];
645 u_int16_t udi_productNo;
646 u_int16_t udi_vendorNo;
647 u_int16_t udi_releaseNo;
649 u_int8_t udi_subclass;
650 u_int8_t udi_protocol;
653 #define USB_SPEED_LOW 1
654 #define USB_SPEED_FULL 2
655 #define USB_SPEED_HIGH 3
656 int udi_power; /* power consumption in mA */
658 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
659 /* hub only: addresses of devices on ports */
660 u_int8_t udi_ports[16];
661 #define USB_PORT_ENABLED 0xff
662 #define USB_PORT_SUSPENDED 0xfe
663 #define USB_PORT_POWERED 0xfd
664 #define USB_PORT_DISABLED 0xfc
670 function generates a string description of the USB device.
673 argument should point to a 1024-byte buffer (XXX the maximum length
674 is approximately 320 chars, but there is no sanity checking and everything uses
675 1024-character buffers).
676 Device class information is included if the
678 parameter is non-zero.
682 function returns information from a table of devices that require
683 special workarounds in order to function correctly.
684 The returned structure is defined in
685 .In bus/usb/usb_quirks.h
689 u_int32_t uq_flags; /* Device problems */
694 .In bus/usb/usb_quirks.h
695 for a list of all currently defined quirks.
697 USB control requests are performed via
698 .Vt usb_device_request_t
699 structures, defined in
709 } UPACKED usb_device_request_t;
714 function performs a single request synchronously.
717 parameter should point to a properly initialized
718 .Vt usb_device_request_t ,
723 should point at a buffer that is at least
726 The request timeout is set to 5 seconds, so the operation will fail
729 if the device does not respond within that time.
731 .Fn usbd_do_request_async
733 .Fn usbd_do_request ,
734 but it does not wait for the request to complete before returning.
735 This routine does not block so it can be used from contexts where
736 sleeping is not allowed.
737 Note that there is no notification mechanism to report when the
738 operation completed nor is there a way to determine whether the
739 request succeeded, so this function is of limited use.
741 .Fn usbd_setup_default_xfer
744 for a way to invoke an asynchronous callback upon completion of
747 .Fn usbd_do_request_flags
749 .Fn usbd_do_request ,
750 but additional flags can be specified, the timeout is configurable,
751 and the actual number of bytes transferred is made available to the
754 .Fn usbd_do_request_flags_pipe
755 function uses a specified pipe instead of the default pipe.
759 creates a pipe connected to a specified endpoint on a specified interface.
764 value from one of this interface's endpoint descriptors.
768 .Dv USBD_EXCLUSIVE_USE
769 then the operation will only succeed if there are no open pipes
770 already connected to the specified endpoint.
772 .Fn usbd_open_pipe_intr
773 function creates an interrupt pipe connected to the specified endpoint.
778 value from one of this interface's endpoint descriptors.
781 parameter is passed to
782 .Fn usbd_setup_xfer .
787 parameters define a buffer that is to be used for the interrupt transfers.
788 The callback to be invoked each time a transfer completes is specified by
792 is an argument to be passed to the callback function.
795 parameter specifies the maximum acceptable interval between transfers;
796 in practice the transfers may occur more frequently.
798 .Fn usbd_pipe2device_handle
799 returns the device associated with the specified
804 function aborts all active or waiting transfers on the specified pipe.
805 Each transfer is aborted with a
807 status; callback routines must detect this error code to ensure that
808 they do not attempt to initiate a new transfer in response to one being
810 This routine blocks while it is waiting for the hardware to complete
811 processing of aborted transfers, so it is only safe to call it in
812 contexts where sleeping is allowed.
814 .Fn usbd_abort_default_pipe
815 aborts all active or waiting transfers on the default pipe.
817 .Fn usbd_abort_pipe ,
818 it blocks waiting for the hardware processing to complete.
820 When a pipe has no active or waiting transfers, the pipe may be closed
824 Once a pipe is closed, its pipe handle becomes invalid and may no longer
827 USB transfer handles are allocated using the function
829 and may be freed using
834 initializes a transfer handle with the details of a transfer to or from
838 parameter specifies the transfer handle to initialize,
840 specifies the pipe on which the transfer is to take place, and
842 is an argument that will be passed to callback function.
847 define the data buffer for the transfer.
856 parameter may contain the following flags:
857 .Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
859 This is used in association with
860 .Fn usbd_alloc_buffer
863 to use a dedicated DMA-capable buffer for the transfer.
864 .It Dv USBD_SYNCHRONOUS
865 Wait for the transfer to compete in
867 .It Dv USBD_SHORT_XFER_OK
868 Permit transfers shorter than the requested data length.
869 .It Dv USBD_FORCE_SHORT_XFER
870 Force a short transfer at the end of a write operation to let the
871 device know that the transfer has ended.
876 parameter specifies a timeout for the transfer in milliseconds.
879 indicates that no timeout should be configured.
882 specifies the function to call when the transfer completes.
885 does not actually initiate the transfer.
887 .Fn usbd_setup_default_xfer
888 initializes a control transfer for the default pipe.
891 parameter should point at a completed
892 .Vt usb_device_request_t
895 .Fn usbd_setup_isoc_xfer
896 initializes a transfer for an isochronous pipe.
900 initiates a transfer.
903 to indicate that the transfer has been queued.
904 If the USB stack is operating in polling mode, or if the transfer
906 .Dv USBD_NORMAL_COMPLETION
908 Other return values indicate that the transfer could not be
909 initiated due to an error.
911 .Fn usbd_sync_transfer
912 function executes a transfer synchronously.
913 It will sleep waiting for the transfer to complete and then return
915 Note that if the transfer has a callback routine, this will be
917 .Fn usbd_sync_transfer
921 .Fn usbd_intr_transfer
923 .Fn usbd_bulk_transfer
924 functions set up a transfer and wait synchronously for it to complete
925 but they allows signals to interrupt the wait.
928 if the transfer was interrupted by a signal.
929 XXX these two functions are identical apart from their names.
932 .Fn usbd_get_xfer_status
933 retrieves various information from a completed transfer.
936 parameter is not NULL then the callback private argument is
941 is not NULL then the transfer buffer pointer is stored in
943 The actual number of bytes transferred is stored in
948 Finally, the transfer status is stored in
955 .Fn usbd_clear_endpoint_stall
956 function clears an endpoint stall condition synchronously, i.e.\&
957 it sleeps waiting for the stall clear request to complete.
959 .Fn usbd_clear_endpoint_stall_async
960 performs the same function asynchronously, but it provides no
961 way to determine when the request completed, or whether it was
964 .Fn usbd_clear_endpoint_toggle
965 function instructs the host controller driver to reset the toggle bit
967 This is used when manually clearing an endpoint stall using a
968 control pipe request, in order to ensure that the host controller
969 driver and the USB device restart with the same toggle value.
971 Normally the USB subsystem maps and copies data to and from
972 DMA-capable memory each time a transfer is performed.
974 .Fn usbd_alloc_buffer
975 allocates a permanent DMA-capable buffer associated with the
976 transfer to avoid this overhead.
977 The return value is the virtual address of the buffer.
980 is called on the transfer with the
982 flag enabled, the allocated buffer will be used directly and
990 function returns a pointer to the virtual address of a buffer previously
992 .Fn usbd_alloc_buffer .
995 deallocates the buffer.
999 function converts a status code into a string for display.
1002 .Fn usbd_set_polling
1003 enables or disables polling mode.
1004 In polling mode, all operations will busy-wait for the device to
1005 respond, so its use is effectively limited to boot time and kernel
1007 It is important to match up calls that enable and disable polling
1008 mode, because the implementation just increments a polling reference
1011 is non-zero and decrements it when
1016 causes the host controller driver to poll for any activity.
1017 This should only be used when polling mode is enabled.
1021 function is used to limit the rate at which error messages are
1022 printed to approximately once per second.
1025 argument should point at a persistent
1026 .Vt "struct timeval" .
1027 A value of 1 will be returned if a message should be printed, but if
1029 has already been called with the same
1030 .Vt "struct timeval"
1031 parameter in the last second then 0 is returned and the error message
1032 should be suppressed.
1037 .Fn usb_detach_wakeup
1038 are used to wait for references to drain before completing the
1039 detachment of a device.
1042 function will wait up to 60 seconds to receive a signal from
1043 .Fn usb_detach_wait .
1044 .Ss "USB Descriptors"
1045 The USB specification defines a number of standard descriptors by
1046 which USB devices report their attributes.
1047 These descriptors are fixed-format structures that all USB devices
1048 make available through USB control pipe requests.
1050 Every USB device has exactly one USB device descriptor.
1051 The USB subsystem retrieves this automatically when a device is
1052 attached, and a copy of the descriptor is kept in memory.
1054 .Fn usbd_get_device_descriptor
1055 function returns a pointer to the descriptor.
1056 The device descriptor structure is defined in
1062 uByte bDescriptorType;
1064 #define UD_USB_2_0 0x0200
1065 #define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
1067 uByte bDeviceSubClass;
1068 uByte bDeviceProtocol;
1069 uByte bMaxPacketSize;
1070 /* The fields below are not part of the initial descriptor. */
1074 uByte iManufacturer;
1076 uByte iSerialNumber;
1077 uByte bNumConfigurations;
1078 } UPACKED usb_device_descriptor_t;
1079 #define USB_DEVICE_DESCRIPTOR_SIZE 18
1082 USB devices have at least one configuration descriptor.
1084 .Fa bNumConfigurations
1085 field of the device descriptor specifies the number of configuration
1086 descriptors that a device supports.
1088 .Fn usbd_get_config_desc
1089 function retrieves a particular configuration descriptor from the device
1091 .Fn usbd_get_config_desc_full
1092 function retrieves a full
1094 length configuration descriptor, which includes all related interface
1095 and endpoint descriptors.
1096 Only one configuration may be active at a time.
1098 .Fn usbd_set_config_index
1099 function activates a specified configuration.
1100 The configuration descriptor structure is defined in
1106 uByte bDescriptorType;
1108 uByte bNumInterface;
1109 uByte bConfigurationValue;
1110 uByte iConfiguration;
1112 #define UC_BUS_POWERED 0x80
1113 #define UC_SELF_POWERED 0x40
1114 #define UC_REMOTE_WAKEUP 0x20
1115 uByte bMaxPower; /* max current in 2 mA units */
1116 #define UC_POWER_FACTOR 2
1117 } UPACKED usb_config_descriptor_t;
1118 #define USB_CONFIG_DESCRIPTOR_SIZE 9
1121 Each device configuration provides one or more interfaces.
1124 field of the configuration descriptor specifies the number of
1125 interfaces associated with a device configuration.
1126 Interfaces are described by an interface descriptor, which is defined in
1132 uByte bDescriptorType;
1133 uByte bInterfaceNumber;
1134 uByte bAlternateSetting;
1135 uByte bNumEndpoints;
1136 uByte bInterfaceClass;
1137 uByte bInterfaceSubClass;
1138 uByte bInterfaceProtocol;
1140 } UPACKED usb_interface_descriptor_t;
1141 #define USB_INTERFACE_DESCRIPTOR_SIZE 9
1144 Configurations may also have alternate interfaces with the same
1145 .Fa bInterfaceNumber
1147 .Fa bAlternateSetting
1149 These alternate interface settings may be selected by passing a
1153 .Fn usbd_set_interface .
1155 Interfaces have zero or more endpoints, and each endpoint has an
1156 endpoint descriptor.
1157 Note that endpoint zero, which is always present, does not have an
1158 endpoint descriptor, and it is never included in the
1161 The endpoint descriptor is defined in
1167 uByte bDescriptorType;
1168 uByte bEndpointAddress;
1169 #define UE_GET_DIR(a) ((a) & 0x80)
1170 #define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
1171 #define UE_DIR_IN 0x80
1172 #define UE_DIR_OUT 0x00
1173 #define UE_ADDR 0x0f
1174 #define UE_GET_ADDR(a) ((a) & UE_ADDR)
1176 #define UE_XFERTYPE 0x03
1177 #define UE_CONTROL 0x00
1178 #define UE_ISOCHRONOUS 0x01
1179 #define UE_BULK 0x02
1180 #define UE_INTERRUPT 0x03
1181 #define UE_GET_XFERTYPE(a) ((a) & UE_XFERTYPE)
1182 #define UE_ISO_TYPE 0x0c
1183 #define UE_ISO_ASYNC 0x04
1184 #define UE_ISO_ADAPT 0x08
1185 #define UE_ISO_SYNC 0x0c
1186 #define UE_GET_ISO_TYPE(a) ((a) & UE_ISO_TYPE)
1187 uWord wMaxPacketSize;
1189 } UPACKED usb_endpoint_descriptor_t;
1190 #define USB_ENDPOINT_DESCRIPTOR_SIZE 7
1193 Many functions return a
1195 type to indicate the outcome of the operation.
1196 If the operation completed successfully then
1197 .Dv USBD_NORMAL_COMPLETION
1199 Operations that have been started but not yet completed will return
1200 .Dv USBD_IN_PROGRESS .
1201 Other errors usually indicate a problem.
1202 Error codes can be converted to strings using
1205 .Bl -tag -width ".Er USBD_PENDING_REQUESTS"
1206 .It Bq Er USBD_PENDING_REQUESTS
1207 A pipe could not be closed because there are active requests.
1208 .It Bq Er USBD_NOT_STARTED
1209 The transfer has not yet been started.
1210 .It Bq Er USBD_INVAL
1211 An invalid value was supplied.
1212 .It Bq Er USBD_NOMEM
1213 An attempt to allocate memory failed.
1214 .It Bq Er USBD_CANCELLED
1215 The transfer was aborted.
1216 .It Bq Er USBD_BAD_ADDRESS
1217 The specified endpoint address was not found.
1218 .It Bq Er USBD_IN_USE
1219 The endpoint is already in use, or the configuration cannot be changed
1220 because some of its endpoints are in use.
1221 .It Bq Er USBD_NO_ADDR
1222 No free USB devices addresses were found to assign to the device.
1223 .It Bq Er USBD_SET_ADDR_FAILED
1224 The device address could not be set.
1225 .It Bq Er USBD_NO_POWER
1226 Insufficient power was available for the device.
1227 .It Bq Er USBD_TOO_DEEP
1228 Too many levels of chained hubs were found.
1229 .It Bq Er USBD_IOERROR
1230 There was an error communicating with the device.
1231 .It Bq Er USBD_NOT_CONFIGURED
1232 An operation that requires an active configuration was attempted while
1233 the device was in an unconfigured state.
1234 .It Bq Er USBD_TIMEOUT
1235 A transfer timed out.
1236 .It Bq Er USBD_SHORT_XFER
1237 A transfer that disallowed short data lengths completed with less than
1238 the requested length transferred.
1239 .It Bq Er USBD_STALLED
1240 A transfer failed because the pipe is stalled.
1241 .It Bq Er USBD_INTERRUPTED
1242 An interruptible operation caught a signal.
1247 The USB driver interface first appeared in
1250 The USB driver was written by
1251 .An Lennart Augustsson
1257 This manual page was written by
1258 .An Ian Dowse Aq iedowse@FreeBSD.org .