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