@@ -27,9 +27,8 @@ differences are:
27273. Raw Gadget provides a way to select a UDC device/driver to bind to,
2828 while GadgetFS currently binds to the first available UDC.
2929
30- 4. Raw Gadget uses predictable endpoint names (handles) across different
31- UDCs (as long as UDCs have enough endpoints of each required transfer
32- type).
30+ 4. Raw Gadget explicitly exposes information about endpoints addresses and
31+ capabilities allowing a user to write UDC-agnostic gadgets.
3332
34335. Raw Gadget has ioctl-based interface instead of a filesystem-based one.
3534
@@ -50,12 +49,36 @@ The typical usage of Raw Gadget looks like:
5049 Raw Gadget and react to those depending on what kind of USB device
5150 needs to be emulated.
5251
52+ Note, that some UDC drivers have fixed addresses assigned to endpoints, and
53+ therefore arbitrary endpoint addresses can't be used in the descriptors.
54+ Nevertheles, Raw Gadget provides a UDC-agnostic way to write USB gadgets.
55+ Once a USB_RAW_EVENT_CONNECT event is received via USB_RAW_IOCTL_EVENT_FETCH,
56+ the USB_RAW_IOCTL_EPS_INFO ioctl can be used to find out information about
57+ endpoints that the UDC driver has. Based on that information, the user must
58+ chose UDC endpoints that will be used for the gadget being emulated, and
59+ properly assign addresses in endpoint descriptors.
60+
61+ You can find usage examples (along with a test suite) here:
62+
63+ https://github.com/xairy/raw-gadget
64+
65+ Internal details
66+ ~~~~~~~~~~~~~~~~
67+
68+ Currently every endpoint read/write ioctl submits a USB request and waits until
69+ its completion. This is the desired mode for coverage-guided fuzzing (as we'd
70+ like all USB request processing happen during the lifetime of a syscall),
71+ and must be kept in the implementation. (This might be slow for real world
72+ applications, thus the O_NONBLOCK improvement suggestion below.)
73+
5374Potential future improvements
5475~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5576
56- - Implement ioctl's for setting/clearing halt status on endpoints.
57-
58- - Reporting more events (suspend, resume, etc.) through
59- USB_RAW_IOCTL_EVENT_FETCH.
77+ - Report more events (suspend, resume, etc.) through USB_RAW_IOCTL_EVENT_FETCH.
6078
6179- Support O_NONBLOCK I/O.
80+
81+ - Support USB 3 features (accept SS endpoint companion descriptor when
82+ enabling endpoints; allow providing stream_id for bulk transfers).
83+
84+ - Support ISO transfer features (expose frame_number for completed requests).
0 commit comments