Chapter 5. USB Core APIs

Table of Contents

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.

There are two basic I/O models in the USB API. The most elemental one is asynchronous: drivers submit requests in the form of an URB, and the URB's completion callback handle the next step. All USB transfer types support that model, although there are special cases for control URBs (which always have setup and status stages, but may not have a data stage) and isochronous URBs (which allow large packets and include per-packet fault reports). Built on top of that is synchronous API support, where a driver calls a routine that allocates one or more URBs, submits them, and waits until they complete. There are synchronous wrappers for single-buffer control and bulk transfers (which are awkward to use in some driver disconnect scenarios), and for scatterlist based streaming i/o (bulk or interrupt).

USB drivers need to provide buffers that can be used for DMA, although they don't necessarily need to provide the DMA mapping themselves. There are APIs to use used when allocating DMA buffers, which can prevent use of bounce buffers on some systems. In some cases, drivers may be able to rely on 64bit DMA to eliminate another kind of bounce buffer.