1STRUCT URB(9) Host-Side Data Types and Macro STRUCT URB(9)
2
6 struct_urb - USB Request Block
7
9 struct urb {
10 struct list_head urb_list;
11 struct list_head anchor_list;
12 struct usb_anchor * anchor;
13 struct usb_device * dev;
14 struct usb_host_endpoint * ep;
15 unsigned int pipe;
16 int status;
17 unsigned int transfer_flags;
18 void * transfer_buffer;
19 dma_addr_t transfer_dma;
20 struct scatterlist * sg;
21 int num_sgs;
22 u32 transfer_buffer_length;
23 u32 actual_length;
24 unsigned char * setup_packet;
25 dma_addr_t setup_dma;
26 int start_frame;
27 int number_of_packets;
28 int interval;
29 int error_count;
30 void * context;
31 usb_complete_t complete;
32 struct usb_iso_packet_descriptor iso_frame_desc[0];
33 };
34
36 urb_list
37 For use by current owner of the URB.
38 anchor_list
40 membership in the list of an anchor
41 anchor
43 to anchor URBs to a common mooring
44 dev
46 Identifies the USB device to perform the request.
47 ep
49 Points to the endpoint's data structure. Will eventually replace
50 pipe.
51 pipe
53 Holds endpoint number, direction, type, and more. Create these
54 values with the eight macros available;
55 usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is “ctrl”
56 (control), “bulk”, “int” (interrupt), or “iso” (isochronous). For
57 example usb_sndbulkpipe or usb_rcvintpipe. Endpoint numbers range
58 from zero to fifteen. Note that “in” endpoint two is a different
59 endpoint (and pipe) from “out” endpoint two. The current
60 configuration controls the existence, type, and maximum packet size
61 of any given endpoint.
62 status
64 This is read in non-iso completion functions to get the status of
65 the particular request. ISO requests only use it to tell whether
66 the URB was unlinked; detailed status for each frame is in the
67 fields of the iso_frame-desc.
68 transfer_flags
70 A variety of flags may be used to affect how URB submission,
71 unlinking, or operation are handled. Different kinds of URB can use
72 different flags.
73 transfer_buffer
75 This identifies the buffer to (or from) which the I/O request will
76 be performed unless URB_NO_TRANSFER_DMA_MAP is set (however, do not
77 leave garbage in transfer_buffer even then). This buffer must be
78 suitable for DMA; allocate it with kmalloc or equivalent. For
79 transfers to “in” endpoints, contents of this buffer will be
80 modified. This buffer is used for the data stage of control
81 transfers.
82 transfer_dma
84 When transfer_flags includes URB_NO_TRANSFER_DMA_MAP, the device
85 driver is saying that it provided this DMA address, which the host
86 controller driver should use in preference to the transfer_buffer.
87 sg
89 scatter gather buffer list
90 num_sgs
92 number of entries in the sg list
93 transfer_buffer_length
95 How big is transfer_buffer. The transfer may be broken up into
96 chunks according to the current maximum packet size for the
97 endpoint, which is a function of the configuration and is encoded
98 in the pipe. When the length is zero, neither transfer_buffer nor
99 transfer_dma is used.
100 actual_length
102 This is read in non-iso completion functions, and it tells how many
103 bytes (out of transfer_buffer_length) were transferred. It will
104 normally be the same as requested, unless either an error was
105 reported or a short read was performed. The URB_SHORT_NOT_OK
106 transfer flag may be used to make such short reads be reported as
107 errors.
108 setup_packet
110 Only used for control transfers, this points to eight bytes of
111 setup data. Control transfers always start by sending this data to
112 the device. Then transfer_buffer is read or written, if needed.
113 setup_dma
115 DMA pointer for the setup packet. The caller must not use this
116 field; setup_packet must point to a valid buffer.
117 start_frame
119 Returns the initial frame for isochronous transfers.
120 number_of_packets
122 Lists the number of ISO transfer buffers.
123 interval
125 Specifies the polling interval for interrupt or isochronous
126 transfers. The units are frames (milliseconds) for full and low
127 speed devices, and microframes (1/8 millisecond) for highspeed and
128 SuperSpeed devices.
129 error_count
131 Returns the number of ISO transfers that reported errors.
132 context
134 For use in completion functions. This normally points to
135 request-specific driver context.
136 complete
138 Completion handler. This URB is passed as the parameter to the
139 completion function. The completion function may then do what it
140 likes with the URB, including resubmitting or freeing it.
141 iso_frame_desc[0]
143 Used to provide arrays of ISO transfer buffers and to collect the
144 transfer status for each buffer.
145
147 This structure identifies USB transfer requests. URBs must be allocated
148 by calling usb_alloc_urb and freed with a call to usb_free_urb.
149 Initialization may be done using various usb_fill_*_urb functions. URBs
150 are submitted using usb_submit_urb, and pending requests may be
151 canceled using usb_unlink_urb or usb_kill_urb.
152
154 Normally drivers provide I/O buffers allocated with kmalloc or
155 otherwise taken from the general page pool. That is provided by
156 transfer_buffer (control requests also use setup_packet), and host
157 controller drivers perform a dma mapping (and unmapping) for each
158 buffer transferred. Those mapping operations can be expensive on some
159 platforms (perhaps using a dma bounce buffer or talking to an IOMMU),
160 although they're cheap on commodity x86 and ppc hardware.
161 Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer
163 flag, which tells the host controller driver that no such mapping is
164 needed for the transfer_buffer since the device driver is DMA-aware.
165 For example, a device driver might allocate a DMA buffer with
166 usb_alloc_coherent or call usb_buffer_map. When this transfer flag is
167 provided, host controller drivers will attempt to use the dma address
168 found in the transfer_dma field rather than determining a dma address
169 themselves.
170 Note that transfer_buffer must still be set if the controller does not
172 support DMA (as indicated by bus.uses_dma) and when talking to root
173 hub. If you have to trasfer between highmem zone and the device on such
174 controller, create a bounce buffer or bail out with an error. If
175 transfer_buffer cannot be set (is in highmem) and the controller is DMA
176 capable, assign NULL to it, so that usbmon knows not to use the value.
177 The setup_packet must always be set, so it cannot be located in
178 highmem.
179
181 All URBs submitted must initialize the dev, pipe, transfer_flags (may
182 be zero), and complete fields. All URBs must also initialize
183 transfer_buffer and transfer_buffer_length. They may provide the
184 URB_SHORT_NOT_OK transfer flag, indicating that short reads are to be
185 treated as errors; that flag is invalid for write requests.
186 Bulk URBs may use the URB_ZERO_PACKET transfer flag, indicating that
188 bulk OUT transfers should always terminate with a short packet, even if
189 it means adding an extra zero length packet.
190 Control URBs must provide a valid pointer in the setup_packet field.
192 Unlike the transfer_buffer, the setup_packet may not be mapped for DMA
193 beforehand.
194 Interrupt URBs must provide an interval, saying how often (in
196 milliseconds or, for highspeed devices, 125 microsecond units) to poll
197 for transfers. After the URB has been submitted, the interval field
198 reflects how the transfer was actually scheduled. The polling interval
199 may be more frequent than requested. For example, some controllers have
200 a maximum interval of 32 milliseconds, while others support intervals
201 of up to 1024 milliseconds. Isochronous URBs also have transfer
202 intervals. (Note that for isochronous endpoints, as well as high speed
203 interrupt endpoints, the encoding of the transfer interval in the
204 endpoint descriptor is logarithmic. Device drivers must convert that
205 value to linear units themselves.)
206 Isochronous URBs normally use the URB_ISO_ASAP transfer flag, telling
208 the host controller to schedule the transfer as soon as bandwidth
209 utilization allows, and then set start_frame to reflect the actual
210 frame selected during submission. Otherwise drivers must specify the
211 start_frame and handle the case where the transfer can't begin then.
212 However, drivers won't know how bandwidth is currently allocated, and
213 while they can find the current frame using
214 usb_get_current_frame_number () they can't know the range for that
215 frame number. (Ranges for frame counter values are HC-specific, and can
216 go from 256 to 65536 frames from “now”.)
217 Isochronous URBs have a different data transfer model, in part because
219 the quality of service is only “best effort”. Callers provide specially
220 allocated URBs, with number_of_packets worth of iso_frame_desc
221 structures at the end. Each such packet is an individual ISO transfer.
222 Isochronous URBs are normally queued, submitted by drivers to arrange
223 that transfers are at least double buffered, and then explicitly
224 resubmitted in completion handlers, so that data (such as audio or
225 video) streams at as constant a rate as the host controller scheduler
226 can support.
227
229 The completion callback is made in_interrupt, and one of the first
230 things that a completion handler should do is check the status field.
231 The status field is provided for all URBs. It is used to report
232 unlinked URBs, and status for all non-ISO transfers. It should not be
233 examined before the URB is returned to the completion handler.
234 The context field is normally used to link URBs back to the relevant
236 driver or request state.
237 When the completion callback is invoked for non-isochronous URBs, the
239 actual_length field tells how many bytes were transferred. This field
240 is updated even when the URB terminated with an error or was unlinked.
241 ISO transfer status is reported in the status and actual_length fields
243 of the iso_frame_desc array, and the number of errors is reported in
244 error_count. Completion callbacks for ISO transfers will normally
245 (re)submit URBs to ensure a constant transfer rate.
246 Note that even fields marked “public” should not be touched by the
248 driver when the urb is owned by the hcd, that is, since the call to
249 usb_submit_urb till the entry into the completion routine.
250
252Kernel Hackers Manual 2.6. November 2011 STRUCT URB(9)