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

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