Enable the USB Gadget HAL APIs

The USB Gadget Hardware Abstraction Layer (HAL) supports the following system APIs:

  • USB Port Reset API: The USB Port Reset API requires USB Gadget HAL v1.1 and is available for devices running Android 11 or higher. Use it to reset the USB gadget connection with the connected host.
  • USB Bandwidth API: The USB Bandwidth API requires USB Gadget HAL v1.2 and is available for devices running Android 12 or higher. Use it to get the transfer speed between a connected USB device and the host.
  • USB Gadget HAL Version API: The USB Gadget HAL Version API requires USB Gadget HAL v1.2 and is available for devices running Android 12 or higher. Use it to get the USB Gadget HAL version number.

To support the USB Gadget HAL APIs, device manufacturers must implement the corresponding USB Gadget HAL version. To use the USB Gadget HAL APIs, a system privileged app is required.

Find the USB Gadget HAL and its APIs

Device manufacturers must implement USB Gadget HAL to support the corresponding APIs.

  1. To find the default implementation of USB Gadget HAL, use the following paths:
  2. To find the hardware interface header file, use the following paths:
  3. To find the APIs, use the following path to locate the APIs under the AIDL header file. This path is also the Android Framework entry point for the APIs:

Implement the USB Gadget HAL

To support the USB Gadget HAL APIs, you must implement the correct USB Gadget HAL version. No system UI implementation is required.

To implement USB Gadget HAL v1.1 for USB Port Reset API, reset the USB connection between the target device and the host.

Understand the USB Gadget HAL API architecture

The USB Gadget HAL APIs are all built into the android.hardware.usb package and leverage the USB Gadget HAL to interact with the device. Details about each of their specific architectures are in the corresponding tabs, as follows:

USB Bandwidth API

The following figure illustrates the code flow of the USB Bandwidth API, built on top of the USB UDC kernel and accessible through the android.hardware.usb package. The API returns the USB bandwidth through the getCurrentUsbSpeed() and updateUsbSpeed() methods.

USB Bandwidth API

Figure 1.1 Architecture of the USB Bandwidth API

USB Gadget HAL Version API

The following figure illustrates the code flow of the USB Gadget HAL Version API, built on top of the IUSBGadget V1.2 hardware binder and accessible through the android.hardware.usb package.

USB Gadget HAL Version API

Figure 1.2 Architecture of the USB Gadget HAL Version API

USB Port Reset API

The following figure illustrates the code flow of the USB Port Reset API in a framework, including the implementation of the USB Gadget HAL.

USB Reset API

Figure 1.3 Example USB Port Reset API code flow

Validate your implementation

There's a Vendor Test Suite (VTS) test case for each USB Gadget HAL version and its corresponding APIs.

USB Bandwidth and USB Gadget HAL Version APIs

Find the VTS test case for USB Gadget HAL v1.2 at the following path:

<aosp>/test/vts-testcase/hal/usb/gadget/V1_2/

The VTS test case for USB Gadget HAL v1.2 is a host-side test case that lets you perform the following actions:

  • Invoke the USB Gadget HAL Version API using adb shell command (#svc usb getGadgetHalVersion).
  • Invoke the USB Bandwidth API using adb shell command (#svc usb getUsbSpeed).
  • Check the output to confirm that it's the expected value.

USB Port Reset API

Follow this path to find the VTS test case implemented for the USB Port Reset API:

<aosp>/test/vts-testcase/hal/usb/gadget/V1_1/

The VTS test case for USB Port Reset API is a host-side test case that lets you perform the following actions:

  • Invoke the USB Port Reset API using adb shell command (#svc usb resetUsbGadget).
  • Check if the device under test (DUT) can disconnect and reconnect.