The Linux-USB Host Side API
|  | Next

# 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
  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 — macro used to describe a specific usb device with a
  USB_DEVICE_INTERFACE_PROTOCOL — macro used to describe a usb
  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 — macro used to describe a specific usb device
  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_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
  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_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

|  | Next
|  | Chapter 1. Introduction to USB on Linux