Root/
1 | Background |
2 | ========== |
3 | |
4 | Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a |
5 | device driver to overload a bulk endpoint so that multiple transfers can be |
6 | queued at once. |
7 | |
8 | Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus |
9 | 3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI |
10 | Protocol, which uses streams to queue multiple SCSI commands, can be found on |
11 | the T10 website (http://t10.org/). |
12 | |
13 | |
14 | Device-side implications |
15 | ======================== |
16 | |
17 | Once a buffer has been queued to a stream ring, the device is notified (through |
18 | an out-of-band mechanism on another endpoint) that data is ready for that stream |
19 | ID. The device then tells the host which "stream" it wants to start. The host |
20 | can also initiate a transfer on a stream without the device asking, but the |
21 | device can refuse that transfer. Devices can switch between streams at any |
22 | time. |
23 | |
24 | |
25 | Driver implications |
26 | =================== |
27 | |
28 | int usb_alloc_streams(struct usb_interface *interface, |
29 | struct usb_host_endpoint **eps, unsigned int num_eps, |
30 | unsigned int num_streams, gfp_t mem_flags); |
31 | |
32 | Device drivers will call this API to request that the host controller driver |
33 | allocate memory so the driver can use up to num_streams stream IDs. They must |
34 | pass an array of usb_host_endpoints that need to be setup with similar stream |
35 | IDs. This is to ensure that a UASP driver will be able to use the same stream |
36 | ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. |
37 | |
38 | The return value is an error condition (if one of the endpoints doesn't support |
39 | streams, or the xHCI driver ran out of memory), or the number of streams the |
40 | host controller allocated for this endpoint. The xHCI host controller hardware |
41 | declares how many stream IDs it can support, and each bulk endpoint on a |
42 | SuperSpeed device will say how many stream IDs it can handle. Therefore, |
43 | drivers should be able to deal with being allocated less stream IDs than they |
44 | requested. |
45 | |
46 | Do NOT call this function if you have URBs enqueued for any of the endpoints |
47 | passed in as arguments. Do not call this function to request less than two |
48 | streams. |
49 | |
50 | Drivers will only be allowed to call this API once for the same endpoint |
51 | without calling usb_free_streams(). This is a simplification for the xHCI host |
52 | controller driver, and may change in the future. |
53 | |
54 | |
55 | Picking new Stream IDs to use |
56 | ============================ |
57 | |
58 | Stream ID 0 is reserved, and should not be used to communicate with devices. If |
59 | usb_alloc_streams() returns with a value of N, you may use streams 1 though N. |
60 | To queue an URB for a specific stream, set the urb->stream_id value. If the |
61 | endpoint does not support streams, an error will be returned. |
62 | |
63 | Note that new API to choose the next stream ID will have to be added if the xHCI |
64 | driver supports secondary stream IDs. |
65 | |
66 | |
67 | Clean up |
68 | ======== |
69 | |
70 | If a driver wishes to stop using streams to communicate with the device, it |
71 | should call |
72 | |
73 | void usb_free_streams(struct usb_interface *interface, |
74 | struct usb_host_endpoint **eps, unsigned int num_eps, |
75 | gfp_t mem_flags); |
76 | |
77 | All stream IDs will be deallocated when the driver releases the interface, to |
78 | ensure that drivers that don't support streams will be able to use the endpoint. |
79 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9