Interface hashing

This document describes HIDL interface hashing, a mechanism to prevent accidental interface changes and ensure interface changes are thoroughly vetted. This mechanism is required because HIDL interfaces are versioned, which means that after an interface is released it must not be changed except in an application binary interface (ABI) preserving manner (such as a comment correction).

Layout

Every package root directory (i.e. android.hardware mapping to hardware/interfaces or vendor.foo mapping to vendor/foo/hardware/interfaces) must contain a current.txt file that lists all released HIDL interface files.

# current.txt files support comments starting with a '#' character
# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt

# Each line has a SHA-256 hash followed by the name of an interface.
# They have been shortened in this doc for brevity but they are
# 64 characters in length in an actual current.txt file.
d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types

# Multiple hashes can be in the file for the same interface. This can be used
# to note how ABI sustaining changes were made to the interface.
# For instance, here is another hash for IFoo:

# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"
822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo

Note: To help keep track of which hashes come from where, Google separates HIDL current.txt files into different sections: The first section is Released in Android 8; the next section will be Released in Android 8 MR1. We strongly recommend using a similar layout in your current.txt file.

Hash with hidl-gen

You can add a hash to a current.txt file manually or by using hidl-gen. The following code snippet provides examples of commands you can use with hidl-gen to manage a current.txt file (hashes have been shortened):

hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt

Warning: Do not replace a hash for a previously-released interface. When changing such an interface, add a new hash to the end of the current.txt file. For details, refer to ABI stability.

Every interface definition library generated by hidl-gen includes hashes, which can be retrieved by calling IBase::getHashChain. When hidl-gen is compiling an interface, it checks the current.txt file in the root directory of the HAL package to see if the HAL has been changed:

If no hash for the HAL is found, the interface is considered unreleased (in development) and compilation proceeds.
If hashes are found, they are checked against the current interface:
- If the interface does match the hash, compilation proceeds.
- If the interface does not match a hash, compilation is halted as this means a previously-released interface is being changed.
  - For an ABI-preserving change (see ABI stability), the current.txt file must be modified before compilation can proceed.
  - All other changes should be made in a minor or major version upgrade of the interface.

ABI stability

An ABI includes the binary linkages/calling conventions/etc. If the ABI or API changes, the interface no longer works with a generic system.img that was compiled with official interfaces.

Making sure that interfaces are versioned and ABI stable is crucial for several reasons:

It ensures your implementation can pass the Vendor Test Suite (VTS), which puts you on track to being able to do framework-only OTAs.
As an OEM, it enables you to provide a Board Support Package (BSP) that is straightforward to use and compliant.
It helps you keep track of what interfaces can be released. Consider current.txt a map of an interfaces directory that allows you to see the history and state of all interfaces being provided in a package root.

When adding a new hash for an interface that already has an entry in current.txt, make sure to add only the hashes that represent interfaces which maintain ABI stability. Review the following types of changes:

Changes allowed	Changing a comment (unless this changes the meaning of a method). Changing the name of a parameter. Changing the name of a return parameter. Changing annotations.
Changes not allowed	Reordering arguments, methods, etc. Renaming an interface or moving it to a new package. Renaming a package. Adding a method/struct field/etc. anywhere in the interface. Anything that would break a C++ vtable. etc.