Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.
Implement USB HAL
Stay organized with collections
Save and categorize content based on your preferences.
The Android 8.0 release moves handling of USB commands out of init
scripts and into a native USB daemon for better configuration and code
reliability. For the Gadget function configuration, init scripts
(property triggers) are used to perform device-specific gadget operations.
In previous releases, these device-specific configurations were achieved through
device-specific init scripts (using property triggers). Moving to a
Hardware Abstraction Layer (HAL) design results in a much cleaner implementation
that solves these problems:
- Operations such as writes to the kernel sysfs nodes could fail but not be
propagated back to the frameworks code that sets the property trigger. As a
result, frameworks incorrectly assumes the operations have succeeded even though
they have silently failed.
init scripts have a limited number of operations that could be
executed.
The Android 12 release adds USB Gadget HAL support for Network Control
Models (NCM) and API calls that return both the HAL version number and USB speed. For more
information on the API calls available through the USB HAL, see
the android.hardware.usb package summary.
HAL and Treble
The device-specific init scripts were used as a substitution for
HAL layers to perform device-specific USB operations. USB (through ADB) is a
primary interface for debugging system issues. Having a native daemon to perform
USB configuration eliminates the dependency on the framework code so even if the
framework crashes USB should be running.
Under the
Treble
model also introduced in Android 8.0, all of the HALs are isolated from System
services and are required to run in their own native daemons. This eliminates
the requirement to have an exclusive USB daemon as the HAL layer nicely doubles
as a USB daemon.
The default HAL implementation takes care of all pre-Android 8.0 devices. Therefore, there
wouldn't be any device-specific work for the pre-Android 8.0 devices. Android 8.0 uses the HAL
interface to query the status of USB ports and to perform data role and power
role swaps.
Implementation
New USB HAL interface needs to be implemented on every device launching on Android 8.0.
The default implementation should take care of pre-Android 8.0 devices. The default
implementation is sufficient if the device uses the dual_role_usb class to report
type-c port status. Trivial changes might be required in device-specific USB scripts
to transfer ownership of the typc-c nodes to system.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-08-29 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# Implement USB HAL\n\nThe Android 8.0 release moves handling of USB commands out of `init`\nscripts and into a native USB daemon for better configuration and code\nreliability. For the Gadget function configuration, `init` scripts\n(property triggers) are used to perform device-specific gadget operations.\n\nIn previous releases, these device-specific configurations were achieved through\ndevice-specific `init` scripts (using property triggers). Moving to a\nHardware Abstraction Layer (HAL) design results in a much cleaner implementation\nthat solves these problems:\n\n1. Operations such as writes to the kernel sysfs nodes could fail but not be propagated back to the frameworks code that sets the property trigger. As a result, frameworks incorrectly assumes the operations have succeeded even though they have silently failed.\n2. `init` scripts have a limited number of operations that could be executed.\n\nThe Android 12 release adds USB Gadget HAL support for Network Control\nModels (NCM) and API calls that return both the HAL version number and USB speed. For more\ninformation on the API calls available through the USB HAL, see\n[the `android.hardware.usb` package summary](https://developer.android.com/reference/android/hardware/usb/package-summary).\n\nHAL and Treble\n--------------\n\n\nThe device-specific `init` scripts were used as a substitution for\nHAL layers to perform device-specific USB operations. USB (through ADB) is a\nprimary interface for debugging system issues. Having a native daemon to perform\nUSB configuration eliminates the dependency on the framework code so even if the\nframework crashes USB should be running.\n\n\nUnder the\n[Treble](https://android-developers.googleblog.com/2017/05/here-comes-treble-modular-base-for.html)\nmodel also introduced in Android 8.0, all of the HALs are isolated from System\nservices and are required to run in their own native daemons. This eliminates\nthe requirement to have an exclusive USB daemon as the HAL layer nicely doubles\nas a USB daemon.\n\n\nThe default HAL implementation takes care of all pre-Android 8.0 devices. Therefore, there\nwouldn't be any device-specific work for the pre-Android 8.0 devices. Android 8.0 uses the HAL\ninterface to query the status of USB ports and to perform data role and power\nrole swaps.\n\nImplementation\n--------------\n\n\nNew USB HAL interface needs to be implemented on every device launching on Android 8.0.\nThe default implementation should take care of pre-Android 8.0 devices. The default\nimplementation is sufficient if the device uses the `dual_role_usb` class to report\ntype-c port status. Trivial changes might be required in device-specific USB scripts\nto transfer ownership of the typc-c nodes to system."]]
