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