Hash da interface

Este documento descreve o hash da interface HIDL, um mecanismo para evitar mudanças acidentais na interface e garantir que elas sejam analisadas minuciosamente. Esse mecanismo é necessário porque as interfaces HIDL são versionadas, o que significa que, depois que uma interface é lançada, ela não pode ser alterada, exceto de uma maneira que preserve a interface binária do aplicativo (ABI, na sigla em inglês), como uma correção de comentário.

Layout

Todos os diretórios raiz do pacote (por exemplo, mapeamento android.hardware para hardware/interfaces ou mapeamento vendor.foo para vendor/foo/hardware/interfaces) precisam conter um arquivo current.txt que liste 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 acompanhar de onde vêm os hashes, o Google separa os arquivos current.txt da HIDL em diferentes seções: a primeira é Lançada no Android 8, e a próxima será Lançada no Android 8 MR1. Recomendamos o uso de um layout semelhante no arquivo current.txt.

Hash com hidl-gen

É possível adicionar um hash a um arquivo current.txt manualmente ou usando hidl-gen. O snippet de código a seguir mostra exemplos de comandos que podem ser usados 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 de uma interface lançada anteriormente. Ao mudar essa interface, adicione um novo hash ao final do arquivo current.txt. Para mais detalhes, consulte Estabilidade da ABI.

Todas as bibliotecas de definição de interface geradas por hidl-gen incluem hashes, que podem ser recuperados chamando IBase::getHashChain. Quando o hidl-gen está compilando uma interface, ele verifica o arquivo current.txt no diretório raiz do pacote HAL para saber 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 será realizada.
• Se hashes forem encontrados, eles serão verificados na interface atual:
  • Se a interface corresponder ao hash, a compilação vai continuar.
  • Se a interface não corresponder a um hash, a compilação será interrompida, porque isso significa que uma interface lançada anteriormente está sendo alterada.
    • Para uma mudança que preserva a ABI (consulte Estabilidade da ABI), o arquivo current.txt precisa ser modificado antes que a compilação possa continuar.
    • Todas as outras mudanças precisam ser feitas em um upgrade de versão secundária ou principal da interface.

Estabilidade da ABI

Uma ABI inclui os links binários/convenções de chamada/etc. Se a ABI ou a API mudar, a interface não vai mais funcionar com um system.img genérico compilado com interfaces oficiais.

Verificar se as interfaces têm uma versão e se a ABI é estável é crucial por vários motivos:

• Isso garante que sua implementação possa passar no conjunto de testes do fornecedor (VTS, na sigla em inglês), o que coloca você no caminho certo para fazer OTAs somente de framework.
• Como OEM, ele permite que você forneça um pacote de suporte à placa (BSP) que seja simples de usar e compatível.
• Ele ajuda a acompanhar quais interfaces podem ser liberadas. Considere current.txt um mapa de um diretório de interfaces que permite conferir o histórico e o estado de todas as interfaces fornecidas na raiz de um pacote.

Ao adicionar um novo hash para uma interface que já tem uma entrada em current.txt, adicione apenas os hashes que representam as interfaces que mantêm a estabilidade da ABI. Analise os seguintes tipos de mudanças: