crackercat / raw-gadget

USB Raw Gadget — low-level interface for the Linux USB Gadget subsystem

Raw Gadget

Note: most likely you need GadgetFS, not Raw Gadget. See the differences here.

USB Raw Gadget is a low-level interface for the Linux USB Gadget subsystem. It can be used to emulate physical USB devices with special hardware, or virtual ones (for the kernel it's running on) with Dummy HCD/UDC. This repository contains instructions and examples for using Raw Gadget.

Raw Gadget has been merged into mainline Linux kernel in 5.7. There's no need to use 5.7+ kernels, see dummy_hcd and raw_gadget for information on how to build and insmod corresponding modules on older kernels. The modules should be compatible with kernel versions down to 4.14, see the table below.

Building kernel modules requires kernel headers. On desktop Ubuntu you can get them by installing linux-headers-`uname -r`. On Raspberry Pi Zero follow these instructions.

USB Device Controllers

USB Raw Gadget requires the user to provide UDC device and driver names, see examples.

UDC device name can be found in /sys/class/udc/:

$ ls /sys/class/udc/
dummy_udc.0

UDC driver name is usually present in /sys/class/udc/$UDC/uevent:

$ cat /sys/class/udc/dummy_udc.0/uevent
USB_UDC_NAME=dummy_udc

"Works" in the table below means that the UDC passes the provided tests, which only cover a subset of functionality and therefore have limitations.

Hardware	Kernel	Driver	Device	Works?
	5.3.0-45-generic	dummy_udc	dummy_udc.0	Yes
Raspberry Pi Zero	4.14.97+	20980000.usb	20980000.usb (dwc2)	Yes
Raspberry Pi 4	5.10.63-v7l+	fe980000.usb	fe980000.usb (dwc2)	Yes
USB Armory MkII	5.4.87-0	2184000.usb	ci_hdrc.0	Yes
Orange Pi PC	5.10.60	musb-hdrc	musb-hdrc.4.auto	Yes
Orange Pi PC 2	5.10.60	musb-hdrc	musb-hdrc.4.auto	Yes
Khadas VIM1	5.10.60-meson64	c9100000.usb	c9100000.usb	Yes
BeagleBone Black	4.19.94-ti-r42	musb-hdrc	musb-hdrc.0	Probably
BeagleBone AI	4.14.108-ti-r131	48890000.usb	dwc3-gadget	Not yet
EC3380-AB	5.3.0-45-generic	net2280	0000:04:00.0 (e.g.)	Partially, net2280 buggy
Odroid C2	3.14.79-116	dwc_otg_pcd	dwc2_a	No, kernel too old

Projects based on Raw Gadget

• syzkaller — a kernel fuzzer, uses Raw Gadget for fuzzing Linux kernel USB drivers.
• usb-proxy — A USB proxy based on Raw Gadget and libusb.

TODO

• TODOs in kernel documentation
• TODOs in Raw Gadget test suite
• GitHub issues

Other potential fixes/improvements to investigate:

• Set ep->maxburst, ep->mult and ep->maxpacket in gadget drivers.
• OTG support.
• Set ep->dev on ep allocation.
• Don't pass ep0_status and ep_status through dev, get from req instead.

License

The parts of code in this repository that are derived from the Linux kernel are covered by GPL-2.0. Everything else is currently covered by Apache-2.0. SPDX-License-Identifier marks the used license in each file.