diff options
Diffstat (limited to 'Documentation/usb/raw-gadget.rst')
| -rw-r--r-- | Documentation/usb/raw-gadget.rst | 102 |
1 files changed, 56 insertions, 46 deletions
diff --git a/Documentation/usb/raw-gadget.rst b/Documentation/usb/raw-gadget.rst index 68d879a8009e..818a1648b387 100644 --- a/Documentation/usb/raw-gadget.rst +++ b/Documentation/usb/raw-gadget.rst @@ -2,83 +2,93 @@ USB Raw Gadget ============== -USB Raw Gadget is a kernel module that provides a userspace interface for -the USB Gadget subsystem. Essentially it allows to emulate USB devices -from userspace. Enabled with CONFIG_USB_RAW_GADGET. Raw Gadget is -currently a strictly debugging feature and shouldn't be used in -production, use GadgetFS instead. +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 a more low-level and -direct access to the USB Gadget layer for the userspace. The key -differences are: +Raw Gadget is similar to GadgetFS but provides more direct access to the +USB gadget layer for userspace. The key differences are: -1. Every USB request is passed to the userspace to get a response, while +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. However note, that the UDC driver might respond to some - requests on its own and never forward them to the Gadget layer. + descriptors. Note that the UDC driver might respond to some requests on + its own and never forward them to the gadget layer. -2. GadgetFS performs some sanity checks on the provided USB descriptors, - while Raw Gadget allows you to provide arbitrary data as responses to - USB requests. +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. + 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 allowing a user to write UDC-agnostic gadgets. + capabilities. This allows the user to write UDC-agnostic gadgets. -5. Raw Gadget has ioctl-based interface instead of a filesystem-based one. +5. Raw Gadget has an ioctl-based interface instead of a filesystem-based + one. Userspace interface ~~~~~~~~~~~~~~~~~~~ -To create a Raw Gadget instance open /dev/raw-gadget. Multiple raw-gadget -instances (bound to different UDCs) can be used at the same time. The -interaction with the opened file happens through the ioctl() calls, see -comments in include/uapi/linux/usb/raw_gadget.h for details. +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. -The typical usage of Raw Gadget looks like: +A typical usage scenario of Raw Gadget: -1. Open Raw Gadget instance via /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 calls to receive events from - Raw Gadget and react to those depending on what kind of USB device - needs to be emulated. +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 can't be used in the descriptors. -Nevertheles, Raw Gadget provides a UDC-agnostic way to write USB gadgets. -Once a USB_RAW_EVENT_CONNECT event is received via USB_RAW_IOCTL_EVENT_FETCH, -the USB_RAW_IOCTL_EPS_INFO ioctl can be used to find out information about -endpoints that the UDC driver has. Based on that information, the user must -chose UDC endpoints that will be used for the gadget being emulated, and -properly assign addresses in endpoint descriptors. +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. -You can find usage examples (along with a test suite) here: +Raw Gadget usage examples and a test suite: https://github.com/xairy/raw-gadget Internal details ~~~~~~~~~~~~~~~~ -Currently every endpoint read/write ioctl submits a USB request and waits until -its completion. This is the desired mode for coverage-guided fuzzing (as we'd -like all USB request processing happen during the lifetime of a syscall), -and must be kept in the implementation. (This might be slow for real world -applications, thus the O_NONBLOCK improvement suggestion below.) +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Report more events (suspend, resume, etc.) through USB_RAW_IOCTL_EVENT_FETCH. +- Report more events (suspend, resume, etc.) through + ``USB_RAW_IOCTL_EVENT_FETCH``. -- Support O_NONBLOCK I/O. +- 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). + enabling endpoints; allow providing ``stream_id`` for bulk transfers). -- Support ISO transfer features (expose frame_number for completed requests). +- Support ISO transfer features (expose ``frame_number`` for completed + requests). |