redonkable
/
alistair23-linux
1
0
Fork 0
Code Releases Activity

usb: raw-gadget: update documentation and Kconfig 

Update Raw Gadget documentation and Kconfig. Make the description more
precise and clear, fix typos and grammar mistakes, and do other cleanups.

Signed-off-by: Andrey Konovalov <andreyknvl@google.com>
Link: https://lore.kernel.org/r/f4c650c94ae2b910e38819d51109cd5f0b251a2a.1611429174.git.andreyknvl@google.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
master
Andrey Konovalov 2021-01-23 20:14:17 +01:00 committed by Greg Kroah-Hartman
parent 4c1934bda8
commit 7a35a5ca26
2 changed files with 65 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
Documentation/usb/raw-gadget.rst
View File

@ -2,83 +2,93 @@
USB Raw Gadget USB Raw Gadget
============== ==============
USB Raw Gadget is a kernel module that provides a userspace interface for USB Raw Gadget is a gadget driver that gives userspace low-level control over
the USB Gadget subsystem. Essentially it allows to emulate USB devices the gadget's communication process.
from userspace. Enabled with CONFIG_USB_RAW_GADGET. Raw Gadget is
currently a strictly debugging feature and shouldn't be used in Like any other gadget driver, Raw Gadget implements USB devices via the
production, use GadgetFS instead. 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 Comparison to GadgetFS
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
Raw Gadget is similar to GadgetFS, but provides a more low-level and Raw Gadget is similar to GadgetFS but provides more direct access to the
direct access to the USB Gadget layer for the userspace. The key USB gadget layer for userspace. The key differences are:
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 GadgetFS responds to some USB requests internally based on the provided
descriptors. However note, that the UDC driver might respond to some descriptors. Note that the UDC driver might respond to some requests on
requests on its own and never forward them to the Gadget layer. its own and never forward them to the gadget layer.
2. GadgetFS performs some sanity checks on the provided USB descriptors, 2. Raw Gadget allows providing arbitrary data as responses to USB requests,
while Raw Gadget allows you to provide arbitrary data as responses to while GadgetFS performs sanity checks on the provided USB descriptors.
USB requests. 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, 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 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 Userspace interface
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
To create a Raw Gadget instance open /dev/raw-gadget. Multiple raw-gadget The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and
instances (bound to different UDCs) can be used at the same time. The issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h
interaction with the opened file happens through the ioctl() calls, see for details. Multiple Raw Gadget instances (bound to different UDCs) can be
comments in include/uapi/linux/usb/raw_gadget.h for details. 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. 1. Create a Raw Gadget instance by opening ``/dev/raw-gadget``.
2. Initialize the instance via USB_RAW_IOCTL_INIT. 2. Initialize the instance via ``USB_RAW_IOCTL_INIT``.
3. Launch the instance with USB_RAW_IOCTL_RUN. 3. Launch the instance with ``USB_RAW_IOCTL_RUN``.
4. In a loop issue USB_RAW_IOCTL_EVENT_FETCH calls to receive events from 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 device Raw Gadget and react to those depending on what kind of USB gadget must
needs to be emulated. be implemented.
Note, that some UDC drivers have fixed addresses assigned to endpoints, and Note that some UDC drivers have fixed addresses assigned to endpoints, and
therefore arbitrary endpoint addresses can't be used in the descriptors. therefore arbitrary endpoint addresses cannot be used in the descriptors.
Nevertheles, Raw Gadget provides a UDC-agnostic way to write USB gadgets. Nevertheless, 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, Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``,
the USB_RAW_IOCTL_EPS_INFO ioctl can be used to find out information about ``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the
endpoints that the UDC driver has. Based on that information, the user must endpoints that the UDC driver has. Based on that, userspace must choose UDC
chose UDC endpoints that will be used for the gadget being emulated, and endpoints for the gadget and assign addresses in the endpoint descriptors
properly assign addresses in 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 https://github.com/xairy/raw-gadget
Internal details Internal details
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Currently every endpoint read/write ioctl submits a USB request and waits until Every Raw Gadget endpoint read/write ioctl submits a USB request and waits
its completion. This is the desired mode for coverage-guided fuzzing (as we'd until its completion. This is done deliberately to assist with coverage-guided
like all USB request processing happen during the lifetime of a syscall), fuzzing by having a single syscall fully process a single USB request. This
and must be kept in the implementation. (This might be slow for real world feature must be kept in the implementation.
applications, thus the O_NONBLOCK improvement suggestion below.)
Potential future improvements 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 - 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).

13
drivers/usb/gadget/legacy/Kconfig
View File

@ -515,10 +515,15 @@ config USB_G_WEBCAM
config USB_RAW_GADGET config USB_RAW_GADGET
tristate "USB Raw Gadget" tristate "USB Raw Gadget"
help help
USB Raw Gadget is a kernel module that provides a userspace interface USB Raw Gadget is a gadget driver that gives userspace low-level
for the USB Gadget subsystem. Essentially it allows to emulate USB control over the gadget's communication process.
devices from userspace. See Documentation/usb/raw-gadget.rst for
details. 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.
See Documentation/usb/raw-gadget.rst for details.
Say "y" to link the driver statically, or "m" to build a Say "y" to link the driver statically, or "m" to build a
dynamically linked module called "raw_gadget". dynamically linked module called "raw_gadget".