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

В этом документе описывается хеширование интерфейса 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 O» ; следующий раздел будет выпущен в Android O 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. Просмотрите следующие типы изменений: