Хеширование интерфейса

В этом документе описывается хеширование интерфейса 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::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 компилирует интерфейс, он проверяет файл current.txt в корневом каталоге пакета HAL, чтобы увидеть, был ли изменен HAL:

• Если хеш-код HAL не найден, интерфейс считается невыпущенным (находящимся в разработке) и компиляция продолжается.
• Если хеши найдены, они проверяются по текущему интерфейсу:
  • Если интерфейс соответствует хешу, компиляция продолжается.
  • Если интерфейс не соответствует хэшу, компиляция останавливается, поскольку это означает, что ранее выпущенный интерфейс изменяется.
    • Для изменения, сохраняющего ABI (см. Стабильность ABI ), файл current.txt необходимо изменить, прежде чем можно будет продолжить компиляцию.
    • Все остальные изменения следует вносить при минорном или мажорном обновлении интерфейса.

Стабильность ABI

ABI включает в себя двоичные связи/соглашения о вызовах и т. д. Если ABI или API изменяются, интерфейс больше не работает с общим system.img , скомпилированным с официальными интерфейсами.

Обеспечение версионности интерфейсов и стабильности ABI имеет решающее значение по нескольким причинам:

• Это гарантирует, что ваша реализация пройдет тест Vendor Test Suite (VTS), что позволит вам выполнять OTA только для платформы.
• Будучи OEM-производителем, вы можете предоставить пакет поддержки плат (BSP), который прост в использовании и соответствует требованиям.
• Это поможет вам отслеживать, какие интерфейсы могут быть выпущены. Рассмотрим current.txt как карту каталога интерфейсов, которая позволяет вам видеть историю и состояние всех интерфейсов, предоставляемых в корне пакета.

При добавлении нового хэша для интерфейса, который уже имеет запись в current.txt , обязательно добавляйте только те хэши, которые представляют интерфейсы, поддерживающие стабильность ABI. Просмотрите следующие типы изменений: