インターフェースのハッシュ化

このドキュメントでは、HIDL インターフェースのハッシュ化について説明します。これは、誤ったインターフェースの変更を防ぎ、インターフェースの変更を徹底して検証するためのメカニズムです。HIDL インターフェースはバージョン管理されているため、このメカニズムは必須です。つまり、インターフェースのリリース後は、アプリケーションバイナリインターフェース（ABI）の維持目的（コメントの修正など）以外には、インターフェースを変更できません。

レイアウト

すべてのパッケージのルートディレクトリ（hardware/interfaces にマッピングされる android.hardware、または vendor/foo/hardware/interfaces にマッピングされる vendor.foo など）には、リリースされたすべての HIDL インターフェースファイルを一覧表示する current.txt ファイルが含まれている必要があります。

# 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

注: どのハッシュがどこから来ているかを追跡しやすくするために、Google は HIDL の current.txt ファイルを別々のセクションに分割しています。最初のセクションは Android O でリリースされ、次のセクションは Android O MR1 でリリースされる予定です。お使いの current.txt ファイルで同様のレイアウトを使用することを強くおすすめします。

hidl-gen を使用したハッシュ化

手動で、または hidl-gen を使用して、ハッシュを current.txt ファイルに追加してください。次のコードスニペットでは、current.txt ファイルを管理するために hidl-gen で使用できるコマンドの例を示します（ハッシュは短縮されています）。

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

警告: 以前にリリースされたインターフェースのハッシュは置き換えないでください。このようなインターフェースを変更する場合は、current.txt ファイルの末尾に新しいハッシュを追加します。詳しくは、ABI の安定性をご覧ください。

hidl-gen で生成されたすべてのインターフェース定義ライブラリには、ハッシュが含まれます。これは、IBase::getHashChain を呼び出すことで取得できます。hidl-gen がインターフェースをコンパイルするときに、HAL パッケージのルートディレクトリにある current.txt ファイルをチェックし、HAL が変更されているかどうかを確認します。

HAL のハッシュが見つからない場合、インターフェースは未リリース（開発中）と見なされ、コンパイルが続行されます。
ハッシュが見つかった場合はチェックされ、現在のインターフェースと照合されます。
- インターフェースがハッシュと一致した場合、コンパイルが続行されます。
- インターフェースがハッシュと一致しない場合、コンパイルは停止されます。これは、以前にリリースされたインターフェースが変更されているためです。
  - ABI を維持するための変更（ABI の安定性を参照）の場合は、コンパイルを続行する前に current.txt ファイルを変更する必要があります。
  - それ以外の変更はすべて、インターフェースのマイナーまたはメジャーバージョンアップグレードで行う必要があります。

ABI の安定性

アプリケーションバイナリインターフェース（ABI）には、バイナリリンケージや呼び出し規約などが含まれます。ABI または API が変更された場合、インターフェースは公式のインターフェースでコンパイルされた一般的な system.img と連携できなくなります。

インターフェースをバージョン管理して ABI を安定させることは、次のいくつかの理由により重要です。

実装がベンダーテストスイート（VTS）に合格して、フレームワークのみの OTA を実行できるようになります。
OEM として、使いやすく、準拠したボードサポートパッケージ（BSP）を提供できます。
どのインターフェースをリリースできるかを追跡するのに役立ちます。current.txt は、パッケージルート内で提供されているすべてのインターフェースの履歴と状態を確認できる、インターフェースディレクトリのマップであると考えてください。

すでに current.txt にエントリがあるインターフェースに新しいハッシュを追加する場合は、ABI の安定性を維持するインターフェースを表すハッシュのみを追加します。以下の変更の種類をご確認ください。

許可されている変更	コメントの変更（メソッドの意味を変更しない場合）。パラメータ名の変更。リターンパラメータ名の変更。アノテーションの変更。
許可されていない変更	引数、メソッドなどの並べ替え。インターフェース名の変更、または新しいパッケージへの移動。パッケージ名の変更。インターフェース内の任意の場所への、メソッドや構造体フィールドなどの追加。 C++ vtable を壊す可能性のあるもの。その他。