Hash de interface

Este documento descreve o hash de interface HIDL, um mecanismo para evitar alterações acidentais na interface e assegurar que alterações na interface sejam cuidadosamente examinadas. Esse mecanismo é necessário porque as interfaces HIDL têm controle de versões, o que significa que, após o lançamento, a interface não deve ser alterada, exceto em uma maneira de preservar a interface binária de aplicativo (ABI), como um comentário (correção).

Layout

Cada diretório raiz do pacote (ou seja, android.hardware mapeando para Mapeamento hardware/interfaces ou vendor.foo para vendor/foo/hardware/interfaces) deve conter um 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 monitorar quais hashes vêm de onde o Google separa os arquivos current.txt HIDL em diferentes seções: a primeira seção é Lançado no Android 8. a próxima seção serão lançados no Android 8 MR1. Recomendamos o uso de uma um layout semelhante no seu 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 fornece exemplos de comandos que você pode usar com hidl-gen para gerenciar um Arquivo current.txt (os hashs 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 um lançada anteriormente. Ao mudar essa interface, adicione um novo hash ao final do arquivo current.txt. Para mais 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 um ela verifica o arquivo current.txt no diretório raiz do o pacote da HAL para ver se ela foi modificada:

• Se nenhum hash para a HAL for encontrado, a interface será considerada não lançada (em desenvolvimento) e a compilação prossegue.
• Se forem encontrados hashes, eles serão verificados em relação à interface atual:
  • Se a interface corresponder ao hash, a compilação continua.
  • 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 fazer uma mudança que preserva a ABI (consulte estabilidade ABI), o arquivo current.txt. precisam ser modificados antes que a compilação possa continuar.
    • Todas as demais alterações devem ser feitas em um upgrade de versão principal ou secundária do interface gráfica do usuário.

Estabilidade da ABI

Uma ABI inclui o binário vinculações/convenções de chamada etc. Se a ABI ou a API mudarem, a interface não funciona mais com um system.img genérico que foi compilado com interfaces oficiais.

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

• Ele garante que sua implementação passe no Conjunto de testes de fornecedor (VTS, na sigla em inglês), que ajuda você a fazer OTAs somente no framework.
• Como OEM, ele permite que você forneça um Pacote de suporte à placa (BSP) que seja simples de usar e compatíveis.
• Ele ajuda 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 a uma interface que já tem uma entrada current.txt, adicione apenas os hashes que representam que mantêm a estabilidade da ABI. Confira os seguintes tipos de alterações: