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

В этом документе описывается хеширование интерфейса 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/API интерфейс больше не работает с общим system.img , скомпилированным с официальными интерфейсами.

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

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

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