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