<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>Chapter 5. USB Core APIs</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The Linux-USB Host Side API" /><link rel="up" href="index.html" title="The Linux-USB Host Side API" /><link rel="prev" href="re40.html" title="struct usb_sg_request" /><link rel="next" href="re41.html" title="usb_init_urb" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. USB Core APIs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re40.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="re41.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 5. USB Core APIs"><div class="titlepage"><div><div><h2 class="title"><a id="usbcore"></a>Chapter 5. USB Core APIs</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="refentrytitle"><a href="re41.html"><span>usb_init_urb</span></a></span><span class="refpurpose"> —
initializes a urb so that it can be used by a USB driver
</span></dt><dt><span class="refentrytitle"><a href="re42.html"><span>usb_alloc_urb</span></a></span><span class="refpurpose"> —
creates a new urb for a USB driver to use
</span></dt><dt><span class="refentrytitle"><a href="re43.html"><span>usb_free_urb</span></a></span><span class="refpurpose"> —
frees the memory used by a urb when all users of it are finished
</span></dt><dt><span class="refentrytitle"><a href="re44.html"><span>usb_get_urb</span></a></span><span class="refpurpose"> —
increments the reference count of the urb
</span></dt><dt><span class="refentrytitle"><a href="re45.html"><span>usb_anchor_urb</span></a></span><span class="refpurpose"> —
anchors an URB while it is processed
</span></dt><dt><span class="refentrytitle"><a href="re46.html"><span>usb_unanchor_urb</span></a></span><span class="refpurpose"> —
unanchors an URB
</span></dt><dt><span class="refentrytitle"><a href="re47.html"><span>usb_submit_urb</span></a></span><span class="refpurpose"> —
issue an asynchronous transfer request for an endpoint
</span></dt><dt><span class="refentrytitle"><a href="re48.html"><span>usb_unlink_urb</span></a></span><span class="refpurpose"> —
abort/cancel a transfer request for an endpoint
</span></dt><dt><span class="refentrytitle"><a href="re49.html"><span>usb_kill_urb</span></a></span><span class="refpurpose"> —
cancel a transfer request and wait for it to finish
</span></dt><dt><span class="refentrytitle"><a href="re50.html"><span>usb_poison_urb</span></a></span><span class="refpurpose"> —
reliably kill a transfer and prevent further use of an URB
</span></dt><dt><span class="refentrytitle"><a href="re51.html"><span>usb_kill_anchored_urbs</span></a></span><span class="refpurpose"> —
cancel transfer requests en masse
</span></dt><dt><span class="refentrytitle"><a href="re52.html"><span>usb_poison_anchored_urbs</span></a></span><span class="refpurpose"> —
cease all traffic from an anchor
</span></dt><dt><span class="refentrytitle"><a href="re53.html"><span>usb_unpoison_anchored_urbs</span></a></span><span class="refpurpose"> —
let an anchor be used successfully again
</span></dt><dt><span class="refentrytitle"><a href="re54.html"><span>usb_unlink_anchored_urbs</span></a></span><span class="refpurpose"> —
asynchronously cancel transfer requests en masse
</span></dt><dt><span class="refentrytitle"><a href="re55.html"><span>usb_wait_anchor_empty_timeout</span></a></span><span class="refpurpose"> —
wait for an anchor to be unused
</span></dt><dt><span class="refentrytitle"><a href="re56.html"><span>usb_get_from_anchor</span></a></span><span class="refpurpose"> —
get an anchor's oldest urb
</span></dt><dt><span class="refentrytitle"><a href="re57.html"><span>usb_scuttle_anchored_urbs</span></a></span><span class="refpurpose"> —
unanchor all an anchor's urbs
</span></dt><dt><span class="refentrytitle"><a href="re58.html"><span>usb_anchor_empty</span></a></span><span class="refpurpose"> —
is an anchor empty
</span></dt><dt><span class="refentrytitle"><a href="re59.html"><span>usb_control_msg</span></a></span><span class="refpurpose"> —
Builds a control urb, sends it off and waits for completion
</span></dt><dt><span class="refentrytitle"><a href="re60.html"><span>usb_interrupt_msg</span></a></span><span class="refpurpose"> —
Builds an interrupt urb, sends it off and waits for completion
</span></dt><dt><span class="refentrytitle"><a href="re61.html"><span>usb_bulk_msg</span></a></span><span class="refpurpose"> —
Builds a bulk urb, sends it off and waits for completion
</span></dt><dt><span class="refentrytitle"><a href="re62.html"><span>usb_sg_init</span></a></span><span class="refpurpose"> —
initializes scatterlist-based bulk/interrupt I/O request
</span></dt><dt><span class="refentrytitle"><a href="re63.html"><span>usb_sg_wait</span></a></span><span class="refpurpose"> —
synchronously execute scatter/gather request
</span></dt><dt><span class="refentrytitle"><a href="re64.html"><span>usb_sg_cancel</span></a></span><span class="refpurpose"> —
stop scatter/gather i/o issued by <code class="function">usb_sg_wait</code>
</span></dt><dt><span class="refentrytitle"><a href="re65.html"><span>usb_get_descriptor</span></a></span><span class="refpurpose"> —
issues a generic GET_DESCRIPTOR request
</span></dt><dt><span class="refentrytitle"><a href="re66.html"><span>usb_string</span></a></span><span class="refpurpose"> —
returns UTF-8 version of a string descriptor
</span></dt><dt><span class="refentrytitle"><a href="re67.html"><span>usb_get_status</span></a></span><span class="refpurpose"> —
issues a GET_STATUS call
</span></dt><dt><span class="refentrytitle"><a href="re68.html"><span>usb_clear_halt</span></a></span><span class="refpurpose"> —
tells device to clear endpoint halt/stall condition
</span></dt><dt><span class="refentrytitle"><a href="re69.html"><span>usb_reset_endpoint</span></a></span><span class="refpurpose"> —
Reset an endpoint's state.
</span></dt><dt><span class="refentrytitle"><a href="re70.html"><span>usb_set_interface</span></a></span><span class="refpurpose"> —
Makes a particular alternate setting be current
</span></dt><dt><span class="refentrytitle"><a href="re71.html"><span>usb_reset_configuration</span></a></span><span class="refpurpose"> —
lightweight device reset
</span></dt><dt><span class="refentrytitle"><a href="re72.html"><span>usb_driver_set_configuration</span></a></span><span class="refpurpose"> —
Provide a way for drivers to change device configurations
</span></dt><dt><span class="refentrytitle"><a href="re73.html"><span>usb_register_dev</span></a></span><span class="refpurpose"> —
register a USB device, and ask for a minor number
</span></dt><dt><span class="refentrytitle"><a href="re74.html"><span>usb_deregister_dev</span></a></span><span class="refpurpose"> —
deregister a USB device's dynamic minor.
</span></dt><dt><span class="refentrytitle"><a href="re75.html"><span>usb_driver_claim_interface</span></a></span><span class="refpurpose"> —
bind a driver to an interface
</span></dt><dt><span class="refentrytitle"><a href="re76.html"><span>usb_driver_release_interface</span></a></span><span class="refpurpose"> —
unbind a driver from an interface
</span></dt><dt><span class="refentrytitle"><a href="re77.html"><span>usb_match_id</span></a></span><span class="refpurpose"> —
find first usb_device_id matching device or interface
</span></dt><dt><span class="refentrytitle"><a href="re78.html"><span>usb_register_device_driver</span></a></span><span class="refpurpose"> —
register a USB device (not interface) driver
</span></dt><dt><span class="refentrytitle"><a href="re79.html"><span>usb_deregister_device_driver</span></a></span><span class="refpurpose"> —
unregister a USB device (not interface) driver
</span></dt><dt><span class="refentrytitle"><a href="re80.html"><span>usb_register_driver</span></a></span><span class="refpurpose"> —
register a USB interface driver
</span></dt><dt><span class="refentrytitle"><a href="re81.html"><span>usb_deregister</span></a></span><span class="refpurpose"> —
unregister a USB interface driver
</span></dt><dt><span class="refentrytitle"><a href="re82.html"><span>usb_autopm_put_interface</span></a></span><span class="refpurpose"> —
decrement a USB interface's PM-usage counter
</span></dt><dt><span class="refentrytitle"><a href="re83.html"><span>usb_autopm_put_interface_async</span></a></span><span class="refpurpose"> —
decrement a USB interface's PM-usage counter
</span></dt><dt><span class="refentrytitle"><a href="re84.html"><span>usb_device_autosuspend_enable</span></a></span><span class="refpurpose"> —
enable autosuspend on a device
</span></dt><dt><span class="refentrytitle"><a href="re85.html"><span>usb_autopm_get_interface</span></a></span><span class="refpurpose"> —
increment a USB interface's PM-usage counter
</span></dt><dt><span class="refentrytitle"><a href="re86.html"><span>usb_autopm_get_interface_async</span></a></span><span class="refpurpose"> —
increment a USB interface's PM-usage counter
</span></dt><dt><span class="refentrytitle"><a href="re87.html"><span>usb_autopm_set_interface</span></a></span><span class="refpurpose"> —
set a USB interface's autosuspend state
</span></dt><dt><span class="refentrytitle"><a href="re88.html"><span>usb_ifnum_to_if</span></a></span><span class="refpurpose"> —
get the interface object with a given interface number
</span></dt><dt><span class="refentrytitle"><a href="re89.html"><span>usb_altnum_to_altsetting</span></a></span><span class="refpurpose"> —
get the altsetting structure with a given alternate setting number.
</span></dt><dt><span class="refentrytitle"><a href="re90.html"><span>usb_find_interface</span></a></span><span class="refpurpose"> —
find usb_interface pointer for driver and device
</span></dt><dt><span class="refentrytitle"><a href="re91.html"><span>usb_get_dev</span></a></span><span class="refpurpose"> —
increments the reference count of the usb device structure
</span></dt><dt><span class="refentrytitle"><a href="re92.html"><span>usb_put_dev</span></a></span><span class="refpurpose"> —
release a use of the usb device structure
</span></dt><dt><span class="refentrytitle"><a href="re93.html"><span>usb_get_intf</span></a></span><span class="refpurpose"> —
increments the reference count of the usb interface structure
</span></dt><dt><span class="refentrytitle"><a href="re94.html"><span>usb_put_intf</span></a></span><span class="refpurpose"> —
release a use of the usb interface structure
</span></dt><dt><span class="refentrytitle"><a href="re95.html"><span>usb_lock_device_for_reset</span></a></span><span class="refpurpose"> —
cautiously acquire the lock for a usb device structure
</span></dt><dt><span class="refentrytitle"><a href="re96.html"><span>usb_get_current_frame_number</span></a></span><span class="refpurpose"> —
return current bus frame number
</span></dt><dt><span class="refentrytitle"><a href="re97.html"><span>usb_buffer_alloc</span></a></span><span class="refpurpose"> —
allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
</span></dt><dt><span class="refentrytitle"><a href="re98.html"><span>usb_buffer_free</span></a></span><span class="refpurpose"> —
free memory allocated with <code class="function">usb_buffer_alloc</code>
</span></dt><dt><span class="refentrytitle"><a href="re99.html"><span>usb_buffer_map</span></a></span><span class="refpurpose"> —
create DMA mapping(s) for an urb
</span></dt><dt><span class="refentrytitle"><a href="re100.html"><span>usb_buffer_dmasync</span></a></span><span class="refpurpose"> —
synchronize DMA and CPU view of buffer(s)
</span></dt><dt><span class="refentrytitle"><a href="re101.html"><span>usb_buffer_unmap</span></a></span><span class="refpurpose"> —
free DMA mapping(s) for an urb
</span></dt><dt><span class="refentrytitle"><a href="re102.html"><span>usb_buffer_map_sg</span></a></span><span class="refpurpose"> —
create scatterlist DMA mapping(s) for an endpoint
</span></dt><dt><span class="refentrytitle"><a href="re103.html"><span>usb_buffer_dmasync_sg</span></a></span><span class="refpurpose"> —
synchronize DMA and CPU view of scatterlist buffer(s)
</span></dt><dt><span class="refentrytitle"><a href="re104.html"><span>usb_buffer_unmap_sg</span></a></span><span class="refpurpose"> —
free DMA mapping(s) for a scatterlist
</span></dt><dt><span class="refentrytitle"><a href="re105.html"><span>usb_hub_clear_tt_buffer</span></a></span><span class="refpurpose"> —
clear control/bulk TT state in high speed hub
</span></dt><dt><span class="refentrytitle"><a href="re106.html"><span>usb_set_device_state</span></a></span><span class="refpurpose"> —
change a device's current state (usbcore, hcds)
</span></dt><dt><span class="refentrytitle"><a href="re107.html"><span>usb_root_hub_lost_power</span></a></span><span class="refpurpose"> —
called by HCD if the root hub lost Vbus power
</span></dt><dt><span class="refentrytitle"><a href="re108.html"><span>usb_reset_device</span></a></span><span class="refpurpose"> —
warn interface drivers and perform a USB port reset
</span></dt><dt><span class="refentrytitle"><a href="re109.html"><span>usb_queue_reset_device</span></a></span><span class="refpurpose"> —
Reset a USB device from an atomic context
</span></dt></dl></div><p>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).
</p><p>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.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re40.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="re41.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span>struct usb_sg_request</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span>usb_init_urb</span></td></tr></table></div></body></html>
