요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
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 https://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 (https://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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
USB bulk stream 배경
1-15Bulk endpoint stream은 USB 3.0 specification에 추가됐습니다. Stream을 사용하면 device driver가 하나의 bulk endpoint에 여러 transfer를 동시에 queue할 수 있습니다.
Stream은 Universal Serial Bus 3.0 specification의 4.4.6.4절과 8.12.1.4절에 정의되어 있으며 문서는 `https://www.usb.org/developers/docs/`에서 찾을 수 있습니다. 여러 SCSI command를 queue하기 위해 stream을 사용하는 USB Attached SCSI Protocol은 T10 website `https://t10.org/`에 있습니다.
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 https://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 (https://t10.org/).
Device 쪽 동작
16-26Buffer가 stream ring에 queue되면 다른 endpoint의 out-of-band mechanism으로 해당 stream ID에 data가 준비됐음을 device에 알립니다. Device는 시작하려는 stream을 host에 지정합니다.
Host도 device 요청 없이 stream transfer를 시작할 수 있지만 device가 이를 거부할 수 있습니다. Device는 언제든 stream 사이를 전환할 수 있습니다.
Queue된 buffer와 device·host의 stream 선택 관계입니다.
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의 stream 할당
27-59Device driver는 `usb_alloc_streams()`를 호출해 host controller driver가 최대 `num_streams`개의 stream ID를 사용할 memory를 할당하도록 요청합니다. 같은 stream ID를 설정해야 하는 `usb_host_endpoint` array를 전달합니다. UASP의 bidirectional command sequence에서 bulk IN과 OUT endpoint가 동일한 stream ID를 쓰도록 보장하기 위한 설계입니다.
반환값은 endpoint가 stream을 지원하지 않거나 xHCI driver에 memory가 부족한 경우의 error, 또는 host controller가 해당 endpoint에 실제 할당한 stream 수입니다. xHCI hardware와 각 SuperSpeed bulk endpoint가 지원 수를 선언하므로 driver는 요청보다 적은 stream ID가 할당되는 경우를 처리해야 합니다.
Argument로 전달하는 endpoint 중 하나라도 URB가 queue된 상태라면 `usb_alloc_streams()`를 호출하면 안 됩니다. 2개 미만의 stream도 요청하면 안 됩니다.
같은 endpoint에는 `usb_free_streams()`를 호출하기 전까지 이 API를 한 번만 호출할 수 있습니다. 이는 xHCI host controller driver를 단순화하기 위한 제한이며 앞으로 바뀔 수 있습니다.
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.
사용할 Stream ID 선택
60-70Stream ID 0은 reserved이므로 device 통신에 사용하면 안 됩니다. `usb_alloc_streams()`가 N을 반환하면 stream 1부터 N까지 사용할 수 있습니다.
특정 stream에 URB를 queue하려면 `urb->stream_id`를 설정합니다. Endpoint가 stream을 지원하지 않으면 error가 반환됩니다. xHCI driver가 secondary stream ID를 지원하게 되면 다음 stream ID를 고르는 새 API가 필요합니다.
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.
Stream 정리
71-83Driver가 device와 stream 통신을 중단하려면 `usb_free_streams()`를 호출합니다. 함수에는 interface, endpoint array, endpoint 수와 allocation flag를 전달합니다.
Driver가 interface를 release하면 모든 stream ID가 deallocate됩니다. 따라서 stream을 지원하지 않는 다음 driver도 endpoint를 사용할 수 있습니다.
명시적 정리와 interface release 시의 안전망입니다.
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.
요약·해설
bulk-streams.rst:1-83Bulk stream은 하나의 SuperSpeed bulk endpoint에서 여러 transfer를 stream ID로 구분해 queue합니다. Driver는 endpoint 집합에 stream을 할당하고 실제 할당 수와 lifecycle 제한을 처리해야 합니다.