1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>struct urb</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="hostside.html" title="Chapter 4. Host-Side Data Types and Macros"><link rel="prev" href="API-module-usb-driver.html" title="module_usb_driver"><link rel="next" href="API-usb-fill-control-urb.html" title="usb_fill_control_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"><span class="phrase">struct urb</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-module-usb-driver.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Host-Side Data Types and Macros</th><td width="20%" align="right"> <a accesskey="n" href="API-usb-fill-control-urb.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-struct-urb"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>struct urb — 2 USB Request Block 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="programlisting"> 4struct urb { 5 struct list_head urb_list; 6 struct list_head anchor_list; 7 struct usb_anchor * anchor; 8 struct usb_device * dev; 9 struct usb_host_endpoint * ep; 10 unsigned int pipe; 11 unsigned int stream_id; 12 int status; 13 unsigned int transfer_flags; 14 void * transfer_buffer; 15 dma_addr_t transfer_dma; 16 struct scatterlist * sg; 17 int num_mapped_sgs; 18 int num_sgs; 19 u32 transfer_buffer_length; 20 u32 actual_length; 21 unsigned char * setup_packet; 22 dma_addr_t setup_dma; 23 int start_frame; 24 int number_of_packets; 25 int interval; 26 int error_count; 27 void * context; 28 usb_complete_t complete; 29 struct usb_iso_packet_descriptor iso_frame_desc[0]; 30}; </pre></div><div class="refsect1"><a name="idp1115816068"></a><h2>Members</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">urb_list</span></dt><dd><p> 31 For use by current owner of the URB. 32 </p></dd><dt><span class="term">anchor_list</span></dt><dd><p> 33 membership in the list of an anchor 34 </p></dd><dt><span class="term">anchor</span></dt><dd><p> 35 to anchor URBs to a common mooring 36 </p></dd><dt><span class="term">dev</span></dt><dd><p> 37 Identifies the USB device to perform the request. 38 </p></dd><dt><span class="term">ep</span></dt><dd><p> 39 Points to the endpoint's data structure. Will eventually 40 replace <em class="parameter"><code>pipe</code></em>. 41 </p></dd><dt><span class="term">pipe</span></dt><dd><p> 42 Holds endpoint number, direction, type, and more. 43 Create these values with the eight macros available; 44 usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is <span class="quote">“<span class="quote">ctrl</span>”</span> 45 (control), <span class="quote">“<span class="quote">bulk</span>”</span>, <span class="quote">“<span class="quote">int</span>”</span> (interrupt), or <span class="quote">“<span class="quote">iso</span>”</span> (isochronous). 46 For example <code class="function">usb_sndbulkpipe</code> or <code class="function">usb_rcvintpipe</code>. Endpoint 47 numbers range from zero to fifteen. Note that <span class="quote">“<span class="quote">in</span>”</span> endpoint two 48 is a different endpoint (and pipe) from <span class="quote">“<span class="quote">out</span>”</span> endpoint two. 49 The current configuration controls the existence, type, and 50 maximum packet size of any given endpoint. 51 </p></dd><dt><span class="term">stream_id</span></dt><dd><p> 52 the endpoint's stream ID for bulk streams 53 </p></dd><dt><span class="term">status</span></dt><dd><p> 54 This is read in non-iso completion functions to get the 55 status of the particular request. ISO requests only use it 56 to tell whether the URB was unlinked; detailed status for 57 each frame is in the fields of the iso_frame-desc. 58 </p></dd><dt><span class="term">transfer_flags</span></dt><dd><p> 59 A variety of flags may be used to affect how URB 60 submission, unlinking, or operation are handled. Different 61 kinds of URB can use different flags. 62 </p></dd><dt><span class="term">transfer_buffer</span></dt><dd><p> 63 This identifies the buffer to (or from) which the I/O 64 request will be performed unless URB_NO_TRANSFER_DMA_MAP is set 65 (however, do not leave garbage in transfer_buffer even then). 66 This buffer must be suitable for DMA; allocate it with 67 <code class="function">kmalloc</code> or equivalent. For transfers to <span class="quote">“<span class="quote">in</span>”</span> endpoints, contents 68 of this buffer will be modified. This buffer is used for the data 69 stage of control transfers. 70 </p></dd><dt><span class="term">transfer_dma</span></dt><dd><p> 71 When transfer_flags includes URB_NO_TRANSFER_DMA_MAP, 72 the device driver is saying that it provided this DMA address, 73 which the host controller driver should use in preference to the 74 transfer_buffer. 75 </p></dd><dt><span class="term">sg</span></dt><dd><p> 76 scatter gather buffer list, the buffer size of each element in 77 the list (except the last) must be divisible by the endpoint's 78 max packet size if no_sg_constraint isn't set in 'struct usb_bus' 79 </p></dd><dt><span class="term">num_mapped_sgs</span></dt><dd><p> 80 (internal) number of mapped sg entries 81 </p></dd><dt><span class="term">num_sgs</span></dt><dd><p> 82 number of entries in the sg list 83 </p></dd><dt><span class="term">transfer_buffer_length</span></dt><dd><p> 84 How big is transfer_buffer. The transfer may 85 be broken up into chunks according to the current maximum packet 86 size for the endpoint, which is a function of the configuration 87 and is encoded in the pipe. When the length is zero, neither 88 transfer_buffer nor transfer_dma is used. 89 </p></dd><dt><span class="term">actual_length</span></dt><dd><p> 90 This is read in non-iso completion functions, and 91 it tells how many bytes (out of transfer_buffer_length) were 92 transferred. It will normally be the same as requested, unless 93 either an error was reported or a short read was performed. 94 The URB_SHORT_NOT_OK transfer flag may be used to make such 95 short reads be reported as errors. 96 </p></dd><dt><span class="term">setup_packet</span></dt><dd><p> 97 Only used for control transfers, this points to eight bytes 98 of setup data. Control transfers always start by sending this data 99 to the device. Then transfer_buffer is read or written, if needed. 100 </p></dd><dt><span class="term">setup_dma</span></dt><dd><p> 101 DMA pointer for the setup packet. The caller must not use 102 this field; setup_packet must point to a valid buffer. 103 </p></dd><dt><span class="term">start_frame</span></dt><dd><p> 104 Returns the initial frame for isochronous transfers. 105 </p></dd><dt><span class="term">number_of_packets</span></dt><dd><p> 106 Lists the number of ISO transfer buffers. 107 </p></dd><dt><span class="term">interval</span></dt><dd><p> 108 Specifies the polling interval for interrupt or isochronous 109 transfers. The units are frames (milliseconds) for full and low 110 speed devices, and microframes (1/8 millisecond) for highspeed 111 and SuperSpeed devices. 112 </p></dd><dt><span class="term">error_count</span></dt><dd><p> 113 Returns the number of ISO transfers that reported errors. 114 </p></dd><dt><span class="term">context</span></dt><dd><p> 115 For use in completion functions. This normally points to 116 request-specific driver context. 117 </p></dd><dt><span class="term">complete</span></dt><dd><p> 118 Completion handler. This URB is passed as the parameter to the 119 completion function. The completion function may then do what 120 it likes with the URB, including resubmitting or freeing it. 121 </p></dd><dt><span class="term">iso_frame_desc[0]</span></dt><dd><p> 122 Used to provide arrays of ISO transfer buffers and to 123 collect the transfer status for each buffer. 124 </p></dd></dl></div></div><div class="refsect1"><a name="idp1115839436"></a><h2>Description</h2><p> 125 This structure identifies USB transfer requests. URBs must be allocated by 126 calling <code class="function">usb_alloc_urb</code> and freed with a call to <code class="function">usb_free_urb</code>. 127 Initialization may be done using various usb_fill_*<code class="function">_urb</code> functions. URBs 128 are submitted using <code class="function">usb_submit_urb</code>, and pending requests may be canceled 129 using <code class="function">usb_unlink_urb</code> or <code class="function">usb_kill_urb</code>. 130</p></div><div class="refsect1"><a name="idp1115842148"></a><h2>Data Transfer Buffers</h2><p> 131 </p><p> 132 133 Normally drivers provide I/O buffers allocated with <code class="function">kmalloc</code> or otherwise 134 taken from the general page pool. That is provided by transfer_buffer 135 (control requests also use setup_packet), and host controller drivers 136 perform a dma mapping (and unmapping) for each buffer transferred. Those 137 mapping operations can be expensive on some platforms (perhaps using a dma 138 bounce buffer or talking to an IOMMU), 139 although they're cheap on commodity x86 and ppc hardware. 140 </p><p> 141 142 Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer flag, 143 which tells the host controller driver that no such mapping is needed for 144 the transfer_buffer since 145 the device driver is DMA-aware. For example, a device driver might 146 allocate a DMA buffer with <code class="function">usb_alloc_coherent</code> or call <code class="function">usb_buffer_map</code>. 147 When this transfer flag is provided, host controller drivers will 148 attempt to use the dma address found in the transfer_dma 149 field rather than determining a dma address themselves. 150 </p><p> 151 152 Note that transfer_buffer must still be set if the controller 153 does not support DMA (as indicated by bus.uses_dma) and when talking 154 to root hub. If you have to trasfer between highmem zone and the device 155 on such controller, create a bounce buffer or bail out with an error. 156 If transfer_buffer cannot be set (is in highmem) and the controller is DMA 157 capable, assign NULL to it, so that usbmon knows not to use the value. 158 The setup_packet must always be set, so it cannot be located in highmem. 159</p></div><div class="refsect1"><a name="idp1115845556"></a><h2>Initialization</h2><p> 160 </p><p> 161 162 All URBs submitted must initialize the dev, pipe, transfer_flags (may be 163 zero), and complete fields. All URBs must also initialize 164 transfer_buffer and transfer_buffer_length. They may provide the 165 URB_SHORT_NOT_OK transfer flag, indicating that short reads are 166 to be treated as errors; that flag is invalid for write requests. 167 </p><p> 168 169 Bulk URBs may 170 use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers 171 should always terminate with a short packet, even if it means adding an 172 extra zero length packet. 173 </p><p> 174 175 Control URBs must provide a valid pointer in the setup_packet field. 176 Unlike the transfer_buffer, the setup_packet may not be mapped for DMA 177 beforehand. 178 </p><p> 179 180 Interrupt URBs must provide an interval, saying how often (in milliseconds 181 or, for highspeed devices, 125 microsecond units) 182 to poll for transfers. After the URB has been submitted, the interval 183 field reflects how the transfer was actually scheduled. 184 The polling interval may be more frequent than requested. 185 For example, some controllers have a maximum interval of 32 milliseconds, 186 while others support intervals of up to 1024 milliseconds. 187 Isochronous URBs also have transfer intervals. (Note that for isochronous 188 endpoints, as well as high speed interrupt endpoints, the encoding of 189 the transfer interval in the endpoint descriptor is logarithmic. 190 Device drivers must convert that value to linear units themselves.) 191 </p><p> 192 193 If an isochronous endpoint queue isn't already running, the host 194 controller will schedule a new URB to start as soon as bandwidth 195 utilization allows. If the queue is running then a new URB will be 196 scheduled to start in the first transfer slot following the end of the 197 preceding URB, if that slot has not already expired. If the slot has 198 expired (which can happen when IRQ delivery is delayed for a long time), 199 the scheduling behavior depends on the URB_ISO_ASAP flag. If the flag 200 is clear then the URB will be scheduled to start in the expired slot, 201 implying that some of its packets will not be transferred; if the flag 202 is set then the URB will be scheduled in the first unexpired slot, 203 breaking the queue's synchronization. Upon URB completion, the 204 start_frame field will be set to the (micro)frame number in which the 205 transfer was scheduled. Ranges for frame counter values are HC-specific 206 and can go from as low as 256 to as high as 65536 frames. 207 </p><p> 208 209 Isochronous URBs have a different data transfer model, in part because 210 the quality of service is only <span class="quote">“<span class="quote">best effort</span>”</span>. Callers provide specially 211 allocated URBs, with number_of_packets worth of iso_frame_desc structures 212 at the end. Each such packet is an individual ISO transfer. Isochronous 213 URBs are normally queued, submitted by drivers to arrange that 214 transfers are at least double buffered, and then explicitly resubmitted 215 in completion handlers, so 216 that data (such as audio or video) streams at as constant a rate as the 217 host controller scheduler can support. 218</p></div><div class="refsect1"><a name="idp1115850972"></a><h2>Completion Callbacks</h2><p> 219 </p><p> 220 221 The completion callback is made <code class="function">in_interrupt</code>, and one of the first 222 things that a completion handler should do is check the status field. 223 The status field is provided for all URBs. It is used to report 224 unlinked URBs, and status for all non-ISO transfers. It should not 225 be examined before the URB is returned to the completion handler. 226 </p><p> 227 228 The context field is normally used to link URBs back to the relevant 229 driver or request state. 230 </p><p> 231 232 When the completion callback is invoked for non-isochronous URBs, the 233 actual_length field tells how many bytes were transferred. This field 234 is updated even when the URB terminated with an error or was unlinked. 235 </p><p> 236 237 ISO transfer status is reported in the status and actual_length fields 238 of the iso_frame_desc array, and the number of errors is reported in 239 error_count. Completion callbacks for ISO transfers will normally 240 (re)submit URBs to ensure a constant transfer rate. 241 </p><p> 242 243 Note that even fields marked <span class="quote">“<span class="quote">public</span>”</span> should not be touched by the driver 244 when the urb is owned by the hcd, that is, since the call to 245 <code class="function">usb_submit_urb</code> till the entry into the completion routine. 246</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-module-usb-driver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="hostside.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-usb-fill-control-urb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">module_usb_driver</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_fill_control_urb</span></td></tr></table></div></body></html> 247