Android Car Automotive Development - Learn Android Native Services HAL (Hardware Abstraction Layer)

Master Android Native Services HAL (Hardware Abstraction Layer) for Android Car Automotive Development.

Learn to create Android Native Services HAL from scratch, starting with the hardware binder, hardware service manager, HAL server and client, HAL interface creation and building, native HAL service creation based on the HIDL, native HAL service configuration, native HAL service building, native HAL service security, client library and tests for the native service focusing on the newest versions of Android 14 and 15.

This book has a total of 16 main chapters and many subchapters designed to help you master the AOSP Automotive Native Services HAL  from the basics to the interesting and complex details.

Includes a step-by-step guide to setting up the AOSP Car Emulator environment for running the provided example code.

Includes example code that is ready to be run in the AOSP Car Emulator.

A Discord link is included so I can directly assist you with any issues you might encounter.

Chapter Overview

1. The Hardware Binder - hwbinder

hwbinder is Android's dedicated Inter-Process Communication (IPC) mechanism, specifically engineered for optimized communication between the Android framework and Hardware Abstraction Layers (HALs). A cornerstone of Project Treble, hwbinder facilitates stable interfaces, which are typically defined using HIDL (Hardware Interface Definition Language) or Stable AIDL. This distinct, high-performance communication occurs over its own device node, usually hwbinder, keeping it separate from other system binder traffic. Ultimately, hwbinder is crucial for decoupling framework and vendor HAL updates, fostering modularity within the Android ecosystem.

Gain a comprehensive understanding of hwbinder through clear and detailed explanations

2. The Hardware ServiceManager - hwservicemanager

The hwservicemanager (Hardware Service Manager) is Android's dedicated service manager for HALs (Hardware Abstraction Layers) that utilize the hwbinder IPC domain. A fundamental component of Project Treble, it facilitates the stable discovery of hardware interfaces, commonly defined using HIDL. Its primary role is to allow HAL implementations to register their services and Android framework components to subsequently look them up. hwservicemanager specifically manages interfaces for framework-HAL communication, distinct from other service managers in the system. All these service registration and lookup operations occur over the dedicated hwbinder IPC channel, ensuring a clear separation for hardware interactions.

Explore the intricacies of hwservicemanager with straightforward explanations.

3. Hardware Abstraction Layer Server

An Android Hardware Abstraction Layer (HAL) server is a crucial vendor-specific native implementation that provides a standardized interface to underlying device hardware for the Android framework. It implements stable interfaces defined using HIDL, ensuring a reliable contract between the OS and hardware capabilities. Typically developed as a native C++ service or library, a HAL server directly interacts with the specific hardware drivers. For communication with the Android framework, HAL servers exclusively use the hwbinder Inter-Process Communication (IPC) mechanism. To become discoverable by the framework, these HAL servers must register themselves with the hwservicemanager under a unique interface name and instance.

Understand Hardware Abstraction Layer Servers in depth, guided by clear explanations.

4. Hardware Abstraction Layer Client

An Android HAL client is typically an Android framework component designed to access specific device hardware functionalities by interacting with a HAL server. To initiate communication, the client discovers the required HAL service by querying hwservicemanager for a registered interface instance. Once the service is found, the client uses the generated Binder proxy object to make method calls as if the HAL server were a local object. All these interactions between the client and the HAL server are conducted exclusively over the hwbinder Inter-Process Communication (IPC) mechanism. Ultimately, HAL clients operate by consuming the stable interfaces (defined in HIDL) provided by HAL servers, upholding the modularity principles of Project Treble.

Discover everything you need to know about Hardware Abstraction Layer Clients with easy-to-follow explanations.

5. Hardware Abstraction Layer interface - Creation

Hardware Abstraction Layer (HAL) interface creation in Android is fundamental for establishing a stable contract between the Android framework and vendor-specific hardware implementations. This definition process is primarily achieved using either HIDL (Hardware Interface Definition Language) or Stable AIDL, with specifications written in .hal. These languages allow developers to rigorously specify methods, parameters, return values, and custom data types that constitute the hardware interaction API. A critical aspect is mandatory interface versioning (e.g., @1.0, @2.1), which ensures backward compatibility and supports Project Treble's goal of independent OS and vendor updates. Finally, build tools like hidl compiler process these interface definitions to automatically generate the necessary C++ and/or Java stub and proxy code.

This guide uses clear explanations and example code to teach you about HAL interfaces.

6. Hardware Abstraction Layer interface creation - Building

Building a Hardware Abstraction Layer (HAL) interface involves processing its definition files (.hal) using the Android Soong build system configured via script files. You define the HAL interface within script files using either a hidl interface module for HIDL, specifying necessary backends. Specialized build tools, they automatically generate the corresponding C++ and/or Java stub and proxy code from these definitions. This compilation process typically results in an output interface library that both HAL server implementations and client applications will link against. The entire interface generation is integrated into the standard AOSP build.

Learn how HAL interfaces are compiled and generated by the build system, using clear explanations and practical code examples.

7. Creating the HAL service/server - The Header

The HAL service/server header file (.h/.hpp) in Android is crucial for defining the C++ class that provides the hardware-specific implementation of a Hardware Abstraction Layer. This class must inherit from the server-side stub generated by HIDL. Within this header, you will declare the method overrides that provide the concrete logic for the functions specified in the HAL interface definition. Your header and corresponding source file must also include the relevant auto-generated HAL interface headers produced by specialized build tools. This header file is a key component of your HAL service module, which is compiled via its build script definition to interact with the device hardware.

Master the creation of native service HAL headers through clear, step-by-step explanations and accompanying example code

8. Creating the HAL service/server - The Source Files

The HAL service/server source file (.cpp) is where you implement the core C++ logic for your Hardware Abstraction Layer, translating abstract interface calls into concrete hardware actions. This file must include your service's own header file along with any necessary auto-generated HIDL interface headers. Within this source, developers define the concrete implementations for all methods specified in the HAL interface, providing the actual hardware control. This is the layer responsible for direct interaction with underlying hardware drivers or a hardware abstraction library. Often, the source file also includes the essential logic for registering the HAL service with hwservicemanager or contains the main function for a standalone HAL daemon.

Grasp the structure and logic of native service HAL source files using clear explanations and supportive code examples

9. Creating the HAL service/server -  Manifest and Compatibility Matrix

For low-level Android Native Services HAL, declaration typically occurs in a device-specific VINTF manifest file, not the standard AndroidManifest.xml. This manifest precisely details the interface versions and instance names the device component provides. Concurrently, the Android framework specifies its dependencies in a Framework Compatibility Matrix (FCM). A critical VINTF compatibility check validates the device manifest against the framework matrix before the system boots. This mechanism is fundamental to ensure stability and interoperability, particularly for devices supporting Project Treble, allowing independent framework and vendor updates.

Discover the intricacies of setting up HAL manifests and compatibility matrices, with the help of straightforward explanations and hands-on example code

10. Creating the HAL service/server - Service Startup

Android Native Services HAL, such as system daemons, are typically launched by the core Android process during the boot sequence. Configuration and startup logic reside within script files. Within these scripts, each native executable is defined using a specific keyword stanza, specifying its binary path and properties. Various service options configure its execution context, including user/group IDs, process class, and SELinux labels. Services are then usually started automatically based on triggers defined in the script files.

Learn how to configure a native service HAL to launch automatically at Android startup and be available system-wide, using step-by-step explanations and code examples.

11. Creating the HAL service/server - Building the Service

To build a Hardware Abstraction Layer (HAL) service/server, you primarily use the Android Soong build system, configuring it through script files. Your HAL implementation is defined as a Soong module, typically a shared library or a binary, often with specific properties to ensure installation to the vendor partition. Within this module definition, you must specify your C++ source files and link against all necessary dependencies, including the generated HAL interface library and key system libraries. The actual HAL compilation is initiated using standard AOSP build commands. This process generates the final output, which is typically placed in the device's vendor partition.

Learn how to compile and link native service HAL implementations using clear explanations and practical code examples

12. Creating the HAL service/server - SElinux

A robust HAL SELinux policy is crucial for securing Android Hardware Abstraction Layer (HAL) services/servers by enforcing Mandatory Access Control. You must define unique SELinux types and process contexts for your service within Type Enforcement policy files. Proper labeling is key, assigning the execution type and the hwbinder context. Specific access permissions are explicitly granted by writing details. Precise SELinux allow rules are written to grant the HAL domain necessary permissions for hardware driver access and hwbinder communication.

Find comprehensive coverage of the required SELinux configurations for Native Services HAL within this book, presented with clear explanations and hands-on examples.

13. Creating a Client Library for the Native Service HAL - The Header

The header file for a Hardware Abstraction Layer (HAL) client library is meticulously designed to define the public C++ API that Android framework components use to interact with specific hardware. It must include the specific HIDL generated interface header corresponding to the target HAL service. Methods declared within this client header are implemented to facilitate Inter-Process Communication (IPC) calls over the hwbinder domain, typically by utilizing proxy objects. The overarching purpose of such a header and its accompanying library is to abstract and simplify hardware interaction for the Android framework, promoting modularity.

Explore header file design for native HAL clients, guided by clear explanations and illustrative code examples.

14. Creating a Client Library for the Native Service HAL - The Source Files

The HAL client library source file (.cpp) is where the C++ implementation of the public client API—defined in its corresponding header—resides, enabling Android framework components to interact with hardware. This file must include its own API header as well as relevant HIDL generated headers. A core responsibility of this source code is discovering the target HAL service via hwservicemanager and then creating the specific Binder proxy object. The public methods implemented here will then execute hwbinder Inter-Process Communication (IPC) calls to the remote HAL server using this proxy.

Learn to write the C++ source files for native HAL clients, detailing their interaction with HAL services, using clear explanations and accompanying code examples.

15. Creating a Client Library for the Native Service HAL - Building

To build a Hardware Abstraction Layer (HAL) client library, you utilize the Android Soong build system, configuring it through script files. Your client library is defined as a library module (typically shared for framework use) within a script file. This definition must specify the C++ source files and correctly link against all necessary dependencies, critically including the generated HAL interface library for the target hardware and system libraries. For the framework to use this library, you must also export the library's public API headers using Soong properties. The final step is to compile the HAL client library using standard AOSP build commands , which produces the linkable shared object or static archive.

Master the process of building client libraries by learning how to write the necessary build scripts through clear examples and step-by-step instructions.

16. Testing the Native Service HAL and Client Library using Test Binaries

Test your Android Hardware Abstraction Layer (HAL) service and its accompanying client library robustly using dedicated native HAL test binaries. These tests are defined in script files utilizing the Soong modules, commonly incorporating the framework for effective test case organization and assertions. The test binary critically links against the HAL client library, thereby simulating how Android framework components would interact with the HAL. During execution, the test binary communicates with the live HAL service instance over hwbinder, typically after discovering it via hwservicemanager. This entire process allows you to thoroughly verify the HAL client library's API and validate the integrity of end-to-end hwbinder communication with the hardware implementation.

Discover how to properly test native service HALs and client library implementations with the help of clear explanations and examples.