1# USB
2
3`services/device/usb` abstracts [Universal Serial Bus](https://en.wikipedia.org/wiki/USB)
4concepts across multiple platforms.
5
6Clients should use the [public Mojo interface](../public/mojom).
7
8
9## USB ID Repository
10
11`/third_party/usb_ids/usb.ids` is imported regularly to provide human-readable
12descriptions of USB devices.
13
14
15## Ongoing Work transitioning away from `libusb`
16
17`UsbService` is implemented by `UsbServiceImpl` based on `third_party/libusb`.
18
19Work is ongoing to implement each platform directly, without using `libusb`.
20
21*   `UsbServiceAndroid` done.
22*   `UsbServiceLinux` done.
23*   macOS not started.
24*   `UsbServiceWin` in progress. Enable via `chrome://flags/#new-usb-backend`
25
26
27## Testing
28
29### Unit Tests
30
31Standard use of `*_unittest.cc` files for must code coverage.
32
33
34### Fuzzers
35
36[libFuzzer] tests are in `*_fuzzer.cc` files. They test for bad input from
37devices, e.g. when parsing device descriptors during device enumeration.
38
39[libFuzzer]: /testing/libfuzzer/README.md
40
41
42### Gadget Tests
43
44[USB/HID API Testing with Gadgets] describes a framework for testing the Chrome
45USB, HID and serial device APIs with real devices on generally accessible
46hardware.
47
48[USB/HID API Testing with Gadgets]: https://docs.google.com/document/d/1O9jTlOAyeCwZX_XRbmQmNFidcJo8QZQSaodP-wmyess
49
50Unit tests using the gadget can be run manually with a hardware "gadget". These
51unit tests all call [UsbTestGadget::Claim].
52
53[UsbTestGadget::Claim]: https://cs.chromium.org/search/?q=UsbTestGadget::Claim&type=cs
54
55
56### Manual Testing
57
58When making changes to platform-specific code the following manual test steps
59should be run to augment automated testing, which is mostly limited to
60platform-independent logic. These tests require an Android phone with USB
61debugging enabled and support for USB tethering. When USB debugging is enabled
62the device creates a vendor-specific interface for the ADB protocol. On
63Windows, with the [OEM USB drivers] installed this interface will have the
64WinUSB.sys driver loaded. When USB tethering is enabled the device creates
65an RNDIS interface for which most operating systems have a built-in driver.
66With both of these features enabled the device will have two interfaces and
67thus be a "composite" device. This is important for testing on Windows as
68composite and non-composite devices must be handled differently.
69
70[OEM USB drivers]: https://developer.android.com/studio/run/oem-usb
71
72#### Steps
73
741.  [Enable USB debugging] and check that the **USB tethering** option is
75    disabled under **Network & Internet > Hotspot & Tethering** in the
76    phone's setting app.
772.  Connect phone to the system under test.
783.  Launch Chrome.
794.  Load `chrome://usb-internals`.
805.  Select the **Devices** tab.
816.  Find the phone in the list. Ensure that the **Manufacturer name**,
82    **Product name** and **Serial number** columns are all populated for this
83    device.
847.  Click the **Inspect** button next to this device.
858.  Click the **Get Device Descriptor** button at the bottom of the page.
869.  Click the **GET** buttons next to **Manufacturer String**,
87    **Product String** and **Serial number** fields.
8810. Check that the values which appear match the ones seen previously.
8911. Load `chrome://inspect` and ensure that the **Discover USB devices**
90    option is checked.
9112. Check that the phone appears as an available device. It may appear as
92    "Offline" until the **Allow** button is tapped on the "Allow USB debugging"
93    prompt which appears on the device. It may take some time for the device to
94    appear.
9513. Launch Chrome on the phone and ensure that the tabs open on the phone are
96    available for inspection.
9714. Enable USB tethering on the phone and repeat steps 4 through 13. This will
98    test hotplugging of a composite device as enabling USB tethering causes
99    the device to reconnect with multiple interfaces.
10015. Disable USB tethering on the phone and repeat steps 4 through 13. This will
101    test hotplugging of a non-composite device as disabling USB tethering
102    causes the device to reconnect with a single interface.
10316. Close Chrome and re-enable USB tethering on the phone.
10417. Repeat steps 3 through 13 for a final time. This will test enumeration of a
105    composite device on Chrome launch.
106
107[Enable USB debugging]: https://developer.android.com/studio/debug/dev-options#enable