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

В этом документе описано хеширование интерфейсов 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 крайне важно по нескольким причинам:

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

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