В этом документе описывается хеширование интерфейса HIDL — механизм, позволяющий предотвратить случайные изменения интерфейса и обеспечить тщательную проверку изменений интерфейса. Этот механизм необходим, поскольку интерфейсы HIDL имеют версии, а это означает, что после выпуска интерфейса его нельзя изменять, за исключением способа сохранения двоичного интерфейса приложения (ABI) (например, исправления комментариев).
Макет
Каждый корневой каталог пакета (т. е. сопоставление android.hardware
с hardware/interfaces
или сопоставление vendor.foo
с vendor/foo/hardware/interfaces
) должен содержать файл current.txt
, в котором перечислены все выпущенные файлы интерфейса HIDL.
# 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 8 ; следующий раздел будет выпущен в Android 8 MR1 . Мы настоятельно рекомендуем использовать аналогичный макет в файле current.txt
.
Хэш с hidl-gen
Вы можете добавить хеш в файл current.txt
вручную или с помощью hidl-gen
. В следующем фрагменте кода приведены примеры команд, которые можно использовать с hidl-gen
для управления файлом current.txt
(хеши сокращены):
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::typeshidl-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::INfchidl-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::INfcClientCallbackhidl-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
компилирует интерфейс, он проверяет файл current.txt
в корневом каталоге пакета HAL, чтобы увидеть, был ли изменен HAL:
- Если хеш-код HAL не найден, интерфейс считается невыпущенным (находящимся в разработке) и компиляция продолжается.
- Если хеши найдены, они сверяются с текущим интерфейсом:
- Если интерфейс соответствует хешу, компиляция продолжается.
- Если интерфейс не соответствует хэшу, компиляция останавливается, поскольку это означает, что ранее выпущенный интерфейс изменяется.
- Для изменения, сохраняющего ABI (см. Стабильность ABI ), файл
current.txt
необходимо изменить, прежде чем можно будет продолжить компиляцию. - Все остальные изменения следует вносить при минорном или мажорном обновлении интерфейса.
- Для изменения, сохраняющего ABI (см. Стабильность ABI ), файл
Стабильность ABI
ABI включает в себя двоичные связи/соглашения о вызовах и т. д. Если ABI или API изменяются, интерфейс больше не работает с общим system.img
, скомпилированным с официальными интерфейсами.
Обеспечение версионности интерфейсов и стабильности ABI имеет решающее значение по нескольким причинам:
- Это гарантирует, что ваша реализация пройдет тест Vendor Test Suite (VTS), что позволит вам выполнять OTA только для платформы.
- Будучи OEM-производителем, вы можете предоставить пакет поддержки плат (BSP), который прост в использовании и соответствует требованиям.
- Это поможет вам отслеживать, какие интерфейсы могут быть выпущены. Рассмотрим
current.txt
как карту каталога интерфейсов, которая позволяет вам видеть историю и состояние всех интерфейсов, предоставляемых в корне пакета.
При добавлении нового хэша для интерфейса, который уже имеет запись в current.txt
, обязательно добавляйте только те хэши, которые представляют интерфейсы, поддерживающие стабильность ABI. Просмотрите следующие типы изменений:
Изменения разрешены |
|
---|---|
Изменения не разрешены |
|