tree: 54c4eaf6680203ad66d7b86b66591cb4e1935321 [path history] [tgz]
  1. BUILD.gn
  2. DEPS
  3. DIR_METADATA
  4. OWNERS
  5. README.md
  6. android/
  7. fake_usb_device_handle.cc
  8. fake_usb_device_handle.h
  9. fuzz_corpus/
  10. mock_usb_device.cc
  11. mock_usb_device.h
  12. mock_usb_device_handle.cc
  13. mock_usb_device_handle.h
  14. mock_usb_service.cc
  15. mock_usb_service.h
  16. mojo/
  17. scoped_libusb_device_handle.cc
  18. scoped_libusb_device_handle.h
  19. scoped_libusb_device_ref.cc
  20. scoped_libusb_device_ref.h
  21. scoped_winusb_handle.cc
  22. scoped_winusb_handle.h
  23. usb_configuration_android.cc
  24. usb_configuration_android.h
  25. usb_context.cc
  26. usb_context.h
  27. usb_context_unittest.cc
  28. usb_descriptors.cc
  29. usb_descriptors.h
  30. usb_descriptors_fuzzer.cc
  31. usb_descriptors_unittest.cc
  32. usb_device.cc
  33. usb_device.h
  34. usb_device_android.cc
  35. usb_device_android.h
  36. usb_device_handle.cc
  37. usb_device_handle.h
  38. usb_device_handle_android.cc
  39. usb_device_handle_android.h
  40. usb_device_handle_impl.cc
  41. usb_device_handle_impl.h
  42. usb_device_handle_mac.cc
  43. usb_device_handle_mac.h
  44. usb_device_handle_unittest.cc
  45. usb_device_handle_usbfs.cc
  46. usb_device_handle_usbfs.h
  47. usb_device_handle_win.cc
  48. usb_device_handle_win.h
  49. usb_device_impl.cc
  50. usb_device_impl.h
  51. usb_device_linux.cc
  52. usb_device_linux.h
  53. usb_device_mac.cc
  54. usb_device_mac.h
  55. usb_device_win.cc
  56. usb_device_win.h
  57. usb_endpoint_android.cc
  58. usb_endpoint_android.h
  59. usb_error.cc
  60. usb_error.h
  61. usb_interface_android.cc
  62. usb_interface_android.h
  63. usb_service.cc
  64. usb_service.h
  65. usb_service_android.cc
  66. usb_service_android.h
  67. usb_service_impl.cc
  68. usb_service_impl.h
  69. usb_service_linux.cc
  70. usb_service_linux.h
  71. usb_service_mac.cc
  72. usb_service_mac.h
  73. usb_service_unittest.cc
  74. usb_service_win.cc
  75. usb_service_win.h
  76. usb_string_read_fuzzer.cc
  77. webusb_descriptors.cc
  78. webusb_descriptors.h
  79. webusb_descriptors_fuzzer.cc
  80. webusb_descriptors_unittest.cc
services/device/usb/README.md

USB

services/device/usb abstracts Universal Serial Bus concepts across multiple platforms.

Clients should use the public Mojo interface.

USB ID Repository

/third_party/usb_ids/usb.ids is imported regularly to provide human-readable descriptions of USB devices.

Ongoing Work transitioning away from libusb

UsbService is implemented by UsbServiceImpl based on third_party/libusb.

Work is ongoing to implement each platform directly, without using libusb.

  • UsbServiceAndroid done.
  • UsbServiceLinux done.
  • macOS not started.
  • UsbServiceWin in progress. Enable via chrome://flags/#new-usb-backend

Testing

Unit Tests

Standard use of *_unittest.cc files for must code coverage.

Fuzzers

libFuzzer tests are in *_fuzzer.cc files. They test for bad input from devices, e.g. when parsing device descriptors during device enumeration.

Gadget Tests

USB/HID API Testing with Gadgets describes a framework for testing the Chrome USB, HID and serial device APIs with real devices on generally accessible hardware.

Unit tests using the gadget can be run manually with a hardware “gadget”. These unit tests all call UsbTestGadget::Claim.

Manual Testing

When making changes to platform-specific code the following manual test steps should be run to augment automated testing, which is mostly limited to platform-independent logic. These tests require an Android phone with USB debugging enabled and support for USB tethering. When USB debugging is enabled the device creates a vendor-specific interface for the ADB protocol. On Windows, with the OEM USB drivers installed this interface will have the WinUSB.sys driver loaded. When USB tethering is enabled the device creates an RNDIS interface for which most operating systems have a built-in driver. With both of these features enabled the device will have two interfaces and thus be a “composite” device. This is important for testing on Windows as composite and non-composite devices must be handled differently.

Steps

  1. Enable USB debugging and check that the USB tethering option is disabled under Network & Internet > Hotspot & Tethering in the phone's setting app.
  2. Connect phone to the system under test.
  3. Launch Chrome.
  4. Load chrome://usb-internals.
  5. Select the Devices tab.
  6. Find the phone in the list. Ensure that the Manufacturer name, Product name and Serial number columns are all populated for this device.
  7. Click the Inspect button next to this device.
  8. Click the Get Device Descriptor button at the bottom of the page.
  9. Click the GET buttons next to Manufacturer String, Product String and Serial number fields.
  10. Check that the values which appear match the ones seen previously.
  11. Load chrome://inspect and ensure that the Discover USB devices option is checked.
  12. Check that the phone appears as an available device. It may appear as “Offline” until the Allow button is tapped on the “Allow USB debugging” prompt which appears on the device. It may take some time for the device to appear.
  13. Launch Chrome on the phone and ensure that the tabs open on the phone are available for inspection.
  14. Enable USB tethering on the phone and repeat steps 4 through 13. This will test hotplugging of a composite device as enabling USB tethering causes the device to reconnect with multiple interfaces.
  15. Disable USB tethering on the phone and repeat steps 4 through 13. This will test hotplugging of a non-composite device as disabling USB tethering causes the device to reconnect with a single interface.
  16. Close Chrome and re-enable USB tethering on the phone.
  17. Repeat steps 3 through 13 for a final time. This will test enumeration of a composite device on Chrome launch.