From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 13:23:03 +0000 (-0300) Subject: usb/bulk-streams.txt: convert to ReST and add to driver-api book X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=401c7be2bad9eea68c1a660d54d1caa00b3098e4;p=GitHub%2FLineageOS%2Fandroid_kernel_motorola_exynos9610.git usb/bulk-streams.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/driver-api/usb/bulk-streams.rst b/Documentation/driver-api/usb/bulk-streams.rst new file mode 100644 index 000000000000..99b515babdeb --- /dev/null +++ b/Documentation/driver-api/usb/bulk-streams.rst @@ -0,0 +1,83 @@ +USB bulk streams +~~~~~~~~~~~~~~~~ + +Background +========== + +Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a +device driver to overload a bulk endpoint so that multiple transfers can be +queued at once. + +Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus +3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI +Protocol, which uses streams to queue multiple SCSI commands, can be found on +the T10 website (http://t10.org/). + + +Device-side implications +======================== + +Once a buffer has been queued to a stream ring, the device is notified (through +an out-of-band mechanism on another endpoint) that data is ready for that stream +ID. The device then tells the host which "stream" it wants to start. The host +can also initiate a transfer on a stream without the device asking, but the +device can refuse that transfer. Devices can switch between streams at any +time. + + +Driver implications +=================== + +:: + + int usb_alloc_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + unsigned int num_streams, gfp_t mem_flags); + +Device drivers will call this API to request that the host controller driver +allocate memory so the driver can use up to num_streams stream IDs. They must +pass an array of usb_host_endpoints that need to be setup with similar stream +IDs. This is to ensure that a UASP driver will be able to use the same stream +ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. + +The return value is an error condition (if one of the endpoints doesn't support +streams, or the xHCI driver ran out of memory), or the number of streams the +host controller allocated for this endpoint. The xHCI host controller hardware +declares how many stream IDs it can support, and each bulk endpoint on a +SuperSpeed device will say how many stream IDs it can handle. Therefore, +drivers should be able to deal with being allocated less stream IDs than they +requested. + +Do NOT call this function if you have URBs enqueued for any of the endpoints +passed in as arguments. Do not call this function to request less than two +streams. + +Drivers will only be allowed to call this API once for the same endpoint +without calling usb_free_streams(). This is a simplification for the xHCI host +controller driver, and may change in the future. + + +Picking new Stream IDs to use +============================= + +Stream ID 0 is reserved, and should not be used to communicate with devices. If +usb_alloc_streams() returns with a value of N, you may use streams 1 though N. +To queue an URB for a specific stream, set the urb->stream_id value. If the +endpoint does not support streams, an error will be returned. + +Note that new API to choose the next stream ID will have to be added if the xHCI +driver supports secondary stream IDs. + + +Clean up +======== + +If a driver wishes to stop using streams to communicate with the device, it +should call:: + + void usb_free_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + gfp_t mem_flags); + +All stream IDs will be deallocated when the driver releases the interface, to +ensure that drivers that don't support streams will be able to use the endpoint. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 5dfb04b2d730..6fe7611f7332 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -7,6 +7,7 @@ Linux USB API usb gadget anchors + bulk-streams writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/usb/bulk-streams.txt deleted file mode 100644 index ffc02021863e..000000000000 --- a/Documentation/usb/bulk-streams.txt +++ /dev/null @@ -1,78 +0,0 @@ -Background -========== - -Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a -device driver to overload a bulk endpoint so that multiple transfers can be -queued at once. - -Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus -3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI -Protocol, which uses streams to queue multiple SCSI commands, can be found on -the T10 website (http://t10.org/). - - -Device-side implications -======================== - -Once a buffer has been queued to a stream ring, the device is notified (through -an out-of-band mechanism on another endpoint) that data is ready for that stream -ID. The device then tells the host which "stream" it wants to start. The host -can also initiate a transfer on a stream without the device asking, but the -device can refuse that transfer. Devices can switch between streams at any -time. - - -Driver implications -=================== - -int usb_alloc_streams(struct usb_interface *interface, - struct usb_host_endpoint **eps, unsigned int num_eps, - unsigned int num_streams, gfp_t mem_flags); - -Device drivers will call this API to request that the host controller driver -allocate memory so the driver can use up to num_streams stream IDs. They must -pass an array of usb_host_endpoints that need to be setup with similar stream -IDs. This is to ensure that a UASP driver will be able to use the same stream -ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. - -The return value is an error condition (if one of the endpoints doesn't support -streams, or the xHCI driver ran out of memory), or the number of streams the -host controller allocated for this endpoint. The xHCI host controller hardware -declares how many stream IDs it can support, and each bulk endpoint on a -SuperSpeed device will say how many stream IDs it can handle. Therefore, -drivers should be able to deal with being allocated less stream IDs than they -requested. - -Do NOT call this function if you have URBs enqueued for any of the endpoints -passed in as arguments. Do not call this function to request less than two -streams. - -Drivers will only be allowed to call this API once for the same endpoint -without calling usb_free_streams(). This is a simplification for the xHCI host -controller driver, and may change in the future. - - -Picking new Stream IDs to use -============================ - -Stream ID 0 is reserved, and should not be used to communicate with devices. If -usb_alloc_streams() returns with a value of N, you may use streams 1 though N. -To queue an URB for a specific stream, set the urb->stream_id value. If the -endpoint does not support streams, an error will be returned. - -Note that new API to choose the next stream ID will have to be added if the xHCI -driver supports secondary stream IDs. - - -Clean up -======== - -If a driver wishes to stop using streams to communicate with the device, it -should call - -void usb_free_streams(struct usb_interface *interface, - struct usb_host_endpoint **eps, unsigned int num_eps, - gfp_t mem_flags); - -All stream IDs will be deallocated when the driver releases the interface, to -ensure that drivers that don't support streams will be able to use the endpoint.