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>
This commit is contained in:
Andrey Konovalov
Greg Kroah-Hartman
parent
4c1934bda8
commit
7a35a5ca26
@ -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).
|
||||
|
||||
@ -515,10 +515,15 @@ config USB_G_WEBCAM
|
||||
config USB_RAW_GADGET
|
||||
tristate "USB Raw Gadget"
|
||||
help
|
||||
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. See Documentation/usb/raw-gadget.rst for
|
||||
details.
|
||||
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.
|
||||
|
||||
See Documentation/usb/raw-gadget.rst for details.
|
||||
|
||||
Say "y" to link the driver statically, or "m" to build a
|
||||
dynamically linked module called "raw_gadget".
|
||||
|
||||
Loading…
Reference in New Issue
Block a user