1<html><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.78.1"><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="API-struct-usb-sg-request.html" title="struct usb_sg_request"><link rel="next" href="API-usb-init-urb.html" title="usb_init_urb"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><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="API-struct-usb-sg-request.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="API-usb-init-urb.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="usbcore"></a>Chapter 5. USB Core APIs</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="refentrytitle"><a href="API-usb-init-urb.html"><span class="phrase">usb_init_urb</span></a></span><span class="refpurpose"> — 2 initializes a urb so that it can be used by a USB driver 3 </span></dt><dt><span class="refentrytitle"><a href="API-usb-alloc-urb.html"><span class="phrase">usb_alloc_urb</span></a></span><span class="refpurpose"> — 4 creates a new urb for a USB driver to use 5 </span></dt><dt><span class="refentrytitle"><a href="API-usb-free-urb.html"><span class="phrase">usb_free_urb</span></a></span><span class="refpurpose"> — 6 frees the memory used by a urb when all users of it are finished 7 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-urb.html"><span class="phrase">usb_get_urb</span></a></span><span class="refpurpose"> — 8 increments the reference count of the urb 9 </span></dt><dt><span class="refentrytitle"><a href="API-usb-anchor-urb.html"><span class="phrase">usb_anchor_urb</span></a></span><span class="refpurpose"> — 10 anchors an URB while it is processed 11 </span></dt><dt><span class="refentrytitle"><a href="API-usb-unanchor-urb.html"><span class="phrase">usb_unanchor_urb</span></a></span><span class="refpurpose"> — 12 unanchors an URB 13 </span></dt><dt><span class="refentrytitle"><a href="API-usb-submit-urb.html"><span class="phrase">usb_submit_urb</span></a></span><span class="refpurpose"> — 14 issue an asynchronous transfer request for an endpoint 15 </span></dt><dt><span class="refentrytitle"><a href="API-usb-unlink-urb.html"><span class="phrase">usb_unlink_urb</span></a></span><span class="refpurpose"> — 16 abort/cancel a transfer request for an endpoint 17 </span></dt><dt><span class="refentrytitle"><a href="API-usb-kill-urb.html"><span class="phrase">usb_kill_urb</span></a></span><span class="refpurpose"> — 18 cancel a transfer request and wait for it to finish 19 </span></dt><dt><span class="refentrytitle"><a href="API-usb-poison-urb.html"><span class="phrase">usb_poison_urb</span></a></span><span class="refpurpose"> — 20 reliably kill a transfer and prevent further use of an URB 21 </span></dt><dt><span class="refentrytitle"><a href="API-usb-block-urb.html"><span class="phrase">usb_block_urb</span></a></span><span class="refpurpose"> — 22 reliably prevent further use of an URB 23 </span></dt><dt><span class="refentrytitle"><a href="API-usb-kill-anchored-urbs.html"><span class="phrase">usb_kill_anchored_urbs</span></a></span><span class="refpurpose"> — 24 cancel transfer requests en masse 25 </span></dt><dt><span class="refentrytitle"><a href="API-usb-poison-anchored-urbs.html"><span class="phrase">usb_poison_anchored_urbs</span></a></span><span class="refpurpose"> — 26 cease all traffic from an anchor 27 </span></dt><dt><span class="refentrytitle"><a href="API-usb-unpoison-anchored-urbs.html"><span class="phrase">usb_unpoison_anchored_urbs</span></a></span><span class="refpurpose"> — 28 let an anchor be used successfully again 29 </span></dt><dt><span class="refentrytitle"><a href="API-usb-unlink-anchored-urbs.html"><span class="phrase">usb_unlink_anchored_urbs</span></a></span><span class="refpurpose"> — 30 asynchronously cancel transfer requests en masse 31 </span></dt><dt><span class="refentrytitle"><a href="API-usb-anchor-suspend-wakeups.html"><span class="phrase">usb_anchor_suspend_wakeups</span></a></span><span class="refpurpose"> — 32 </span></dt><dt><span class="refentrytitle"><a href="API-usb-anchor-resume-wakeups.html"><span class="phrase">usb_anchor_resume_wakeups</span></a></span><span class="refpurpose"> — 33 </span></dt><dt><span class="refentrytitle"><a href="API-usb-wait-anchor-empty-timeout.html"><span class="phrase">usb_wait_anchor_empty_timeout</span></a></span><span class="refpurpose"> — 34 wait for an anchor to be unused 35 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-from-anchor.html"><span class="phrase">usb_get_from_anchor</span></a></span><span class="refpurpose"> — 36 get an anchor's oldest urb 37 </span></dt><dt><span class="refentrytitle"><a href="API-usb-scuttle-anchored-urbs.html"><span class="phrase">usb_scuttle_anchored_urbs</span></a></span><span class="refpurpose"> — 38 unanchor all an anchor's urbs 39 </span></dt><dt><span class="refentrytitle"><a href="API-usb-anchor-empty.html"><span class="phrase">usb_anchor_empty</span></a></span><span class="refpurpose"> — 40 is an anchor empty 41 </span></dt><dt><span class="refentrytitle"><a href="API-usb-control-msg.html"><span class="phrase">usb_control_msg</span></a></span><span class="refpurpose"> — 42 Builds a control urb, sends it off and waits for completion 43 </span></dt><dt><span class="refentrytitle"><a href="API-usb-interrupt-msg.html"><span class="phrase">usb_interrupt_msg</span></a></span><span class="refpurpose"> — 44 Builds an interrupt urb, sends it off and waits for completion 45 </span></dt><dt><span class="refentrytitle"><a href="API-usb-bulk-msg.html"><span class="phrase">usb_bulk_msg</span></a></span><span class="refpurpose"> — 46 Builds a bulk urb, sends it off and waits for completion 47 </span></dt><dt><span class="refentrytitle"><a href="API-usb-sg-init.html"><span class="phrase">usb_sg_init</span></a></span><span class="refpurpose"> — 48 initializes scatterlist-based bulk/interrupt I/O request 49 </span></dt><dt><span class="refentrytitle"><a href="API-usb-sg-wait.html"><span class="phrase">usb_sg_wait</span></a></span><span class="refpurpose"> — 50 synchronously execute scatter/gather request 51 </span></dt><dt><span class="refentrytitle"><a href="API-usb-sg-cancel.html"><span class="phrase">usb_sg_cancel</span></a></span><span class="refpurpose"> — 52 stop scatter/gather i/o issued by <code class="function">usb_sg_wait</code> 53 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-descriptor.html"><span class="phrase">usb_get_descriptor</span></a></span><span class="refpurpose"> — 54 issues a generic GET_DESCRIPTOR request 55 </span></dt><dt><span class="refentrytitle"><a href="API-usb-string.html"><span class="phrase">usb_string</span></a></span><span class="refpurpose"> — 56 returns UTF-8 version of a string descriptor 57 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-status.html"><span class="phrase">usb_get_status</span></a></span><span class="refpurpose"> — 58 issues a GET_STATUS call 59 </span></dt><dt><span class="refentrytitle"><a href="API-usb-clear-halt.html"><span class="phrase">usb_clear_halt</span></a></span><span class="refpurpose"> — 60 tells device to clear endpoint halt/stall condition 61 </span></dt><dt><span class="refentrytitle"><a href="API-usb-reset-endpoint.html"><span class="phrase">usb_reset_endpoint</span></a></span><span class="refpurpose"> — 62 Reset an endpoint's state. 63 </span></dt><dt><span class="refentrytitle"><a href="API-usb-set-interface.html"><span class="phrase">usb_set_interface</span></a></span><span class="refpurpose"> — 64 Makes a particular alternate setting be current 65 </span></dt><dt><span class="refentrytitle"><a href="API-usb-reset-configuration.html"><span class="phrase">usb_reset_configuration</span></a></span><span class="refpurpose"> — 66 lightweight device reset 67 </span></dt><dt><span class="refentrytitle"><a href="API-usb-driver-set-configuration.html"><span class="phrase">usb_driver_set_configuration</span></a></span><span class="refpurpose"> — 68 Provide a way for drivers to change device configurations 69 </span></dt><dt><span class="refentrytitle"><a href="API-usb-register-dev.html"><span class="phrase">usb_register_dev</span></a></span><span class="refpurpose"> — 70 register a USB device, and ask for a minor number 71 </span></dt><dt><span class="refentrytitle"><a href="API-usb-deregister-dev.html"><span class="phrase">usb_deregister_dev</span></a></span><span class="refpurpose"> — 72 deregister a USB device's dynamic minor. 73 </span></dt><dt><span class="refentrytitle"><a href="API-usb-driver-claim-interface.html"><span class="phrase">usb_driver_claim_interface</span></a></span><span class="refpurpose"> — 74 bind a driver to an interface 75 </span></dt><dt><span class="refentrytitle"><a href="API-usb-driver-release-interface.html"><span class="phrase">usb_driver_release_interface</span></a></span><span class="refpurpose"> — 76 unbind a driver from an interface 77 </span></dt><dt><span class="refentrytitle"><a href="API-usb-match-id.html"><span class="phrase">usb_match_id</span></a></span><span class="refpurpose"> — 78 find first usb_device_id matching device or interface 79 </span></dt><dt><span class="refentrytitle"><a href="API-usb-register-device-driver.html"><span class="phrase">usb_register_device_driver</span></a></span><span class="refpurpose"> — 80 register a USB device (not interface) driver 81 </span></dt><dt><span class="refentrytitle"><a href="API-usb-deregister-device-driver.html"><span class="phrase">usb_deregister_device_driver</span></a></span><span class="refpurpose"> — 82 unregister a USB device (not interface) driver 83 </span></dt><dt><span class="refentrytitle"><a href="API-usb-register-driver.html"><span class="phrase">usb_register_driver</span></a></span><span class="refpurpose"> — 84 register a USB interface driver 85 </span></dt><dt><span class="refentrytitle"><a href="API-usb-deregister.html"><span class="phrase">usb_deregister</span></a></span><span class="refpurpose"> — 86 unregister a USB interface driver 87 </span></dt><dt><span class="refentrytitle"><a href="API-usb-enable-autosuspend.html"><span class="phrase">usb_enable_autosuspend</span></a></span><span class="refpurpose"> — 88 allow a USB device to be autosuspended 89 </span></dt><dt><span class="refentrytitle"><a href="API-usb-disable-autosuspend.html"><span class="phrase">usb_disable_autosuspend</span></a></span><span class="refpurpose"> — 90 prevent a USB device from being autosuspended 91 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-put-interface.html"><span class="phrase">usb_autopm_put_interface</span></a></span><span class="refpurpose"> — 92 decrement a USB interface's PM-usage counter 93 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-put-interface-async.html"><span class="phrase">usb_autopm_put_interface_async</span></a></span><span class="refpurpose"> — 94 decrement a USB interface's PM-usage counter 95 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-put-interface-no-suspend.html"><span class="phrase">usb_autopm_put_interface_no_suspend</span></a></span><span class="refpurpose"> — 96 decrement a USB interface's PM-usage counter 97 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-get-interface.html"><span class="phrase">usb_autopm_get_interface</span></a></span><span class="refpurpose"> — 98 increment a USB interface's PM-usage counter 99 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-get-interface-async.html"><span class="phrase">usb_autopm_get_interface_async</span></a></span><span class="refpurpose"> — 100 increment a USB interface's PM-usage counter 101 </span></dt><dt><span class="refentrytitle"><a href="API-usb-autopm-get-interface-no-resume.html"><span class="phrase">usb_autopm_get_interface_no_resume</span></a></span><span class="refpurpose"> — 102 increment a USB interface's PM-usage counter 103 </span></dt><dt><span class="refentrytitle"><a href="API-usb-find-alt-setting.html"><span class="phrase">usb_find_alt_setting</span></a></span><span class="refpurpose"> — 104 Given a configuration, find the alternate setting for the given interface. 105 </span></dt><dt><span class="refentrytitle"><a href="API-usb-ifnum-to-if.html"><span class="phrase">usb_ifnum_to_if</span></a></span><span class="refpurpose"> — 106 get the interface object with a given interface number 107 </span></dt><dt><span class="refentrytitle"><a href="API-usb-altnum-to-altsetting.html"><span class="phrase">usb_altnum_to_altsetting</span></a></span><span class="refpurpose"> — 108 get the altsetting structure with a given alternate setting number. 109 </span></dt><dt><span class="refentrytitle"><a href="API-usb-find-interface.html"><span class="phrase">usb_find_interface</span></a></span><span class="refpurpose"> — 110 find usb_interface pointer for driver and device 111 </span></dt><dt><span class="refentrytitle"><a href="API-usb-for-each-dev.html"><span class="phrase">usb_for_each_dev</span></a></span><span class="refpurpose"> — 112 iterate over all USB devices in the system 113 </span></dt><dt><span class="refentrytitle"><a href="API-usb-alloc-dev.html"><span class="phrase">usb_alloc_dev</span></a></span><span class="refpurpose"> — 114 usb device constructor (usbcore-internal) 115 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-dev.html"><span class="phrase">usb_get_dev</span></a></span><span class="refpurpose"> — 116 increments the reference count of the usb device structure 117 </span></dt><dt><span class="refentrytitle"><a href="API-usb-put-dev.html"><span class="phrase">usb_put_dev</span></a></span><span class="refpurpose"> — 118 release a use of the usb device structure 119 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-intf.html"><span class="phrase">usb_get_intf</span></a></span><span class="refpurpose"> — 120 increments the reference count of the usb interface structure 121 </span></dt><dt><span class="refentrytitle"><a href="API-usb-put-intf.html"><span class="phrase">usb_put_intf</span></a></span><span class="refpurpose"> — 122 release a use of the usb interface structure 123 </span></dt><dt><span class="refentrytitle"><a href="API-usb-lock-device-for-reset.html"><span class="phrase">usb_lock_device_for_reset</span></a></span><span class="refpurpose"> — 124 cautiously acquire the lock for a usb device structure 125 </span></dt><dt><span class="refentrytitle"><a href="API-usb-get-current-frame-number.html"><span class="phrase">usb_get_current_frame_number</span></a></span><span class="refpurpose"> — 126 return current bus frame number 127 </span></dt><dt><span class="refentrytitle"><a href="API-usb-alloc-coherent.html"><span class="phrase">usb_alloc_coherent</span></a></span><span class="refpurpose"> — 128 allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP 129 </span></dt><dt><span class="refentrytitle"><a href="API-usb-free-coherent.html"><span class="phrase">usb_free_coherent</span></a></span><span class="refpurpose"> — 130 free memory allocated with <code class="function">usb_alloc_coherent</code> 131 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-map.html"><span class="phrase">usb_buffer_map</span></a></span><span class="refpurpose"> — 132 create DMA mapping(s) for an urb 133 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-dmasync.html"><span class="phrase">usb_buffer_dmasync</span></a></span><span class="refpurpose"> — 134 synchronize DMA and CPU view of buffer(s) 135 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-unmap.html"><span class="phrase">usb_buffer_unmap</span></a></span><span class="refpurpose"> — 136 free DMA mapping(s) for an urb 137 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-map-sg.html"><span class="phrase">usb_buffer_map_sg</span></a></span><span class="refpurpose"> — 138 create scatterlist DMA mapping(s) for an endpoint 139 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-dmasync-sg.html"><span class="phrase">usb_buffer_dmasync_sg</span></a></span><span class="refpurpose"> — 140 synchronize DMA and CPU view of scatterlist buffer(s) 141 </span></dt><dt><span class="refentrytitle"><a href="API-usb-buffer-unmap-sg.html"><span class="phrase">usb_buffer_unmap_sg</span></a></span><span class="refpurpose"> — 142 free DMA mapping(s) for a scatterlist 143 </span></dt><dt><span class="refentrytitle"><a href="API-usb-hub-clear-tt-buffer.html"><span class="phrase">usb_hub_clear_tt_buffer</span></a></span><span class="refpurpose"> — 144 clear control/bulk TT state in high speed hub 145 </span></dt><dt><span class="refentrytitle"><a href="API-usb-set-device-state.html"><span class="phrase">usb_set_device_state</span></a></span><span class="refpurpose"> — 146 change a device's current state (usbcore, hcds) 147 </span></dt><dt><span class="refentrytitle"><a href="API-usb-root-hub-lost-power.html"><span class="phrase">usb_root_hub_lost_power</span></a></span><span class="refpurpose"> — 148 called by HCD if the root hub lost Vbus power 149 </span></dt><dt><span class="refentrytitle"><a href="API-usb-reset-device.html"><span class="phrase">usb_reset_device</span></a></span><span class="refpurpose"> — 150 warn interface drivers and perform a USB port reset 151 </span></dt><dt><span class="refentrytitle"><a href="API-usb-queue-reset-device.html"><span class="phrase">usb_queue_reset_device</span></a></span><span class="refpurpose"> — 152 Reset a USB device from an atomic context 153 </span></dt><dt><span class="refentrytitle"><a href="API-usb-hub-find-child.html"><span class="phrase">usb_hub_find_child</span></a></span><span class="refpurpose"> — 154 Get the pointer of child device attached to the port which is specified by <em class="parameter"><code>port1</code></em>. 155 </span></dt></dl></div><p>There are two basic I/O models in the USB API. 156 The most elemental one is asynchronous: drivers submit requests 157 in the form of an URB, and the URB's completion callback 158 handle the next step. 159 All USB transfer types support that model, although there 160 are special cases for control URBs (which always have setup 161 and status stages, but may not have a data stage) and 162 isochronous URBs (which allow large packets and include 163 per-packet fault reports). 164 Built on top of that is synchronous API support, where a 165 driver calls a routine that allocates one or more URBs, 166 submits them, and waits until they complete. 167 There are synchronous wrappers for single-buffer control 168 and bulk transfers (which are awkward to use in some 169 driver disconnect scenarios), and for scatterlist based 170 streaming i/o (bulk or interrupt). 171 </p><p>USB drivers need to provide buffers that can be 172 used for DMA, although they don't necessarily need to 173 provide the DMA mapping themselves. 174 There are APIs to use used when allocating DMA buffers, 175 which can prevent use of bounce buffers on some systems. 176 In some cases, drivers may be able to rely on 64bit DMA 177 to eliminate another kind of bounce buffer. 178 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-struct-usb-sg-request.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="API-usb-init-urb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">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 class="phrase">usb_init_urb</span></td></tr></table></div></body></html> 179