linux/Documentation/usb/raw-gadget.rst
<<
>>
Prefs
   1==============
   2USB Raw Gadget
   3==============
   4
   5USB Raw Gadget is a gadget driver that gives userspace low-level control over
   6the gadget's communication process.
   7
   8Like any other gadget driver, Raw Gadget implements USB devices via the
   9USB gadget API. Unlike most gadget drivers, Raw Gadget does not implement
  10any concrete USB functions itself but requires userspace to do that.
  11
  12Raw Gadget is currently a strictly debugging feature and should not be used
  13in production. Use GadgetFS instead.
  14
  15Enabled with CONFIG_USB_RAW_GADGET.
  16
  17Comparison to GadgetFS
  18~~~~~~~~~~~~~~~~~~~~~~
  19
  20Raw Gadget is similar to GadgetFS but provides more direct access to the
  21USB gadget layer for userspace. The key differences are:
  22
  231. Raw Gadget passes every USB request to userspace to get a response, while
  24   GadgetFS responds to some USB requests internally based on the provided
  25   descriptors. Note that the UDC driver might respond to some requests on
  26   its own and never forward them to the gadget layer.
  27
  282. Raw Gadget allows providing arbitrary data as responses to USB requests,
  29   while GadgetFS performs sanity checks on the provided USB descriptors.
  30   This makes Raw Gadget suitable for fuzzing by providing malformed data as
  31   responses to USB requests.
  32
  333. Raw Gadget provides a way to select a UDC device/driver to bind to,
  34   while GadgetFS currently binds to the first available UDC. This allows
  35   having multiple Raw Gadget instances bound to different UDCs.
  36
  374. Raw Gadget explicitly exposes information about endpoints addresses and
  38   capabilities. This allows the user to write UDC-agnostic gadgets.
  39
  405. Raw Gadget has an ioctl-based interface instead of a filesystem-based
  41   one.
  42
  43Userspace interface
  44~~~~~~~~~~~~~~~~~~~
  45
  46The user can interact with Raw Gadget by opening ``/dev/raw-gadget`` and
  47issuing ioctl calls; see the comments in include/uapi/linux/usb/raw_gadget.h
  48for details. Multiple Raw Gadget instances (bound to different UDCs) can be
  49used at the same time.
  50
  51A typical usage scenario of Raw Gadget:
  52
  531. Create a Raw Gadget instance by opening ``/dev/raw-gadget``.
  542. Initialize the instance via ``USB_RAW_IOCTL_INIT``.
  553. Launch the instance with ``USB_RAW_IOCTL_RUN``.
  564. In a loop issue ``USB_RAW_IOCTL_EVENT_FETCH`` to receive events from
  57   Raw Gadget and react to those depending on what kind of USB gadget must
  58   be implemented.
  59
  60Note that some UDC drivers have fixed addresses assigned to endpoints, and
  61therefore arbitrary endpoint addresses cannot be used in the descriptors.
  62Nevertheless, Raw Gadget provides a UDC-agnostic way to write USB gadgets.
  63Once ``USB_RAW_EVENT_CONNECT`` is received via ``USB_RAW_IOCTL_EVENT_FETCH``,
  64``USB_RAW_IOCTL_EPS_INFO`` can be used to find out information about the
  65endpoints that the UDC driver has. Based on that, userspace must choose UDC
  66endpoints for the gadget and assign addresses in the endpoint descriptors
  67correspondingly.
  68
  69Raw Gadget usage examples and a test suite:
  70
  71https://github.com/xairy/raw-gadget
  72
  73Internal details
  74~~~~~~~~~~~~~~~~
  75
  76Every Raw Gadget endpoint read/write ioctl submits a USB request and waits
  77until its completion. This is done deliberately to assist with coverage-guided
  78fuzzing by having a single syscall fully process a single USB request. This
  79feature must be kept in the implementation.
  80
  81Potential future improvements
  82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84- Report more events (suspend, resume, etc.) through
  85  ``USB_RAW_IOCTL_EVENT_FETCH``.
  86
  87- Support ``O_NONBLOCK`` I/O. This would be another mode of operation, where
  88  Raw Gadget would not wait until the completion of each USB request.
  89
  90- Support USB 3 features (accept SS endpoint companion descriptor when
  91  enabling endpoints; allow providing ``stream_id`` for bulk transfers).
  92
  93- Support ISO transfer features (expose ``frame_number`` for completed
  94  requests).
  95