This lesson starts at a contract and follows it toward an implementation. The next lesson follows the framework service that calls into this kind of boundary. Keeping those views separate helps you avoid treating an interface declaration as proof that hardware works.
Before you start#
Required earlier lessons: Binder: app to system service, Android’s security model, and Find your way around AOSP. You should know that Binder is IPC, that a process has an identity and permissions, and that a source file lives in a versioned repository. Java familiarity helps with the follow-up service lesson but is not required to complete this source-only exercise.
Learning goals#
You will distinguish a HAL contract, its VINTF declaration, service registration, and implementation; explain why AIDL and HIDL both appear in Android trees; and produce a small evidence table that does not claim more than the source or observation shows.
Practice#
Contract before implementation
Why have a HAL at all? The framework needs a stable meaning for an operation while a vendor needs to implement it using a particular chip, firmware, calibration, and driver. Without an explicit boundary, platform updates can depend on private vendor details and vendor changes can require framework rewrites. Treble controls that dependency through supported contracts; it does not turn all hardware into identical devices. The app-facing API also applies user policy and arbitration that should not be implemented independently by every actuator vendor.
At Android 14 tag android-14.0.0_r1, open hardware/interfaces/vibrator/aidl/android/hardware/vibrator/IVibrator.aidl. The short contract excerpt includes getCapabilities(), on(timeoutMs, callback), off(), and perform(effect, strength, callback). AIDL describes typed operations. Generated Binder bindings carry calls between processes; the interface does not specify the vendor’s driver algorithm or guarantee a working actuator.
The same tagged project’s vibrator/aidl/Android.bp defines an aidl_interface with VINTF stability and frozen interface versions (stable AIDL). Build metadata helps generate and validate compatibility artifacts; it is not a runtime status report. A VINTF manifest declares interfaces a device provides; a compatibility matrix describes interfaces expected by a framework or device configuration (VINTF). Neither document is the service implementation.
Older HALs may use HIDL, the earlier HAL interface definition language. HIDL was deprecated as of Android 13 (HAL overview), so newer HALs generally favor stable AIDL, but a real product can include both. Inspect the release and device tree rather than guessing from a directory name. App-facing Android SDK APIs are also different from internal framework/vendor HAL interfaces.
Trace the layers without collapsing them
- App / framework service
- SDK entry, Binder request, platform policy, and arbitration.
- Framework HAL client
- Uses the stable interface contract; not the vendor algorithm.
- Vendor HAL implementation
- Product-specific service and hardware logic; may not be public.
- Kernel driver / actuator
- Device access and physical effect, not established by an AIDL declaration.
For vibration, the conceptual route is:
app API → framework service and policy → framework HAL client
→ vendor HAL implementation → kernel driver → actuator
The framework service is responsible for framework policy and request arbitration; the HAL contract isolates hardware-specific implementation. A declaration, registered service, successful IPC call, and physical effect are four different evidence claims. A generic emulator may simulate vibration or lack a relevant implementation.
Useful read-only observations on a disposable virtual target include:
adb -s SERIAL shell service list
adb -s SERIAL shell dumpsys vibrator_manager
adb -s SERIAL shell lshal
service list lists Binder registrations visible to that caller, which can include AIDL HAL instances as well as framework services; it is not restricted to Java framework objects. dumpsys queries a service's supported diagnostic interface, not every implementation method. At the Android 14 tag, the vibrator framework service is published as vibrator_manager (VibratorManagerService.java, Context.VIBRATOR_MANAGER_SERVICE). That name differs from the HAL instance android.hardware.vibrator.IVibrator/default. lshal is useful for HIDL-era services; its own usage text says it lists HIDL HALs and that AIDL HALs are checked with dumpsys (Lshal.cpp). Empty output is not proof that no HAL exists. Verify source declarations and relevant service configuration; runtime access varies by build. Never turn a missing listing into a reason to flash a replacement.
The next chapter, Inside a HAL service, follows the actual example implementation, its build dependencies, init file, VINTF fragment, registration call, serving thread, and asynchronous callback. Interface evolution then explains how those contracts survive supported updates. This chapter's overview is the map, not the end of the implementation story.
Evidence table (source-only is valid)
Use the pinned interface source if no device is available. If you have a disposable virtual target, you may add observations, but label them as runtime evidence and include the build/image identity.
| Claim | Evidence (file/symbol or observation) | What it establishes | What it cannot establish |
|---|---|---|---|
| The interface offers a timed-on operation | |||
| A device declares the interface | |||
| A service is visible at runtime (if observed) | |||
| Physical vibration works |
Write “not observed” rather than inventing a runtime result. For a source-only exercise, leave runtime and physical rows explicitly unknown.
Knowledge check#
- A device manifest declares a vibrator interface, but a request fails. Give two distinct causes that remain possible.
- Why might
lshalbe empty while an AIDL HAL is present? - Does passing an interface compatibility test prove that a motor physically vibrates with correct timing?
- What does a contract tell a framework client that it does not tell about the hardware internals?
Answers#
- Registration may be absent or the process may have crashed; the version may be incompatible; the implementation may return an error; framework policy may suppress the request. A declaration proves none of these runtime states.
lshalis not a complete inventory of stable AIDL services.- No. Compatibility validates defined contracts in a test configuration; device behavior, timing, driver, and physical hardware require separate evidence.
- It specifies operations and types (and stability/versioning constraints), not the chip-specific algorithm or physical outcome.
Checkpoint#
Pass when the evidence table distinguishes at least declaration from runtime and physical behavior, and the answers identify at least two different layers for a failed request. Revise if a manifest, process listing, or compatibility result is described as proof of hardware health. Not yet evidenced is the correct outcome for any runtime or physical claim not observed.
If the Binder contract is unclear, revisit Binder: app to system service. If you are mixing framework permission with Linux identity, revisit Android’s security model. The next source walkthrough follows the framework-side request path through one service.
Sources#
- Vibrator HAL AIDL, Android 14.0.0_r1 — interface definition.
- Vibrator AIDL
Android.bp, Android 14.0.0_r1 — AIDL module stability/version metadata. - HAL architecture, VINTF, and AIDL — framework/vendor contracts and compatibility concepts.
- Stable AIDL, Android docs — frozen versions under
aidl_api/, matching theversionslist inAndroid.bp. Lshal.cpp, Android 14 tag — usage text: HIDL HALs listed here; AIDL HALs viadumpsys.VibratorManagerService.java, Android 14 tag — publishes thevibrator_managerservice name used in thedumpsyscommand.