The Linux-USB Host Side API

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.


Table of Contents

1. Introduction to USB on Linux
2. USB Host-Side API Model
3. USB-Standard Types
struct usb_ctrlrequest - SETUP data for a USB device control request
usb_endpoint_num - get the endpoint's number
usb_endpoint_type - get the endpoint's transfer type
usb_endpoint_dir_in - check if the endpoint has IN direction
usb_endpoint_dir_out - check if the endpoint has OUT direction
usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
usb_endpoint_xfer_control - check if the endpoint has control transfer type
usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
usb_endpoint_is_int_in - check if the endpoint is interrupt IN
usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
4. Host-Side Data Types and Macros
struct usb_host_endpoint - host-side endpoint descriptor and queue
struct usb_interface - what usb device drivers talk to
struct usb_interface_cache - long-term representation of a device interface
struct usb_host_config - representation of a device's configuration
struct usb_device - kernel's representation of a USB device
usb_interface_claimed - returns true iff an interface is claimed
usb_make_path - returns stable device path in the usb tree
USB_DEVICE - macro used to describe a specific usb device
USB_DEVICE_VER - describe a specific usb device with a version range
USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
USB_DEVICE_INFO - macro used to describe a class of usb devices
USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
struct usbdrv_wrap - wrapper for driver-model structure
struct usb_driver - identifies USB interface driver to usbcore
struct usb_device_driver - identifies USB device driver to usbcore
struct usb_class_driver - identifies a USB driver that wants to use the USB major number
struct urb - USB Request Block
usb_fill_control_urb - initializes a control urb
usb_fill_bulk_urb - macro to help initialize a bulk urb
usb_fill_int_urb - macro to help initialize a interrupt urb
usb_urb_dir_in - check if an URB describes an IN transfer
usb_urb_dir_out - check if an URB describes an OUT transfer
struct usb_sg_request - support for scatter/gather I/O
5. USB Core APIs
usb_init_urb - initializes a urb so that it can be used by a USB driver
usb_alloc_urb - creates a new urb for a USB driver to use
usb_free_urb - frees the memory used by a urb when all users of it are finished
usb_get_urb - increments the reference count of the urb
usb_anchor_urb - anchors an URB while it is processed
usb_unanchor_urb - unanchors an URB
usb_submit_urb - issue an asynchronous transfer request for an endpoint
usb_unlink_urb - abort/cancel a transfer request for an endpoint
usb_kill_urb - cancel a transfer request and wait for it to finish
usb_poison_urb - reliably kill a transfer and prevent further use of an URB
usb_kill_anchored_urbs - cancel transfer requests en masse
usb_poison_anchored_urbs - cease all traffic from an anchor
usb_unpoison_anchored_urbs - let an anchor be used successfully again
usb_unlink_anchored_urbs - asynchronously cancel transfer requests en masse
usb_wait_anchor_empty_timeout - wait for an anchor to be unused
usb_get_from_anchor - get an anchor's oldest urb
usb_scuttle_anchored_urbs - unanchor all an anchor's urbs
usb_anchor_empty - is an anchor empty
usb_control_msg - Builds a control urb, sends it off and waits for completion
usb_interrupt_msg - Builds an interrupt urb, sends it off and waits for completion
usb_bulk_msg - Builds a bulk urb, sends it off and waits for completion
usb_sg_init - initializes scatterlist-based bulk/interrupt I/O request
usb_sg_wait - synchronously execute scatter/gather request
usb_sg_cancel - stop scatter/gather i/o issued by usb_sg_wait
usb_get_descriptor - issues a generic GET_DESCRIPTOR request
usb_string - returns UTF-8 version of a string descriptor
usb_get_status - issues a GET_STATUS call
usb_clear_halt - tells device to clear endpoint halt/stall condition
usb_reset_endpoint - Reset an endpoint's state.
usb_set_interface - Makes a particular alternate setting be current
usb_reset_configuration - lightweight device reset
usb_driver_set_configuration - Provide a way for drivers to change device configurations
usb_register_dev - register a USB device, and ask for a minor number
usb_deregister_dev - deregister a USB device's dynamic minor.
usb_driver_claim_interface - bind a driver to an interface
usb_driver_release_interface - unbind a driver from an interface
usb_match_id - find first usb_device_id matching device or interface
usb_register_device_driver - register a USB device (not interface) driver
usb_deregister_device_driver - unregister a USB device (not interface) driver
usb_register_driver - register a USB interface driver
usb_deregister - unregister a USB interface driver
usb_enable_autosuspend - allow a USB device to be autosuspended
usb_disable_autosuspend - prevent a USB device from being autosuspended
usb_autopm_put_interface - decrement a USB interface's PM-usage counter
usb_autopm_put_interface_async - decrement a USB interface's PM-usage counter
usb_autopm_put_interface_no_suspend - decrement a USB interface's PM-usage counter
usb_autopm_get_interface - increment a USB interface's PM-usage counter
usb_autopm_get_interface_async - increment a USB interface's PM-usage counter
usb_autopm_get_interface_no_resume - increment a USB interface's PM-usage counter
usb_find_alt_setting - Given a configuration, find the alternate setting for the given interface.
usb_ifnum_to_if - get the interface object with a given interface number
usb_altnum_to_altsetting - get the altsetting structure with a given alternate setting number.
usb_find_interface - find usb_interface pointer for driver and device
usb_get_dev - increments the reference count of the usb device structure
usb_put_dev - release a use of the usb device structure
usb_get_intf - increments the reference count of the usb interface structure
usb_put_intf - release a use of the usb interface structure
usb_lock_device_for_reset - cautiously acquire the lock for a usb device structure
usb_get_current_frame_number - return current bus frame number
usb_alloc_coherent - allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
usb_free_coherent - free memory allocated with usb_alloc_coherent
usb_buffer_map - create DMA mapping(s) for an urb
usb_buffer_dmasync - synchronize DMA and CPU view of buffer(s)
usb_buffer_unmap - free DMA mapping(s) for an urb
usb_buffer_map_sg - create scatterlist DMA mapping(s) for an endpoint
usb_buffer_dmasync_sg - synchronize DMA and CPU view of scatterlist buffer(s)
usb_buffer_unmap_sg - free DMA mapping(s) for a scatterlist
usb_hub_clear_tt_buffer - clear control/bulk TT state in high speed hub
usb_set_device_state - change a device's current state (usbcore, hcds)
usb_root_hub_lost_power - called by HCD if the root hub lost Vbus power
usb_reset_device - warn interface drivers and perform a USB port reset
usb_queue_reset_device - Reset a USB device from an atomic context
6. Host Controller APIs
usb_calc_bus_time - approximate periodic transaction time in nanoseconds
usb_hcd_link_urb_to_ep - add an URB to its endpoint queue
usb_hcd_check_unlink_urb - check whether an URB may be unlinked
usb_hcd_unlink_urb_from_ep - remove an URB from its endpoint queue
usb_hcd_giveback_urb - return URB from HCD to device driver
usb_alloc_streams - allocate bulk endpoint stream IDs.
usb_free_streams - free bulk endpoint stream IDs.
usb_hcd_resume_root_hub - called by HCD to resume its root hub
usb_bus_start_enum - start immediate enumeration (for OTG)
usb_hcd_irq - hook IRQs to HCD framework (bus glue)
usb_hc_died - report abnormal shutdown of a host controller (bus glue)
usb_create_shared_hcd - create and initialize an HCD structure
usb_create_hcd - create and initialize an HCD structure
usb_add_hcd - finish generic HCD structure initialization and register
usb_remove_hcd - shutdown processing for generic HCDs
usb_hcd_pci_probe - initialize PCI-based HCDs
usb_hcd_pci_remove - shutdown processing for PCI-based HCDs
usb_hcd_pci_shutdown - shutdown host controller
hcd_buffer_create - initialize buffer pools
hcd_buffer_destroy - deallocate buffer pools
7. The USB Filesystem (usbfs)
What files are in "usbfs"?
Mounting and Access Control
/proc/bus/usb/devices
/proc/bus/usb/BBB/DDD
Life Cycle of User Mode Drivers
The ioctl() Requests
Management/Status Requests
Synchronous I/O Support
Asynchronous I/O Support