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 $
27 .\" $DragonFly: src/share/man/man9/usbdi.9,v 1.2 2008/02/09 09:32:05 swildner 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
94 .In bus/usb/usbdi_util.h
97 .Fn usb_detach_wait "device_t dv"
99 .Fn usb_detach_wakeup "device_t dv"
100 .Ft "const usb_descriptor_t *"
101 .Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
103 .Fn usbd_abort_default_pipe "usbd_device_handle dev"
105 .Fn usbd_abort_pipe "usbd_pipe_handle pipe"
107 .Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
109 .Fn usbd_alloc_xfer "usbd_device_handle dev"
111 .Fo usbd_bulk_transfer
112 .Fa "usbd_xfer_handle xfer"
113 .Fa "usbd_pipe_handle pipe"
114 .Fa "u_int16_t flags"
115 .Fa "u_int32_t timeout"
117 .Fa "u_int32_t *size"
121 .Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
123 .Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle pipe"
125 .Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
127 .Fn usbd_close_pipe "usbd_pipe_handle pipe"
129 .Fo usbd_device2interface_handle
130 .Fa "usbd_device_handle dev"
131 .Fa "u_int8_t ifaceno"
132 .Fa "usbd_interface_handle *iface"
135 .Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
138 .Fa "usbd_device_handle dev"
139 .Fa "usb_device_request_t *req"
143 .Fo usbd_do_request_async
144 .Fa "usbd_device_handle dev"
145 .Fa "usb_device_request_t *req"
149 .Fo usbd_do_request_flags
150 .Fa "usbd_device_handle dev"
151 .Fa "usb_device_request_t *req"
153 .Fa "u_int16_t flags"
158 .Fo usbd_do_request_flags_pipe
159 .Fa "usbd_device_handle dev"
160 .Fa "usbd_pipe_handle pipe"
161 .Fa "usb_device_request_t *req"
163 .Fa "u_int16_t flags"
165 .Fa "u_int32_t timeout"
168 .Fn usbd_dopoll "usbd_interface_handle iface"
170 .Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
172 .Fn usbd_errstr "usbd_status err"
174 .Fo usbd_fill_deviceinfo
175 .Fa "usbd_device_handle dev"
176 .Fa "struct usb_device_info *di"
179 .Ft "usb_endpoint_descriptor_t *"
181 .Fa "usb_config_descriptor_t *cd"
186 .Ft "usb_interface_descriptor_t *"
187 .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
189 .Fn usbd_free_buffer "usbd_xfer_handle xfer"
191 .Fn usbd_free_xfer "usbd_xfer_handle xfer"
193 .Fn usbd_get_buffer "usbd_xfer_handle xfer"
195 .Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
197 .Fo usbd_get_config_desc
198 .Fa "usbd_device_handle dev"
200 .Fa "usb_config_descriptor_t *d"
203 .Fo usbd_get_config_desc_full
204 .Fa "usbd_device_handle dev"
209 .Ft "usb_config_descriptor_t *"
210 .Fn usbd_get_config_descriptor "usbd_device_handle dev"
211 .Ft "usb_device_descriptor_t *"
212 .Fn usbd_get_device_descriptor "usbd_device_handle dev"
213 .Ft "usb_endpoint_descriptor_t *"
214 .Fo usbd_get_endpoint_descriptor
215 .Fa "usbd_interface_handle iface"
216 .Fa "u_int8_t address"
219 .Fn usbd_get_interface_altindex "usbd_interface_handle iface"
220 .Ft "usb_interface_descriptor_t *"
221 .Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
223 .Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
224 .Ft "const struct usbd_quirks *"
225 .Fn usbd_get_quirks "usbd_device_handle dev"
227 .Fn usbd_get_speed "usbd_device_handle dev"
229 .Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
231 .Fo usbd_get_string_desc
232 .Fa "usbd_device_handle dev"
235 .Fa "usb_string_descriptor_t *sdesc"
239 .Fo usbd_get_xfer_status
240 .Fa "usbd_xfer_handle xfer"
241 .Fa "usbd_private_handle *priv"
243 .Fa "u_int32_t *count"
244 .Fa "usbd_status *status"
247 .Fo usbd_interface2device_handle
248 .Fa "usbd_interface_handle iface"
249 .Fa "usbd_device_handle *dev"
251 .Ft "usb_endpoint_descriptor_t *"
252 .Fo usbd_interface2endpoint_descriptor
253 .Fa "usbd_interface_handle iface"
257 .Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
259 .Fo usbd_intr_transfer
260 .Fa "usbd_xfer_handle xfer"
261 .Fa "usbd_pipe_handle pipe"
262 .Fa "u_int16_t flags"
263 .Fa "u_int32_t timeout"
265 .Fa "u_int32_t *size"
270 .Fa "usbd_interface_handle iface"
271 .Fa "u_int8_t address"
273 .Fa "usbd_pipe_handle *pipe"
276 .Fo usbd_open_pipe_intr
277 .Fa "usbd_interface_handle iface"
278 .Fa "u_int8_t address"
280 .Fa "usbd_pipe_handle *pipe"
281 .Fa "usbd_private_handle priv"
284 .Fa "usbd_callback cb"
287 .Ft usbd_device_handle
288 .Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
290 .Fn usbd_ratecheck "struct timeval *last"
292 .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
294 .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
296 .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
298 .Fn usbd_set_polling "usbd_device_handle dev" "int on"
300 .Fo usbd_setup_default_xfer
301 .Fa "usbd_xfer_handle xfer"
302 .Fa "usbd_device_handle dev"
303 .Fa "usbd_private_handle priv"
304 .Fa "u_int32_t timeout"
305 .Fa "usb_device_request_t *req"
307 .Fa "u_int32_t length"
308 .Fa "u_int16_t flags"
309 .Fa "usbd_callback callback"
312 .Fo usbd_setup_isoc_xfer
313 .Fa "usbd_xfer_handle xfer"
314 .Fa "usbd_pipe_handle pipe"
315 .Fa "usbd_private_handle priv"
316 .Fa "u_int16_t *frlengths"
317 .Fa "u_int32_t nframes"
318 .Fa "u_int16_t flags"
319 .Fa "usbd_callback callback"
323 .Fa "usbd_xfer_handle xfer"
324 .Fa "usbd_pipe_handle pipe"
325 .Fa "usbd_private_handle priv"
327 .Fa "u_int32_t length"
328 .Fa "u_int16_t flags"
329 .Fa "u_int32_t timeout"
330 .Fa "usbd_callback callback"
333 .Fn usbd_sync_transfer "usbd_xfer_handle xfer"
335 .Fn usbd_transfer "usbd_xfer_handle xfer"
337 The Universal Serial Bus (USB) driver programming interface provides
338 USB peripheral drivers with a host controller independent API for
339 controlling and communicating with USB peripherals.
341 Typically, drivers will first use some combination of the functions
342 .Fn usbd_set_config_no ,
343 .Fn usbd_get_config_descriptor ,
344 .Fn usbd_set_interface ,
345 .Fn usbd_get_interface_descriptor ,
346 .Fn usbd_device2interface_handle ,
347 .Fn usbd_endpoint_count
349 .Fn usbd_interface2endpoint_descriptor
350 to query the device's properties and prepare it for use.
351 Drivers can then perform requests on the USB control pipe using
352 .Fn usbd_do_request ,
353 they can open pipes using the functions
356 .Fn usbd_open_pipe_intr ,
357 and perform transfers over these pipes using
358 .Fn usbd_alloc_xfer ,
362 Finally, the functions
363 .Fn usbd_abort_pipe ,
367 are used to cancel outstanding transfers, close open pipes and deallocate
371 .Fn usbd_get_device_descriptor
372 function returns a pointer to the USB device descriptor for
375 .Sx "USB Descriptors"
376 below for information about the USB device descriptor.
379 .Fn usbd_get_config_desc
380 function retrieves the specified configuration descriptor from the device.
383 parameter specifies the configuration descriptor index, which must be less
385 .Fa bNumConfigurations
386 value in the device descriptor.
388 .Fn usbd_get_config_desc_full
389 retrieves a full configuration descriptor, which has all related interface
390 and endpoint descriptors appended to a normal configuration descriptor.
393 should point to memory that is at least
395 bytes in length, and this should be at least as long as the
397 value from the configuration descriptor.
399 .Sx "USB Descriptors"
400 below for information about the USB configuration descriptor.
404 function retrieves the current configuration number from the device, i.e.\&
406 .Fa bConfigurationValue
407 value from the configuration that is active.
408 If the device is unconfigured then
411 The current configuration can be changed by calling either
412 .Fn usbd_set_config_index
414 .Fn usbd_set_config_no .
415 The difference between these functions is that
416 .Fn usbd_set_config_index
417 accepts a configuration index number that is less than the
418 .Fa bNumConfigurations
419 value from the device descriptor, whereas
420 .Fn usbd_set_config_no
422 .Fa bConfigurationValue
423 value of the desired configuration to be provided instead.
424 To unconfigure the device, supply a configuration index of
425 .Dv USB_UNCONFIG_INDEX
427 .Fn usbd_set_config_index ,
428 or else specify a configuration number of
431 .Fn usbd_set_config_no .
434 .Fn usbd_get_config_descriptor
435 function returns a pointer to an in-memory copy of the full configuration
436 descriptor of the configuration that is currently active.
437 The returned pointer remains valid until the device configuration
439 .Fn usbd_set_config_index
441 .Fn usbd_set_config_no .
442 If the device is unconfigured then
447 .Fn usbd_interface_count
448 returns the number of interfaces available in the current device
452 function determines the number of alternate interfaces in a full
453 configuration descriptor by counting the interface descriptors with
457 (the count includes alternate index zero).
460 function locates an interface descriptor within a full configuration
464 parameter specifies the interface index number, which should be less than
465 the number of interfaces in the configuration descriptor (i.e.\& the value
467 .Fn usbd_interface_count
470 field from the configuration descriptor).
471 An alternate interface can be specified using a non-zero
473 which should be less than the value returned by
474 .Fn usbd_get_no_alts .
475 The return value is a pointer to the requested interface descriptor
476 within the full configuration descriptor, or
478 if the specified interface descriptor does not exist.
481 parameter specifies the alternate setting by index number starting
482 at zero; it is not the alternate setting number defined in the
483 interface descriptor.
487 locates an endpoint descriptor within a full configuration descriptor.
492 parameters are the same as described for
493 .Fn usbd_find_idesc ,
496 parameter is an endpoint index number that should be less than the
498 field in the interface descriptor.
499 The return value is a pointer to the requested endpoint descriptor
500 within the full configuration descriptor, or
502 if the specified endpoint descriptor does not exist.
507 parameters are index numbers starting at zero; they are not the
508 alternate setting and endpoint address defined in the descriptors.
512 function returns the device speed.
519 USB devices optionally support string descriptors, which can be
523 .Fn usbd_get_string_desc
525 Device, configuration and interface descriptors reference strings by
526 an index number that can be supplied to these functions.
529 function should be used unless a non-default language is required.
532 points to a buffer of at least
533 .Dv USB_MAX_STRING_LEN
537 parameter specified which string to retrieve.
541 function searches through the in-memory full configuration descriptor
542 for the active configuration and finds the first descriptor that has a
549 .Dv USBD_SUBTYPE_ANY ,
550 the descriptor must also have a
551 .Fa bDescriptorSubtype
554 If found, then a pointer to the descriptor is returned.
559 The returned pointer is valid until the device configuration is changed using
560 .Fn usbd_set_config_index
562 .Fn usbd_set_config_no .
564 The USB driver interface uses opaque interface handles to refer to
565 configuration interfaces.
566 These handles remain valid until the device configuration is changed using
567 .Fn usbd_set_config_index
569 .Fn usbd_set_config_no .
571 .Fn usbd_device2interface_handle
572 function retrieves an interface handle.
575 parameter is an interface index number starting at zero.
576 If the device is configured and the specified interface exists, then
577 .Dv USBD_NORMAL_COMPLETION
578 is returned and the interface handle is stored in
580 Otherwise an error code is returned and
584 .Fn usbd_interface2device_handle
585 function retrieves the device handle from an interface handle.
586 This is just for convenience to save passing around the device
587 handle as well as the interface handle.
589 .Fn usbd_set_interface
590 function changes the alternate setting number for an interface to
591 the alternate setting identified by the zero-based index number
593 This operation invalidates any existing endpoints on this
594 interface and their descriptors.
596 .Fn usbd_get_interface_altindex
597 function returns the current alternative setting index as was
598 specified when calling
599 .Fn usbd_set_interface .
601 .Fn usbd_endpoint_count
602 function retrieves the number of endpoints associated with the
605 .Fn usbd_interface2endpoint_descriptor
606 function returns a pointer to an in-memory endpoint descriptor for
607 the endpoint that has an index number of
609 This pointer remains valid until the configuration or alternate setting
612 .Fn usbd_get_endpoint_descriptor
614 .Fn usbd_interface2endpoint_descriptor
617 address value instead of an index.
620 .Fn usbd_fill_deviceinfo
623 structure with information about the device.
624 The vendor and product names come from the device itself, falling back to
625 a table lookup or just providing the IDs in hexadecimal.
629 .Fn usbd_fill_deviceinfo
630 will not attempt to retrieve the vendor and product names from the
632 The usb_device_info structure is defined in
636 struct usb_device_info {
638 u_int8_t udi_addr; /* device address */
639 usb_event_cookie_t udi_cookie;
640 char udi_product[USB_MAX_STRING_LEN];
641 char udi_vendor[USB_MAX_STRING_LEN];
643 u_int16_t udi_productNo;
644 u_int16_t udi_vendorNo;
645 u_int16_t udi_releaseNo;
647 u_int8_t udi_subclass;
648 u_int8_t udi_protocol;
651 #define USB_SPEED_LOW 1
652 #define USB_SPEED_FULL 2
653 #define USB_SPEED_HIGH 3
654 int udi_power; /* power consumption in mA */
656 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
657 /* hub only: addresses of devices on ports */
658 u_int8_t udi_ports[16];
659 #define USB_PORT_ENABLED 0xff
660 #define USB_PORT_SUSPENDED 0xfe
661 #define USB_PORT_POWERED 0xfd
662 #define USB_PORT_DISABLED 0xfc
668 function generates a string description of the USB device.
671 argument should point to a 1024-byte buffer (XXX the maximum length
672 is approximately 320 chars, but there is no sanity checking and everything uses
673 1024-character buffers).
674 Device class information is included if the
676 parameter is non-zero.
680 function returns information from a table of devices that require
681 special workarounds in order to function correctly.
682 The returned structure is defined in
683 .In bus/usb/usb_quirks.h
687 u_int32_t uq_flags; /* Device problems */
692 .In bus/usb/usb_quirks.h
693 for a list of all currently defined quirks.
695 USB control requests are performed via
696 .Vt usb_device_request_t
697 structures, defined in
707 } UPACKED usb_device_request_t;
712 function performs a single request synchronously.
715 parameter should point to a properly initialized
716 .Vt usb_device_request_t ,
721 should point at a buffer that is at least
724 The request timeout is set to 5 seconds, so the operation will fail
727 if the device does not respond within that time.
729 .Fn usbd_do_request_async
731 .Fn usbd_do_request ,
732 but it does not wait for the request to complete before returning.
733 This routine does not block so it can be used from contexts where
734 sleeping is not allowed.
735 Note that there is no notification mechanism to report when the
736 operation completed nor is there a way to determine whether the
737 request succeeded, so this function is of limited use.
739 .Fn usbd_setup_default_xfer
742 for a way to invoke an asynchronous callback upon completion of
745 .Fn usbd_do_request_flags
747 .Fn usbd_do_request ,
748 but additional flags can be specified, the timeout is configurable,
749 and the actual number of bytes transferred is made available to the
752 .Fn usbd_do_request_flags_pipe
753 function uses a specified pipe instead of the default pipe.
757 creates a pipe connected to a specified endpoint on a specified interface.
762 value from one of this interface's endpoint descriptors.
766 .Dv USBD_EXCLUSIVE_USE
767 then the operation will only succeed if there are no open pipes
768 already connected to the specified endpoint.
770 .Fn usbd_open_pipe_intr
771 function creates an interrupt pipe connected to the specified endpoint.
776 value from one of this interface's endpoint descriptors.
779 parameter is passed to
780 .Fn usbd_setup_xfer .
785 parameters define a buffer that is to be used for the interrupt transfers.
786 The callback to be invoked each time a transfer completes is specified by
790 is an argument to be passed to the callback function.
793 parameter specifies the maximum acceptable interval between transfers;
794 in practice the transfers may occur more frequently.
796 .Fn usbd_pipe2device_handle
797 returns the device associated with the specified
802 function aborts all active or waiting transfers on the specified pipe.
803 Each transfer is aborted with a
805 status; callback routines must detect this error code to ensure that
806 they do not attempt to initiate a new transfer in response to one being
808 This routine blocks while it is waiting for the hardware to complete
809 processing of aborted transfers, so it is only safe to call it in
810 contexts where sleeping is allowed.
812 .Fn usbd_abort_default_pipe
813 aborts all active or waiting transfers on the default pipe.
815 .Fn usbd_abort_pipe ,
816 it blocks waiting for the hardware processing to complete.
818 When a pipe has no active or waiting transfers, the pipe may be closed
822 Once a pipe is closed, its pipe handle becomes invalid and may no longer
825 USB transfer handles are allocated using the function
827 and may be freed using
832 initializes a transfer handle with the details of a transfer to or from
836 parameter specifies the transfer handle to initialize,
838 specifies the pipe on which the transfer is to take place, and
840 is an argument that will be passed to callback function.
845 define the data buffer for the transfer.
854 parameter may contain the following flags:
855 .Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
857 This is used in association with
858 .Fn usbd_alloc_buffer
861 to use a dedicated DMA-capable buffer for the transfer.
862 .It Dv USBD_SYNCHRONOUS
863 Wait for the transfer to compete in
865 .It Dv USBD_SHORT_XFER_OK
866 Permit transfers shorter than the requested data length.
867 .It Dv USBD_FORCE_SHORT_XFER
868 Force a short transfer at the end of a write operation to let the
869 device know that the transfer has ended.
874 parameter specifies a timeout for the transfer in milliseconds.
877 indicates that no timeout should be configured.
880 specifies the function to call when the transfer completes.
883 does not actually initiate the transfer.
885 .Fn usbd_setup_default_xfer
886 initializes a control transfer for the default pipe.
889 parameter should point at a completed
890 .Vt usb_device_request_t
893 .Fa usbd_setup_isoc_xfer
894 initializes a transfer for an isochronous pipe.
898 initiates a transfer.
901 to indicate that the transfer has been queued.
902 If the USB stack is operating in polling mode, or if the transfer
904 .Dv USBD_NORMAL_COMPLETION
906 Other return values indicate that the transfer could not be
907 initiated due to an error.
909 .Fn usbd_sync_transfer
910 function executes a transfer synchronously.
911 It will sleep waiting for the transfer to complete and then return
913 Note that if the transfer has a callback routine, this will be
915 .Fn usbd_sync_transfer
919 .Fn usbd_intr_transfer
921 .Fn usbd_bulk_transfer
922 functions set up a transfer and wait synchronously for it to complete
923 but they allows signals to interrupt the wait.
926 if the transfer was interrupted by a signal.
927 XXX these two functions are identical apart from their names.
930 .Fn usbd_get_xfer_status
931 retrieves various information from a completed transfer.
934 parameter is not NULL then the callback private argument is
939 is not NULL then the transfer buffer pointer is stored in
941 The actual number of bytes transferred is stored in
946 Finally, the transfer status is stored in
953 .Fn usbd_clear_endpoint_stall
954 function clears an endpoint stall condition synchronously, i.e.\&
955 it sleeps waiting for the stall clear request to complete.
957 .Fn usbd_clear_endpoint_stall_async
958 performs the same function asynchronously, but it provides no
959 way to determine when the request completed, or whether it was
962 .Fn usbd_clear_endpoint_toggle
963 function instructs the host controller driver to reset the toggle bit
965 This is used when manually clearing an endpoint stall using a
966 control pipe request, in order to ensure that the host controller
967 driver and the USB device restart with the same toggle value.
969 Normally the USB subsystem maps and copies data to and from
970 DMA-capable memory each time a transfer is performed.
972 .Fn usbd_alloc_buffer
973 allocates a permanent DMA-capable buffer associated with the
974 transfer to avoid this overhead.
975 The return value is the virtual address of the buffer.
978 is called on the transfer with the
980 flag enabled, the allocated buffer will be used directly and
988 function returns a pointer to the virtual address of a buffer previously
990 .Fn usbd_alloc_buffer .
993 deallocates the buffer.
997 function converts a status code into a string for display.
1000 .Fn usbd_set_polling
1001 enables or disables polling mode.
1002 In polling mode, all operations will busy-wait for the device to
1003 respond, so its use is effectively limited to boot time and kernel
1005 It is important to match up calls that enable and disable polling
1006 mode, because the implementation just increments a polling reference
1009 is non-zero and decrements it when
1014 causes the host controller driver to poll for any activity.
1015 This should only be used when polling mode is enabled.
1019 function is used to limit the rate at which error messages are
1020 printed to approximately once per second.
1023 argument should point at a persistent
1024 .Vt "struct timeval" .
1025 A value of 1 will be returned if a message should be printed, but if
1027 has already been called with the same
1028 .Vt "struct timeval"
1029 parameter in the last second then 0 is returned and the error message
1030 should be suppressed.
1035 .Fn usb_detach_wakeup
1036 are used to wait for references to drain before completing the
1037 detachment of a device.
1040 function will wait up to 60 seconds to receive a signal from
1041 .Fn usb_detach_wait .
1042 .Ss "USB Descriptors"
1043 The USB specification defines a number of standard descriptors by
1044 which USB devices report their attributes.
1045 These descriptors are fixed-format structures that all USB devices
1046 make available through USB control pipe requests.
1048 Every USB device has exactly one USB device descriptor.
1049 The USB subsystem retrieves this automatically when a device is
1050 attached, and a copy of the descriptor is kept in memory.
1052 .Fn usbd_get_device_descriptor
1053 function returns a pointer to the descriptor.
1054 The device descriptor structure is defined in
1060 uByte bDescriptorType;
1062 #define UD_USB_2_0 0x0200
1063 #define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
1065 uByte bDeviceSubClass;
1066 uByte bDeviceProtocol;
1067 uByte bMaxPacketSize;
1068 /* The fields below are not part of the initial descriptor. */
1072 uByte iManufacturer;
1074 uByte iSerialNumber;
1075 uByte bNumConfigurations;
1076 } UPACKED usb_device_descriptor_t;
1077 #define USB_DEVICE_DESCRIPTOR_SIZE 18
1080 USB devices have at least one configuration descriptor.
1082 .Fa bNumConfigurations
1083 field of the device descriptor specifies the number of configuration
1084 descriptors that a device supports.
1086 .Fn usbd_get_config_desc
1087 function retrieves a particular configuration descriptor from the device
1089 .Fn usbd_get_config_desc_full
1090 function retrieves a full
1092 length configuration descriptor, which includes all related interface
1093 and endpoint descriptors.
1094 Only one configuration may be active at a time.
1096 .Fn usbd_set_config_index
1097 function activates a specified configuration.
1098 The configuration descriptor structure is defined in
1104 uByte bDescriptorType;
1106 uByte bNumInterface;
1107 uByte bConfigurationValue;
1108 uByte iConfiguration;
1110 #define UC_BUS_POWERED 0x80
1111 #define UC_SELF_POWERED 0x40
1112 #define UC_REMOTE_WAKEUP 0x20
1113 uByte bMaxPower; /* max current in 2 mA units */
1114 #define UC_POWER_FACTOR 2
1115 } UPACKED usb_config_descriptor_t;
1116 #define USB_CONFIG_DESCRIPTOR_SIZE 9
1119 Each device configuration provides one or more interfaces.
1122 field of the configuration descriptor specifies the number of
1123 interfaces associated with a device configuration.
1124 Interfaces are described by an interface descriptor, which is defined in
1130 uByte bDescriptorType;
1131 uByte bInterfaceNumber;
1132 uByte bAlternateSetting;
1133 uByte bNumEndpoints;
1134 uByte bInterfaceClass;
1135 uByte bInterfaceSubClass;
1136 uByte bInterfaceProtocol;
1138 } UPACKED usb_interface_descriptor_t;
1139 #define USB_INTERFACE_DESCRIPTOR_SIZE 9
1142 Configurations may also have alternate interfaces with the same
1143 .Fa bInterfaceNumber
1145 .Fa bAlternateSetting
1147 These alternate interface settings may be selected by passing a
1151 .Fn usbd_set_interface .
1153 Interfaces have zero or more endpoints, and each endpoint has an
1154 endpoint descriptor.
1155 Note that endpoint zero, which is always present, does not have an
1156 endpoint descriptor, and it is never included in the
1159 The endpoint descriptor is defined in
1165 uByte bDescriptorType;
1166 uByte bEndpointAddress;
1167 #define UE_GET_DIR(a) ((a) & 0x80)
1168 #define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
1169 #define UE_DIR_IN 0x80
1170 #define UE_DIR_OUT 0x00
1171 #define UE_ADDR 0x0f
1172 #define UE_GET_ADDR(a) ((a) & UE_ADDR)
1174 #define UE_XFERTYPE 0x03
1175 #define UE_CONTROL 0x00
1176 #define UE_ISOCHRONOUS 0x01
1177 #define UE_BULK 0x02
1178 #define UE_INTERRUPT 0x03
1179 #define UE_GET_XFERTYPE(a) ((a) & UE_XFERTYPE)
1180 #define UE_ISO_TYPE 0x0c
1181 #define UE_ISO_ASYNC 0x04
1182 #define UE_ISO_ADAPT 0x08
1183 #define UE_ISO_SYNC 0x0c
1184 #define UE_GET_ISO_TYPE(a) ((a) & UE_ISO_TYPE)
1185 uWord wMaxPacketSize;
1187 } UPACKED usb_endpoint_descriptor_t;
1188 #define USB_ENDPOINT_DESCRIPTOR_SIZE 7
1191 Many functions return a
1193 type to indicate the outcome of the operation.
1194 If the operation completed successfully then
1195 .Dv USBD_NORMAL_COMPLETION
1197 Operations that have been started but not yet completed will return
1198 .Dv USBD_IN_PROGRESS .
1199 Other errors usually indicate a problem.
1200 Error codes can be converted to strings using
1203 .Bl -tag -width ".Er USBD_PENDING_REQUESTS"
1204 .It Bq Er USBD_PENDING_REQUESTS
1205 A pipe could not be closed because there are active requests.
1206 .It Bq Er USBD_NOT_STARTED
1207 The transfer has not yet been started.
1208 .It Bq Er USBD_INVAL
1209 An invalid value was supplied.
1210 .It Bq Er USBD_NOMEM
1211 An attempt to allocate memory failed.
1212 .It Bq Er USBD_CANCELLED
1213 The transfer was aborted.
1214 .It Bq Er USBD_BAD_ADDRESS
1215 The specified endpoint address was not found.
1216 .It Bq Er USBD_IN_USE
1217 The endpoint is already in use, or the configuration cannot be changed
1218 because some of its endpoints are in use.
1219 .It Bq Er USBD_NO_ADDR
1220 No free USB devices addresses were found to assign to the device.
1221 .It Bq Er USBD_SET_ADDR_FAILED
1222 The device address could not be set.
1223 .It Bq Er USBD_NO_POWER
1224 Insufficient power was available for the device.
1225 .It Bq Er USBD_TOO_DEEP
1226 Too many levels of chained hubs were found.
1227 .It Bq Er USBD_IOERROR
1228 There was an error communicating with the device.
1229 .It Bq Er USBD_NOT_CONFIGURED
1230 An operation that requires an active configuration was attempted while
1231 the device was in an unconfigured state.
1232 .It Bq Er USBD_TIMEOUT
1233 A transfer timed out.
1234 .It Bq Er USBD_SHORT_XFER
1235 A transfer that disallowed short data lengths completed with less than
1236 the requested length transferred.
1237 .It Bq Er USBD_STALLED
1238 A transfer failed because the pipe is stalled.
1239 .It Bq Er USBD_INTERRUPTED
1240 An interruptible operation caught a signal.
1245 The USB driver interface first appeared in
1248 The USB driver was written by
1249 .An Lennart Augustsson
1255 This manual page was written by
1256 .An Ian Dowse Aq iedowse@FreeBSD.org .
lentferj's projects / dragonfly.git / blob