Linux Certif

Toute la documentation sur la certification Linux LPI

usbd_clear_endpoint_stall.9freebsd

BSD mandoc

NAME

usb_detach_wait usb_detach_wakeup usb_find_desc usbd_abort_default_pipe usbd_abort_pipe usbd_alloc_buffer usbd_alloc_xfer usbd_bulk_transfer usbd_clear_endpoint_stall usbd_clear_endpoint_stall_async usbd_clear_endpoint_toggle usbd_close_pipe usbd_device2interface_handle usbd_devinfo usbd_do_request usbd_do_request_async usbd_do_request_flags usbd_do_request_flags_pipe usbd_dopoll usbd_endpoint_count usbd_errstr usbd_fill_deviceinfo usbd_find_edesc usbd_find_idesc usbd_free_buffer usbd_free_xfer usbd_get_buffer usbd_get_config usbd_get_config_desc usbd_get_config_desc_full usbd_get_config_descriptor usbd_get_device_descriptor usbd_get_endpoint_descriptor usbd_get_interface_altindex usbd_get_interface_descriptor usbd_get_no_alts usbd_get_quirks usbd_get_speed usbd_get_string usbd_get_string_desc usbd_get_xfer_status usbd_interface2device_handle usbd_interface2endpoint_descriptor usbd_interface_count usbd_intr_transfer usbd_open_pipe usbd_open_pipe_intr usbd_pipe2device_handle usbd_ratecheck usbd_set_config_index usbd_set_config_no usbd_set_interface usbd_set_polling usbd_setup_default_xfer usbd_setup_isoc_xfer usbd_setup_xfer usbd_sync_transfer usbd_transfer - Universal Serial Bus driver programming interface

SYNOPSIS

In dev/usb/usb.h In dev/usb/usbdi.h In dev/usb/usbdi_util.h

Ft void Fn usb_detach_wait device_ptr_t dv Ft void Fn usb_detach_wakeup device_ptr_t dv Ft const usb_descriptor_t * Fn usb_find_desc usbd_device_handle dev int type int subtype Ft usbd_status Fn usbd_abort_default_pipe usbd_device_handle dev Ft usbd_status Fn usbd_abort_pipe usbd_pipe_handle pipe Ft void * Fn usbd_alloc_buffer usbd_xfer_handle xfer u_int32_t size Ft usbd_xfer_handle Fn usbd_alloc_xfer usbd_device_handle dev Ft usbd_status Fo usbd_bulk_transfer Fa usbd_xfer_handle xfer Fa usbd_pipe_handle pipe Fa u_int16_t flags Fa u_int32_t timeout Fa void *buf Fa u_int32_t *size Fa char *lbl Fc Ft usbd_status Fn usbd_clear_endpoint_stall usbd_pipe_handle pipe Ft usbd_status Fn usbd_clear_endpoint_stall_async usbd_pipe_handle Ft void Fn usbd_clear_endpoint_toggle usbd_pipe_handle pipe Ft usbd_status Fn usbd_close_pipe usbd_pipe_handle pipe Ft usbd_status Fo usbd_device2interface_handle Fa usbd_device_handle dev Fa u_int8_t ifaceno Fa usbd_interface_handle *iface Fc Ft void Fn usbd_devinfo usbd_device_handle dev int showclass char *cp Ft usbd_status Fo usbd_do_request Fa usbd_device_handle dev Fa usb_device_request_t *req Fa void *data Fc Ft usbd_status Fo usbd_do_request_async Fa usbd_device_handle dev Fa usb_device_request_t *req Fa void *data Fc Ft usbd_status Fo usbd_do_request_flags Fa usbd_device_handle dev Fa usb_device_request_t *req Fa void *data Fa u_int16_t flags Fa int *actlen Fa u_int32_t timo Fc Ft usbd_status Fo usbd_do_request_flags_pipe Fa usbd_device_handle dev Fa usbd_pipe_handle pipe Fa usb_device_request_t *req Fa void *data Fa u_int16_t flags Fa int *actlen Fa u_int32_t timeout Fc Ft void Fn usbd_dopoll usbd_interface_handle iface Ft usbd_status Fn usbd_endpoint_count usbd_interface_handle iface u_int8_t *count Ft const char * Fn usbd_errstr usbd_status err Ft void Fo usbd_fill_deviceinfo Fa usbd_device_handle dev Fa struct usb_device_info *di Fa int usedev Fc Ft usb_endpoint_descriptor_t * Fo usbd_find_edesc Fa usb_config_descriptor_t *cd Fa int ifaceidx Fa int altidx Fa int endptidx Fc Ft usb_interface_descriptor_t * Fn usbd_find_idesc usb_config_descriptor_t *cd int ifaceidx int altidx Ft void Fn usbd_free_buffer usbd_xfer_handle xfer Ft usbd_status Fn usbd_free_xfer usbd_xfer_handle xfer Ft void * Fn usbd_get_buffer usbd_xfer_handle xfer Ft usbd_status Fn usbd_get_config usbd_device_handle dev u_int8_t *conf Ft usbd_status Fo usbd_get_config_desc Fa usbd_device_handle dev Fa int confidx Fa usb_config_descriptor_t *d Fc Ft usbd_status Fo usbd_get_config_desc_full Fa usbd_device_handle dev Fa int conf Fa void *d Fa int size Fc Ft usb_config_descriptor_t * Fn usbd_get_config_descriptor usbd_device_handle dev Ft usb_device_descriptor_t * Fn usbd_get_device_descriptor usbd_device_handle dev Ft usb_endpoint_descriptor_t * Fo usbd_get_endpoint_descriptor Fa usbd_interface_handle iface Fa u_int8_t address Fc Ft int Fn usbd_get_interface_altindex usbd_interface_handle iface Ft usb_interface_descriptor_t * Fn usbd_get_interface_descriptor usbd_interface_handle iface Ft int Fn usbd_get_no_alts usb_config_descriptor_t *cdesc int ifaceno Ft const struct usbd_quirks * Fn usbd_get_quirks usbd_device_handle dev Ft int Fn usbd_get_speed usbd_device_handle dev Ft usbd_status Fn usbd_get_string usbd_device_handle dev int si char *buf Ft usbd_status Fo usbd_get_string_desc Fa usbd_device_handle dev Fa int sindex Fa int langid Fa usb_string_descriptor_t *sdesc Fa int *sizep Fc Ft void Fo usbd_get_xfer_status Fa usbd_xfer_handle xfer Fa usbd_private_handle *priv Fa void **buffer Fa u_int32_t *count Fa usbd_status *status Fc Ft void Fo usbd_interface2device_handle Fa usbd_interface_handle iface Fa usbd_device_handle *dev Fc Ft usb_endpoint_descriptor_t * Fo usbd_interface2endpoint_descriptor Fa usbd_interface_handle iface Fa u_int8_t index Fc Ft usbd_status Fn usbd_interface_count usbd_device_handle dev u_int8_t *count Ft usbd_status Fo usbd_intr_transfer Fa usbd_xfer_handle xfer Fa usbd_pipe_handle pipe Fa u_int16_t flags Fa u_int32_t timeout Fa void *buf Fa u_int32_t *size Fa char *lbl Fc Ft usbd_status Fo usbd_open_pipe Fa usbd_interface_handle iface Fa u_int8_t address Fa u_int8_t flags Fa usbd_pipe_handle *pipe Fc Ft usbd_status Fo usbd_open_pipe_intr Fa usbd_interface_handle iface Fa u_int8_t address Fa u_int8_t flags Fa usbd_pipe_handle *pipe Fa usbd_private_handle priv Fa void *buffer Fa u_int32_t len Fa usbd_callback cb Fa int ival Fc Ft usbd_device_handle Fn usbd_pipe2device_handle usbd_pipe_handle pipe Ft int Fn usbd_ratecheck struct timeval *last Ft usbd_status Fn usbd_set_config_index usbd_device_handle dev int index int msg Ft usbd_status Fn usbd_set_config_no usbd_device_handle dev int no int msg Ft usbd_status Fn usbd_set_interface usbd_interface_handle iface int altidx Ft void Fn usbd_set_polling usbd_device_handle dev int on Ft void Fo usbd_setup_default_xfer Fa usbd_xfer_handle xfer Fa usbd_device_handle dev Fa usbd_private_handle priv Fa u_int32_t timeout Fa usb_device_request_t *req Fa void *buffer Fa u_int32_t length Fa u_int16_t flags Fa usbd_callback callback Fc Ft void Fo usbd_setup_isoc_xfer Fa usbd_xfer_handle xfer Fa usbd_pipe_handle pipe Fa usbd_private_handle priv Fa u_int16_t *frlengths Fa u_int32_t nframes Fa u_int16_t flags Fa usbd_callback callback Fc Ft void Fo usbd_setup_xfer Fa usbd_xfer_handle xfer Fa usbd_pipe_handle pipe Fa usbd_private_handle priv Fa void *buffer Fa u_int32_t length Fa u_int16_t flags Fa u_int32_t timeout Fa usbd_callback callback Fc Ft usbd_status Fn usbd_sync_transfer usbd_xfer_handle xfer Ft usbd_status Fn usbd_transfer usbd_xfer_handle xfer

DESCRIPTION

The Universal Serial Bus (USB) driver programming interface provides USB peripheral drivers with a host controller independent API for controlling and communicating with USB peripherals.

Typically, drivers will first use some combination of the functions Fn usbd_set_config_no , Fn usbd_get_config_descriptor , Fn usbd_set_interface , Fn usbd_get_interface_descriptor , Fn usbd_device2interface_handle , Fn usbd_endpoint_count and Fn usbd_interface2endpoint_descriptor to query the device's properties and prepare it for use. Drivers can then perform requests on the USB control pipe using Fn usbd_do_request , they can open pipes using the functions Fn usbd_open_pipe and Fn usbd_open_pipe_intr , and perform transfers over these pipes using Fn usbd_alloc_xfer , Fn usbd_setup_xfer and Fn usbd_transfer . Finally, the functions Fn usbd_abort_pipe , Fn usbd_close_pipe and Fn usbd_free_xfer are used to cancel outstanding transfers, close open pipes and deallocate transfer structures.

The Fn usbd_get_device_descriptor function returns a pointer to the USB device descriptor for Fa dev . See Sx USB Descriptors below for information about the USB device descriptor.

The Fn usbd_get_config_desc function retrieves the specified configuration descriptor from the device. The Fa confidx parameter specifies the configuration descriptor index, which must be less than the Fa bNumConfigurations value in the device descriptor. The function Fn usbd_get_config_desc_full retrieves a full configuration descriptor, which has all related interface and endpoint descriptors appended to a normal configuration descriptor. The parameter Fa d should point to memory that is at least Fa size bytes in length, and this should be at least as long as the Fa wTotalLength value from the configuration descriptor. See Sx USB Descriptors below for information about the USB configuration descriptor.

The Fn usbd_get_config function retrieves the current configuration number from the device, i.e. the Fa bConfigurationValue value from the configuration that is active. If the device is unconfigured then USB_UNCONFIG_NO is returned. The current configuration can be changed by calling either Fn usbd_set_config_index or Fn usbd_set_config_no . The difference between these functions is that Fn usbd_set_config_index accepts a configuration index number that is less than the Fa bNumConfigurations value from the device descriptor, whereas Fn usbd_set_config_no requires the Fa bConfigurationValue value of the desired configuration to be provided instead. To unconfigure the device, supply a configuration index of USB_UNCONFIG_INDEX to Fn usbd_set_config_index , or else specify a configuration number of USB_UNCONFIG_NO to Fn usbd_set_config_no .

The Fn usbd_get_config_descriptor function returns a pointer to an in-memory copy of the full configuration descriptor of the configuration that is currently active. The returned pointer remains valid until the device configuration is changed using Fn usbd_set_config_index or Fn usbd_set_config_no . If the device is unconfigured then NULL is returned instead.

The function Fn usbd_interface_count returns the number of interfaces available in the current device configuration. The Fn usbd_get_no_alts function determines the number of alternate interfaces in a full configuration descriptor by counting the interface descriptors with Fa bInterfaceNumber equal to Fa ifaceno (the count includes alternate index zero). The Fn usbd_find_idesc function locates an interface descriptor within a full configuration descriptor. The Fa ifaceidx parameter specifies the interface index number, which should be less than the number of interfaces in the configuration descriptor (i.e. the value returned by Fn usbd_interface_count or the Fa bNumInterface field from the configuration descriptor). An alternate interface can be specified using a non-zero Fa altidx , which should be less than the value returned by Fn usbd_get_no_alts . The return value is a pointer to the requested interface descriptor within the full configuration descriptor, or NULL if the specified interface descriptor does not exist. Note that the Fa altidx parameter specifies the alternate setting by index number starting at zero; it is not the alternate setting number defined in the interface descriptor.

The function Fn usbd_find_edesc locates an endpoint descriptor within a full configuration descriptor. The Fa ifaceidx and Fa altidx parameters are the same as described for Fn usbd_find_idesc , and the Fa endptidx parameter is an endpoint index number that should be less than the Fa bNumEndpoints field in the interface descriptor. The return value is a pointer to the requested endpoint descriptor within the full configuration descriptor, or NULL if the specified endpoint descriptor does not exist. Note that the Fa altidx and Fa endptidx parameters are index numbers starting at zero; they are not the alternate setting and endpoint address defined in the descriptors.

The Fn usbd_get_speed function returns the device speed. This can be USB_SPEED_LOW USB_SPEED_FULL or USB_SPEED_HIGH

USB devices optionally support string descriptors, which can be retrieved using the Fn usbd_get_string or Fn usbd_get_string_desc functions. Device, configuration and interface descriptors reference strings by an index number that can be supplied to these functions. The Fn usbd_get_string function should be used unless a non-default language is required. It requires that Fa buf points to a buffer of at least USB_MAX_STRING_LEN bytes in size. The Fa si parameter specified which string to retrieve.

The Fn usb_find_desc function searches through the in-memory full configuration descriptor for the active configuration and finds the first descriptor that has a Fa bDescriptorType equal to Fa type , and if Fa subtype is not equal to USBD_SUBTYPE_ANY the descriptor must also have a Fa bDescriptorSubtype equal to Fa subtype . If found, then a pointer to the descriptor is returned. Otherwise, Fn usb_find_desc returns NULL The returned pointer is valid until the device configuration is changed using Fn usbd_set_config_index or Fn usbd_set_config_no .

The USB driver interface uses opaque interface handles to refer to configuration interfaces. These handles remain valid until the device configuration is changed using Fn usbd_set_config_index or Fn usbd_set_config_no . The Fn usbd_device2interface_handle function retrieves an interface handle. The Fa ifaceno parameter is an interface index number starting at zero. If the device is configured and the specified interface exists, then USBD_NORMAL_COMPLETION is returned and the interface handle is stored in Fa *iface . Otherwise an error code is returned and Fa *iface is not changed. The Fn usbd_interface2device_handle function retrieves the device handle from an interface handle. This is just for convenience to save passing around the device handle as well as the interface handle. The Fn usbd_set_interface function changes the alternate setting number for an interface to the alternate setting identified by the zero-based index number Fa altidx . This operation invalidates any existing endpoints on this interface and their descriptors. The Fn usbd_get_interface_altindex function returns the current alternative setting index as was specified when calling Fn usbd_set_interface . The Fn usbd_endpoint_count function retrieves the number of endpoints associated with the specified interface. The Fn usbd_interface2endpoint_descriptor function returns a pointer to an in-memory endpoint descriptor for the endpoint that has an index number of Fa index . This pointer remains valid until the configuration or alternate setting number are changed. The function Fn usbd_get_endpoint_descriptor is like Fn usbd_interface2endpoint_descriptor but it accepts a Fa bEndpointAddress address value instead of an index.

The Fn usbd_fill_deviceinfo function fills out a Vt usb_device_info structure with information about the device. The vendor and product names come from the device itself, falling back to a table lookup or just providing the IDs in hexadecimal. If Fa usedev is zero then Fn usbd_fill_deviceinfo will not attempt to retrieve the vendor and product names from the device. The usb_device_info structure is defined in In dev/usb/usb.h as follows:

 struct usb_device_info {
         u_int8_t        udi_bus;
         u_int8_t        udi_addr;       /* device address */
         usb_event_cookie_t udi_cookie;
         char            udi_product[USB_MAX_STRING_LEN];
         char            udi_vendor[USB_MAX_STRING_LEN];
         char            udi_release[8];
         u_int16_t       udi_productNo;
         u_int16_t       udi_vendorNo;
         u_int16_t       udi_releaseNo;
         u_int8_t        udi_class;
         u_int8_t        udi_subclass;
         u_int8_t        udi_protocol;
         u_int8_t        udi_config;
         u_int8_t        udi_speed;
 #define USB_SPEED_LOW  1
 #define USB_SPEED_FULL 2
 #define USB_SPEED_HIGH 3
         int             udi_power;      /* power consumption in mA */
         int             udi_nports;
         char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
         /* hub only: addresses of devices on ports */
         u_int8_t        udi_ports[16];
 #define USB_PORT_ENABLED 0xff
 #define USB_PORT_SUSPENDED 0xfe
 #define USB_PORT_POWERED 0xfd
 }
 

The Fn usbd_devinfo function generates a string description of the USB device. The Fa cp argument should point to a 1024-byte buffer (XXX the maximum length is approximately 320 chars, but there is no sanity checking and everything uses 1024-character buffers). Device class information is included if the Fa showclass parameter is non-zero.

The Fn usbd_get_quirks function returns information from a table of devices that require special workarounds in order to function correctly. The returned structure is defined in In dev/usb/usb_quirks.h as follows:

 struct usbd_quirks {
         u_int32_t uq_flags;     /* Device problems */
 };
 

See In dev/usb/usb_quirks.h for a list of all currently defined quirks.

USB control requests are performed via Vt usb_device_request_t structures, defined in In dev/usb/usb.h as follows:

 typedef struct {
         uByte           bmRequestType;
         uByte           bRequest;
         uWord           wValue;
         uWord           wIndex;
         uWord           wLength;
 } UPACKED usb_device_request_t;
 

The Fn usbd_do_request function performs a single request synchronously. The Fa req parameter should point to a properly initialized Vt usb_device_request_t , and when the Fa wLength field is non-zero, Fa data should point at a buffer that is at least Fa wLength bytes in length. The request timeout is set to 5 seconds, so the operation will fail with Er USBD_TIMEOUT if the device does not respond within that time. The Fn usbd_do_request_async function is like Fn usbd_do_request , but it does not wait for the request to complete before returning. This routine does not block so it can be used from contexts where sleeping is not allowed. Note that there is no notification mechanism to report when the operation completed nor is there a way to determine whether the request succeeded, so this function is of limited use. See Fn usbd_setup_default_xfer and Fn usbd_transfer for a way to invoke an asynchronous callback upon completion of a control request. The Fn usbd_do_request_flags function is like Fn usbd_do_request , but additional flags can be specified, the timeout is configurable, and the actual number of bytes transferred is made available to the caller. The Fn usbd_do_request_flags_pipe function uses a specified pipe instead of the default pipe.

The function Fn usbd_open_pipe creates a pipe connected to a specified endpoint on a specified interface. The parameter Fa address should be the Fa bEndpointAddress value from one of this interface's endpoint descriptors. If Fa flags contains USBD_EXCLUSIVE_USE then the operation will only succeed if there are no open pipes already connected to the specified endpoint. The Fn usbd_open_pipe_intr function creates an interrupt pipe connected to the specified endpoint. The parameter Fa address should be the Fa bEndpointAddress value from one of this interface's endpoint descriptors. The Fa flags parameter is passed to Fn usbd_setup_xfer . The Fa buffer and Fa len parameters define a buffer that is to be used for the interrupt transfers. The callback to be invoked each time a transfer completes is specified by Fa cb , and Fa priv is an argument to be passed to the callback function. The Fa ival parameter specifies the maximum acceptable interval between transfers; in practice the transfers may occur more frequently. The function Fn usbd_pipe2device_handle returns the device associated with the specified Fa pipe .

The Fn usbd_abort_pipe function aborts all active or waiting transfers on the specified pipe. Each transfer is aborted with a USBD_CANCELLED status; callback routines must detect this error code to ensure that they do not attempt to initiate a new transfer in response to one being aborted. This routine blocks while it is waiting for the hardware to complete processing of aborted transfers, so it is only safe to call it in contexts where sleeping is allowed. The function Fn usbd_abort_default_pipe aborts all active or waiting transfers on the default pipe. Like Fn usbd_abort_pipe , it blocks waiting for the hardware processing to complete.

When a pipe has no active or waiting transfers, the pipe may be closed using the Fn usbd_close_pipe function. Once a pipe is closed, its pipe handle becomes invalid and may no longer be used.

USB transfer handles are allocated using the function Fn usbd_alloc_xfer and may be freed using Fn usbd_free_xfer .

The function Fn usbd_setup_xfer initializes a transfer handle with the details of a transfer to or from a USB device. The Fa xfer parameter specifies the transfer handle to initialize, Fa pipe specifies the pipe on which the transfer is to take place, and Fa priv is an argument that will be passed to callback function. The arguments Fa buffer and Fa length define the data buffer for the transfer. If Fa length is zero then the Fa buffer may be NULL The Fa flags parameter may contain the following flags:

USBD_NO_COPY

This is used in association with Fn usbd_alloc_buffer and Fn usbd_free_buffer to use a dedicated DMA-capable buffer for the transfer.

USBD_SYNCHRONOUS

Wait for the transfer to compete in Fn usbd_transfer .

USBD_SHORT_XFER_OK

Permit transfers shorter than the requested data length.

USBD_FORCE_SHORT_XFER

Force a short transfer at the end of a write operation to let the device know that the transfer has ended.

The Fa timeout parameter specifies a timeout for the transfer in milliseconds. A value of USBD_NO_TIMEOUT indicates that no timeout should be configured. The parameter Fa callback specifies the function to call when the transfer completes. Note that Fn usbd_setup_xfer does not actually initiate the transfer. The Fn usbd_setup_default_xfer initializes a control transfer for the default pipe. The Fa req parameter should point at a completed Vt usb_device_request_t structure. The function Fa usbd_setup_isoc_xfer initializes a transfer for an isochronous pipe.

The function Fn usbd_transfer initiates a transfer. Normally it returns USBD_IN_PROGRESS to indicate that the transfer has been queued. If the USB stack is operating in polling mode, or if the transfer is synchronous, then USBD_NORMAL_COMPLETION may be returned. Other return values indicate that the transfer could not be initiated due to an error. The Fn usbd_sync_transfer function executes a transfer synchronously. It will sleep waiting for the transfer to complete and then return the transfer status. Note that if the transfer has a callback routine, this will be invoked before Fn usbd_sync_transfer returns.

The Fn usbd_intr_transfer and Fn usbd_bulk_transfer functions set up a transfer and wait synchronously for it to complete but they allows signals to interrupt the wait. They returns USBD_INTERRUPTED if the transfer was interrupted by a signal. XXX these two functions are identical apart from their names.

The function Fn usbd_get_xfer_status retrieves various information from a completed transfer. If the Fa priv parameter is not NULL then the callback private argument is stored in Fa *priv . If Fa buffer is not NULL then the transfer buffer pointer is stored in Fa *buffer . The actual number of bytes transferred is stored in Fa *count if Fa count is not NULL. Finally, the transfer status is stored in Fa *status if Fa status is not NULL.

The Fn usbd_clear_endpoint_stall function clears an endpoint stall condition synchronously, i.e. it sleeps waiting for the stall clear request to complete. The function Fn usbd_clear_endpoint_stall_async performs the same function asynchronously, but it provides no way to determine when the request completed, or whether it was successful. The Fn usbd_clear_endpoint_toggle function instructs the host controller driver to reset the toggle bit on a pipe. This is used when manually clearing an endpoint stall using a control pipe request, in order to ensure that the host controller driver and the USB device restart with the same toggle value.

Normally the USB subsystem maps and copies data to and from DMA-capable memory each time a transfer is performed. The function Fn usbd_alloc_buffer allocates a permanent DMA-capable buffer associated with the transfer to avoid this overhead. The return value is the virtual address of the buffer. Any time that Fn usbd_setup_xfer is called on the transfer with the USBD_NO_COPY flag enabled, the allocated buffer will be used directly and the Fa buffer argument passed to Fn usbd_setup_xfer will be ignored. The Fn usbd_get_buffer function returns a pointer to the virtual address of a buffer previously allocated by Fn usbd_alloc_buffer . Finally, Fn usbd_free_buffer deallocates the buffer.

The Fn usbd_errstr function converts a status code into a string for display.

The function Fn usbd_set_polling enables or disables polling mode. In polling mode, all operations will busy-wait for the device to respond, so its use is effectively limited to boot time and kernel debuggers. It is important to match up calls that enable and disable polling mode, because the implementation just increments a polling reference count when Fa on is non-zero and decrements it when Fa on is zero. The Fn usbd_dopoll causes the host controller driver to poll for any activity. This should only be used when polling mode is enabled.

The Fn usbd_ratecheck function is used to limit the rate at which error messages are printed to approximately once per second. The Fa last argument should point at a persistent Vt struct timeval . A value of 1 will be returned if a message should be printed, but if Fn usbd_ratecheck has already been called with the same Vt struct timeval parameter in the last second then 0 is returned and the error message should be suppressed.

The functions Fn usb_detach_wait and Fn usb_detach_wakeup are used to wait for references to drain before completing the detachment of a device. The Fn usb_detach_wait function will wait up to 60 seconds to receive a signal from Fn usb_detach_wait .

USB Descriptors

The USB specification defines a number of standard descriptors by which USB devices report their attributes. These descriptors are fixed-format structures that all USB devices make available through USB control pipe requests.

Every USB device has exactly one USB device descriptor. The USB subsystem retrieves this automatically when a device is attached, and a copy of the descriptor is kept in memory. The Fn usbd_get_device_descriptor function returns a pointer to the descriptor. The device descriptor structure is defined in In dev/usb/usb.h as follows:

 typedef struct {
         uByte           bLength;
         uByte           bDescriptorType;
         uWord           bcdUSB;
 #define UD_USB_2_0              0x0200
 #define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
         uByte           bDeviceClass;
         uByte           bDeviceSubClass;
         uByte           bDeviceProtocol;
         uByte           bMaxPacketSize;
         /* The fields below are not part of the initial descriptor. */
         uWord           idVendor;
         uWord           idProduct;
         uWord           bcdDevice;
         uByte           iManufacturer;
         uByte           iProduct;
         uByte           iSerialNumber;
         uByte           bNumConfigurations;
 } UPACKED usb_device_descriptor_t;
 #define USB_DEVICE_DESCRIPTOR_SIZE 18
 

USB devices have at least one configuration descriptor. The Fa bNumConfigurations field of the device descriptor specifies the number of configuration descriptors that a device supports. The Fn usbd_get_config_desc function retrieves a particular configuration descriptor from the device and the Fn usbd_get_config_desc_full function retrieves a full Fa wTotalLength length configuration descriptor, which includes all related interface and endpoint descriptors. Only one configuration may be active at a time. The Fn usbd_set_config_index function activates a specified configuration. The configuration descriptor structure is defined in In dev/usb/usb.h as follows:

 typedef struct {
         uByte           bLength;
         uByte           bDescriptorType;
         uWord           wTotalLength;
         uByte           bNumInterface;
         uByte           bConfigurationValue;
         uByte           iConfiguration;
         uByte           bmAttributes;
 #define UC_BUS_POWERED          0x80
 #define UC_SELF_POWERED         0x40
 #define UC_REMOTE_WAKEUP        0x20
         uByte           bMaxPower; /* max current in 2 mA units */
 #define UC_POWER_FACTOR 2
 } UPACKED usb_config_descriptor_t;
 #define USB_CONFIG_DESCRIPTOR_SIZE 9
 

Each device configuration provides one or more interfaces. The Fa bNumInterface field of the configuration descriptor specifies the number of interfaces associated with a device configuration. Interfaces are described by an interface descriptor, which is defined in In dev/usb/usb.h as follows:

 typedef struct {
         uByte           bLength;
         uByte           bDescriptorType;
         uByte           bInterfaceNumber;
         uByte           bAlternateSetting;
         uByte           bNumEndpoints;
         uByte           bInterfaceClass;
         uByte           bInterfaceSubClass;
         uByte           bInterfaceProtocol;
         uByte           iInterface;
 } UPACKED usb_interface_descriptor_t;
 #define USB_INTERFACE_DESCRIPTOR_SIZE 9
 

Configurations may also have alternate interfaces with the same Fa bInterfaceNumber but different Fa bAlternateSetting values. These alternate interface settings may be selected by passing a non-zero Fa altidx parameter to Fn usbd_set_interface .

Interfaces have zero or more endpoints, and each endpoint has an endpoint descriptor. Note that endpoint zero, which is always present, does not have an endpoint descriptor, and it is never included in the Fa bNumEndpoints count of endpoints. The endpoint descriptor is defined in In dev/usb/usb.h as follows:

 typedef struct {
         uByte           bLength;
         uByte           bDescriptorType;
         uByte           bEndpointAddress;
 #define UE_GET_DIR(a)   ((a) & 0x80)
 #define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
 #define UE_DIR_IN       0x80
 #define UE_DIR_OUT      0x00
 #define UE_ADDR         0x0f
 #define UE_GET_ADDR(a)  ((a) & UE_ADDR)
         uByte           bmAttributes;
 #define UE_XFERTYPE     0x03
 #define  UE_CONTROL     0x00
 #define  UE_ISOCHRONOUS 0x01
 #define  UE_BULK        0x02
 #define  UE_INTERRUPT   0x03
 #define UE_GET_XFERTYPE(a)      ((a) & UE_XFERTYPE)
 #define UE_ISO_TYPE     0x0c
 #define  UE_ISO_ASYNC   0x04
 #define  UE_ISO_ADAPT   0x08
 #define  UE_ISO_SYNC    0x0c
 #define UE_GET_ISO_TYPE(a)      ((a) & UE_ISO_TYPE)
         uWord           wMaxPacketSize;
         uByte           bInterval;
 } UPACKED usb_endpoint_descriptor_t;
 #define USB_ENDPOINT_DESCRIPTOR_SIZE 7
 

RETURN VALUES

Many functions return a Vt usbd_status type to indicate the outcome of the operation. If the operation completed successfully then USBD_NORMAL_COMPLETION is returned. Operations that have been started but not yet completed will return USBD_IN_PROGRESS Other errors usually indicate a problem. Error codes can be converted to strings using Fn usbd_errstr .

ERRORS

Bq Er USBD_PENDING_REQUESTS

A pipe could not be closed because there are active requests.

Bq Er USBD_NOT_STARTED

The transfer has not yet been started.

Bq Er USBD_INVAL

An invalid value was supplied.

Bq Er USBD_NOMEM

An attempt to allocate memory failed.

Bq Er USBD_CANCELLED

The transfer was aborted.

Bq Er USBD_BAD_ADDRESS

The specified endpoint address was not found.

Bq Er USBD_IN_USE

The endpoint is already in use, or the configuration cannot be changed because some of its endpoints are in use.

Bq Er USBD_NO_ADDR

No free USB devices addresses were found to assign to the device.

Bq Er USBD_SET_ADDR_FAILED

The device address could not be set.

Bq Er USBD_NO_POWER

Insufficient power was available for the device.

Bq Er USBD_TOO_DEEP

Too many levels of chained hubs were found.

Bq Er USBD_IOERROR

There was an error communicating with the device.

Bq Er USBD_NOT_CONFIGURED

An operation that requires an active configuration was attempted while the device was in an unconfigured state.

Bq Er USBD_TIMEOUT

A transfer timed out.

Bq Er USBD_SHORT_XFER

A transfer that disallowed short data lengths completed with less than the requested length transferred.

Bq Er USBD_STALLED

A transfer failed because the pipe is stalled.

Bq Er USBD_INTERRUPTED

An interruptible operation caught a signal.

SEE ALSO

usb(4)

HISTORY

The USB driver interface first appeared in Fx 3.0 .

AUTHORS

The USB driver was written by An Lennart Augustsson for the Nx project.

An -nosplit This manual page was written by An Ian Dowse Aq iedowse@FreeBSD.org .