The Linux-USB Host Side API

Table of Contents

1. Introduction to USB on Linux

2. USB Host-Side API Model

3. USB-Standard Types

usb_speed_string — Returns human readable-name of the speed.

usb_state_string — Returns human readable name for the state.

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_hub_for_each_child — iterate over all child devices on the hub

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_CLASS — describe a usb device with a specific interface class

USB_DEVICE_INTERFACE_PROTOCOL — describe a usb device with a specific interface protocol

USB_DEVICE_INTERFACE_NUMBER — describe a usb device with a specific interface number

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

USB_VENDOR_AND_INTERFACE_INFO — describe a specific usb vendor 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

module_usb_driver — Helper macro for registering a USB driver

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_block_urb — reliably 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_anchor_suspend_wakeups —

usb_anchor_resume_wakeups —

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_for_each_dev — iterate over all USB devices in the system

usb_alloc_dev — usb device constructor (usbcore-internal)

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

usb_hub_find_child — Get the pointer of child device attached to the port which is specified by port1.

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