Hash de la interfaz

En este documento, se describe el hash de la interfaz HIDL, un mecanismo para evitar cambios accidentales en la interfaz y garantizar que los cambios en la interfaz se aprueben rigurosamente. Este mecanismo es necesario porque las interfaces HIDL tienen control de versiones, lo que significa que, tras el lanzamiento de una interfaz, no se debe cambiar, excepto en un cómo preservar la interfaz binaria de la aplicación (ABI) (como un comentario corrección).

Diseño

Cada directorio raíz del paquete (es decir, la asignación de android.hardware al Se asigna hardware/interfaces o vendor.foo a vendor/foo/hardware/interfaces) debe contener un elemento Archivo current.txt que enumera todos los archivos de interfaz HIDL publicados.

# 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

Nota: Para hacer un seguimiento de los hashes que provienen y Google separa los archivos current.txt del HIDL en diferentes secciones: La primera sección es Lanzada en Android 8. la siguiente sección Se lanzará en Android 8 MR1. Te recomendamos que utilices un diseño similar en tu archivo current.txt.

Cómo generar hash con hidl-gen

Puedes agregar un hash a un archivo current.txt de forma manual o mediante usando hidl-gen. El siguiente fragmento de código proporciona ejemplos de comandos que puedes usar con hidl-gen para administrar un current.txt archivo (los hashes se acortaron):

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

Advertencia: No reemplaces un hash por que se lanzó anteriormente. Cuando cambies una interfaz de este tipo, agrega un hash nuevo. al final del archivo current.txt. Para obtener más información, consulta Estabilidad de las ABI.

Todas las bibliotecas de definiciones de interfaces que genera hidl-gen incluye hashes, que se pueden recuperar llamando IBase::getHashChain Cuando hidl-gen compila una esta verifica el archivo current.txt en el directorio raíz de el paquete de HAL para ver si se modificó:

• Si no se encuentra ningún hash para la HAL, la interfaz se considera no publicada (en el desarrollo) y la compilación.
• Si se encuentran hashes, se comparan con la interfaz actual:
  • Si la interfaz coincide con el hash, la compilación continúa.
  • Si la interfaz no coincide con un hash, la compilación se detiene, ya que esto significa que se cambia una interfaz ya publicada.
    • Para un cambio que preserva la ABI (consulta estabilidad de ABI), el archivo current.txt se debe modificar para poder continuar con la compilación.
    • Todos los demás cambios deben realizarse en una actualización de la versión secundaria o principal del interfaz de usuario.

Estabilidad de la ABI

Una ABI incluye el objeto binario de las vinculaciones de llamadas, convenciones de llamadas, etcétera. Si la ABI o la API cambian, la interfaz no ya funciona con un elemento system.img genérico que se compiló con interfaces oficiales.

Asegurarse de que las interfaces tienen control de versiones y ABI estables fundamental por varios motivos:

• Garantiza que la implementación pase el Conjunto de pruebas del proveedor (VTS), que te prepara para que seas capaz de realizar OTA solo en el framework.
• Como OEM, te permite proporcionar un Paquete de compatibilidad para la placa (BSP) que fáciles de usar y cumplir con la normativa.
• Te ayuda a realizar un seguimiento de las interfaces que se pueden lanzar. Reflexiona current.txt: Es un mapa de un directorio de interfaces que te permite ver. el historial y el estado de todas las interfaces que se proporcionan en una raíz del paquete.

Cuando se agrega un hash nuevo para una interfaz que ya tiene una entrada en current.txt, asegúrate de agregar solo los hashes que representan que mantienen la estabilidad de las ABI. Revisa los siguientes tipos de cambios: