Hash de interface

Este documento descreve o hashing da interface HIDL, um mecanismo para evitar alterações acidentais na interface e garantir que as alterações na interface sejam minuciosamente verificadas. Esse mecanismo é necessário porque as interfaces HIDL são versionadas, o que significa que depois que uma interface é lançada ela não deve ser alterada, exceto de maneira preservada pela Application Binary Interface (ABI) (como uma correção de comentário).

Disposição

Cada diretório raiz do pacote (ou seja, mapeamento android.hardware para hardware/interfaces ou mapeamento vendor.foo para vendor/foo/hardware/interfaces ) deve conter um arquivo current.txt que lista todos os arquivos de interface HIDL lançados.

# 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

Observação: para ajudar a controlar quais hashes vêm de onde, o Google separa os arquivos HIDL current.txt em seções diferentes: A primeira seção é lançada no Android O ; a próxima seção será lançada no Android O MR1 . Recomendamos fortemente o uso de um layout semelhante em seu arquivo current.txt .

Hashing com hidl-gen

Você pode adicionar um hash a um arquivo current.txt manualmente ou usando hidl-gen . O trecho de código a seguir fornece exemplos de comandos que você pode usar com hidl-gen para gerenciar um arquivo current.txt (os hashes foram encurtados):

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

Aviso: Não substitua um hash por uma interface lançada anteriormente. Ao alterar essa interface, adicione um novo hash ao final do arquivo current.txt . Para obter detalhes, consulte Estabilidade da ABI .

Cada biblioteca de definição de interface gerada por hidl-gen inclui hashes, que podem ser recuperados chamando IBase::getHashChain . Quando hidl-gen está compilando uma interface, ele verifica o arquivo current.txt no diretório raiz do pacote HAL para ver se o HAL foi alterado:

• Se nenhum hash para o HAL for encontrado, a interface será considerada não lançada (em desenvolvimento) e a compilação continuará.
• Se hashes forem encontrados, eles serão verificados na interface atual:
  • Se a interface corresponder ao hash, a compilação continuará.
  • Se a interface não corresponder a um hash, a compilação será interrompida, pois isso significa que uma interface lançada anteriormente está sendo alterada.
    • Para uma alteração que preserve a ABI (consulte Estabilidade da ABI ), o arquivo current.txt deve ser modificado antes que a compilação possa prosseguir.
    • Todas as outras alterações devem ser feitas em uma atualização de versão secundária ou principal da interface.

Estabilidade da ABI

Uma Interface Binária de Aplicativo (ABI) inclui ligações binárias/convenções de chamada/etc. Se a ABI/API mudar, a interface não funcionará mais com um system.img genérico que foi compilado com interfaces oficiais.

Garantir que as interfaces tenham controle de versão e a ABI estável é crucial por vários motivos:

• Ele garante que sua implementação passe no Vendor Test Suite (VTS), o que o coloca no caminho certo para poder fazer OTAs somente de estrutura.
• Como OEM, ele permite que você forneça um Pacote de Suporte de Placa (BSP) que seja fácil de usar e compatível.
• Isso ajuda você a acompanhar quais interfaces podem ser lançadas. Considere current.txt um mapa de um diretório de interfaces que permite ver o histórico e o estado de todas as interfaces fornecidas em uma raiz de pacote.

Ao adicionar um novo hash para uma interface que já possui uma entrada em current.txt , certifique-se de adicionar apenas os hashes que representam interfaces que mantêm a estabilidade da ABI. Revise os seguintes tipos de alterações: