Hashing de interface

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

Esquema

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 liberados.

# 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 quais hashes vêm de onde, o Google separa os arquivos HIDL current.txt em diferentes seções: A primeira seção é lançada no Android O ; a próxima seção será lançada no Android O MR1 . É altamente recomendável usar 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 a 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 é considerada inédita (em desenvolvimento) e a compilação prossegue.
  • Se os hashes forem encontrados, eles serão verificados na interface atual:
    • Se a interface corresponder ao hash, a compilação prossegue.
    • 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 preserva 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 ABI

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

Certificar-se de que as interfaces sejam versionadas e a ABI estável é crucial por vários motivos:

  • Ele garante que sua implementação possa passar no Vendor Test Suite (VTS), que o coloca no caminho certo para poder fazer OTAs somente de estrutura.
  • Como OEM, ele permite que você forneça um Board Support Package (BSP) fácil de usar e compatível.
  • Ele 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:

Alterações permitidas
  • Alterar um comentário (a menos que isso altere o significado de um método).
  • Alterando o nome de um parâmetro.
  • Alterando o nome de um parâmetro de retorno.
  • Alterando anotações.
Alterações não permitidas
  • Reordenando argumentos, métodos, etc…
  • Renomear uma interface ou movê-la para um novo pacote.
  • Renomeando um pacote.
  • Adicionando um método/campo de estrutura/etc… em qualquer lugar da interface.
  • Qualquer coisa que quebraria uma vtable C++.
  • etc.