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
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_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
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_kill_anchored_urbs — cancel transfer requests en masse
usb_unlink_anchored_urbs — asynchronously cancel transfer requests en masse
usb_wait_anchor_empty_timeout — wait for an anchor to be unused
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 ISO 8859-1 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_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_autopm_put_interface — decrement a USB interface's PM-usage counter
usb_autopm_get_interface — increment a USB interface's PM-usage counter
usb_autopm_set_interface — set a USB interface's autosuspend state
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_buffer_alloc — allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
usb_buffer_free — free memory allocated with usb_buffer_alloc
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_tt_clear_buffer — clear control/bulk TT state in high speed hub
usb_root_hub_lost_power — called by HCD if the root hub lost Vbus power
usb_reset_device — perform a USB port reset to reinitialize a device
usb_reset_composite_device — warn interface drivers and perform a USB port reset
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_hcd_resume_root_hub — called by HCD to resume its root hub
usb_bus_start_enum — start immediate enumeration (for OTG)
usb_hc_died — report abnormal shutdown of a host controller (bus glue)
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_suspend — power management suspend of a PCI-based HCD
usb_hcd_pci_resume — power management resume of a PCI-based HCD
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