요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
==============
USB Raw Gadget
==============
USB Raw Gadget is a gadget driver that gives userspace low-level control over
the gadget's communication process.
Like any other gadget driver, Raw Gadget implements USB devices via the
USB gadget API. Unlike most gadget drivers, Raw Gadget does not implement
any concrete USB functions itself but requires userspace to do that.
Raw Gadget is currently a strictly debugging feature and should not be used
in production. Use GadgetFS instead.
Enabled with CONFIG_USB_RAW_GADGET.
Comparison to GadgetFS
~~~~~~~~~~~~~~~~~~~~~~
Raw Gadget is similar to GadgetFS but provides more direct access to the
USB gadget layer for userspace. The key differences are:
1. Raw Gadget passes every USB request to userspace to get a response, while
GadgetFS responds to some USB requests internally based on the provided
descriptors. Note that the UDC driver might respond to some requests on
its own and never forward them to the gadget layer.
2. Raw Gadget allows providing arbitrary data as responses to USB requests,
while GadgetFS performs sanity checks on the provided USB descriptors.
This makes Raw Gadget suitable for fuzzing by providing malformed data as
responses to USB requests.
3. Raw Gadget provides a way to select a UDC device/driver to bind to,
while GadgetFS currently binds to the first available UDC. This allows
having multiple Raw Gadget instances bound to different UDCs.
4. Raw Gadget explicitly exposes information about endpoints addresses and
capabilities. This allows the user to write UDC-agnostic gadgets.
5. Raw Gadget has an ioctl-based interface instead of a filesystem-based
one.
Userspace interface
~~~~~~~~~~~~~~~~~~~
The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and
issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h
for details. Multiple Raw Gadget instances (bound to different UDCs) can be
used at the same time.
A typical usage scenario of Raw Gadget:
1. Create a Raw Gadget instance by opening ``/dev/raw-gadget``.
2. Initialize the instance via ``USB_RAW_IOCTL_INIT``.
3. Launch the instance with ``USB_RAW_IOCTL_RUN``.
4. In a loop issue ``USB_RAW_IOCTL_EVENT_FETCH`` to receive events from
Raw Gadget and react to those depending on what kind of USB gadget must
be implemented.
Note that some UDC drivers have fixed addresses assigned to endpoints, and
therefore arbitrary endpoint addresses cannot be used in the descriptors.
Nevertheless, Raw Gadget provides a UDC-agnostic way to write USB gadgets.
Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``,
``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the
endpoints that the UDC driver has. Based on that, userspace must choose UDC
endpoints for the gadget and assign addresses in the endpoint descriptors
correspondingly.
Raw Gadget usage examples and a test suite:
https://github.com/xairy/raw-gadget
Internal details
~~~~~~~~~~~~~~~~
Every Raw Gadget endpoint read/write ioctl submits a USB request and waits
until its completion. This is done deliberately to assist with coverage-guided
fuzzing by having a single syscall fully process a single USB request. This
feature must be kept in the implementation.
Potential future improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Support ``O_NONBLOCK`` I/O. This would be another mode of operation, where
Raw Gadget would not wait until the completion of each USB request.
- Support USB 3 features (accept SS endpoint companion descriptor when
enabling endpoints; allow providing ``stream_id`` for bulk transfers).
- Support ISO transfer features (expose ``frame_number`` for completed
requests).
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
개요와 사용 제한
1-16USB Raw Gadget은 gadget 통신 과정을 사용자 공간에서 저수준으로 제어하게 하는 gadget driver입니다.
다른 gadget driver처럼 USB gadget API로 USB device를 구현하지만 구체적인 USB function은 자체 구현하지 않고 사용자 공간에 맡깁니다.
현재는 엄격히 debugging용 기능이며 production에서 사용하면 안 됩니다. production 용도에는 GadgetFS를 사용해야 합니다.
kernel option `CONFIG_USB_RAW_GADGET`으로 활성화합니다.
구현 책임과 지원 범위를 요약합니다.
==============
USB Raw Gadget
==============
USB Raw Gadget is a gadget driver that gives userspace low-level control over
the gadget's communication process.
Like any other gadget driver, Raw Gadget implements USB devices via the
USB gadget API. Unlike most gadget drivers, Raw Gadget does not implement
any concrete USB functions itself but requires userspace to do that.
Raw Gadget is currently a strictly debugging feature and should not be used
in production. Use GadgetFS instead.
Enabled with CONFIG_USB_RAW_GADGET.
GadgetFS와 비교
17-42Raw Gadget은 GadgetFS와 비슷하지만 USB gadget layer를 사용자 공간에 더 직접 노출합니다.
Raw Gadget은 모든 USB request를 사용자 공간에 전달해 응답을 받습니다. GadgetFS는 제공된 descriptor를 바탕으로 일부 request에 내부 응답합니다. 다만 UDC driver가 gadget layer로 넘기지 않고 자체 응답하는 request도 있습니다.
Raw Gadget은 arbitrary data를 응답으로 허용하지만 GadgetFS는 USB descriptor sanity check를 수행합니다. 그래서 malformed response를 제공하는 fuzzing에는 Raw Gadget이 적합합니다.
Raw Gadget은 bind할 UDC device/driver를 선택할 수 있어 여러 instance를 서로 다른 UDC에 연결할 수 있습니다. GadgetFS는 현재 첫 available UDC에 bind합니다.
Raw Gadget은 endpoint address와 capability를 명시적으로 노출해 UDC-independent gadget을 작성할 수 있게 합니다.
interface는 filesystem 기반이 아니라 ioctl 기반입니다.
request 처리, validation, UDC 선택, endpoint 정보와 interface 차이입니다.
Comparison to GadgetFS
~~~~~~~~~~~~~~~~~~~~~~
Raw Gadget is similar to GadgetFS but provides more direct access to the
USB gadget layer for userspace. The key differences are:
1. Raw Gadget passes every USB request to userspace to get a response, while
GadgetFS responds to some USB requests internally based on the provided
descriptors. Note that the UDC driver might respond to some requests on
its own and never forward them to the gadget layer.
2. Raw Gadget allows providing arbitrary data as responses to USB requests,
while GadgetFS performs sanity checks on the provided USB descriptors.
This makes Raw Gadget suitable for fuzzing by providing malformed data as
responses to USB requests.
3. Raw Gadget provides a way to select a UDC device/driver to bind to,
while GadgetFS currently binds to the first available UDC. This allows
having multiple Raw Gadget instances bound to different UDCs.
4. Raw Gadget explicitly exposes information about endpoints addresses and
capabilities. This allows the user to write UDC-agnostic gadgets.
5. Raw Gadget has an ioctl-based interface instead of a filesystem-based
one.
사용자 공간 interface
43-72사용자는 `/dev/raw-gadget`을 열고 ioctl을 호출합니다. 자세한 계약은 `include/uapi/linux/usb/raw_gadget.h`의 주석에 있습니다.
서로 다른 UDC에 bind한 Raw Gadget instance를 동시에 여러 개 사용할 수 있습니다.
일반적인 순서는 device file open, `USB_RAW_IOCTL_INIT`, `USB_RAW_IOCTL_RUN`, 반복적인 `USB_RAW_IOCTL_EVENT_FETCH`와 event별 응답입니다.
일부 UDC driver는 endpoint address가 고정되어 descriptor에 arbitrary address를 사용할 수 없습니다.
`USB_RAW_EVENT_CONNECT`를 받으면 `USB_RAW_IOCTL_EPS_INFO`로 UDC endpoint 정보를 얻고 사용자 공간이 gadget endpoint를 고른 뒤 descriptor address를 맞춰야 합니다.
사용 예제와 test suite는 `https://github.com/xairy/raw-gadget`에 있습니다.
device open부터 event loop까지 ioctl 순서입니다.
connect event 뒤 실제 UDC capability에 맞춰 descriptor address를 결정합니다.
Userspace interface
~~~~~~~~~~~~~~~~~~~
The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and
issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h
for details. Multiple Raw Gadget instances (bound to different UDCs) can be
used at the same time.
A typical usage scenario of Raw Gadget:
1. Create a Raw Gadget instance by opening ``/dev/raw-gadget``.
2. Initialize the instance via ``USB_RAW_IOCTL_INIT``.
3. Launch the instance with ``USB_RAW_IOCTL_RUN``.
4. In a loop issue ``USB_RAW_IOCTL_EVENT_FETCH`` to receive events from
Raw Gadget and react to those depending on what kind of USB gadget must
be implemented.
Note that some UDC drivers have fixed addresses assigned to endpoints, and
therefore arbitrary endpoint addresses cannot be used in the descriptors.
Nevertheless, Raw Gadget provides a UDC-agnostic way to write USB gadgets.
Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``,
``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the
endpoints that the UDC driver has. Based on that, userspace must choose UDC
endpoints for the gadget and assign addresses in the endpoint descriptors
correspondingly.
Raw Gadget usage examples and a test suite:
https://github.com/xairy/raw-gadget
내부 동작
73-80각 Raw Gadget endpoint read/write ioctl은 USB request를 submit하고 완료될 때까지 기다립니다.
한 syscall이 USB request 하나를 완전히 처리하게 해 coverage-guided fuzzing을 돕기 위한 의도적 설계이므로 구현에서 유지해야 합니다.
한 syscall과 한 USB request를 대응시켜 fuzzing coverage를 명확하게 합니다.
Internal details
~~~~~~~~~~~~~~~~
Every Raw Gadget endpoint read/write ioctl submits a USB request and waits
until its completion. This is done deliberately to assist with coverage-guided
fuzzing by having a single syscall fully process a single USB request. This
feature must be kept in the implementation.
향후 개선 가능성
81-91`O_NONBLOCK` I/O 지원을 추가하면 각 request 완료를 기다리지 않는 별도 operation mode를 제공할 수 있습니다.
USB 3 지원 후보에는 endpoint enable 시 SS endpoint companion descriptor 수용과 bulk transfer의 `stream_id` 제공이 있습니다.
ISO transfer 지원 후보에는 완료 request의 `frame_number` 노출이 있습니다.
비동기 I/O와 USB 3/ISO 기능 후보입니다.
Potential future improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Support ``O_NONBLOCK`` I/O. This would be another mode of operation, where
Raw Gadget would not wait until the completion of each USB request.
- Support USB 3 features (accept SS endpoint companion descriptor when
enabling endpoints; allow providing ``stream_id`` for bulk transfers).
- Support ISO transfer features (expose ``frame_number`` for completed
requests).
요약·해설
raw-gadget.rst:1-91Raw Gadget과 GadgetFS의 차이, ioctl interface, UDC endpoint 선택과 fuzzing 설계를 설명합니다.
원문 명령, symbol, source path, 수치와 ABI 이름을 그대로 유지하면서 각 절의 의미와 주의 사항을 한국어로 옮겼습니다.