Hash de interfaz

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En este documento, se describe el hash de interfaz HIDL, un mecanismo para evitar cambios accidentales en la interfaz y garantizar que se revisen en detalle. Este mecanismo es necesario porque las interfaces HIDL tienen control de versión, lo que significa que, después de que se lanza una interfaz, no se debe cambiar, excepto de una manera que preserve la interfaz binaria de la aplicación (ABI) (como una corrección de comentarios).

Diseño

Cada directorio raíz del paquete (es decir, la asignación de android.hardware a hardware/interfaces o la asignación de vendor.foo a vendor/foo/hardware/interfaces) debe contener un archivo current.txt que enumere todos los archivos de interfaz HIDL lanzados.

# 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 ayudar a hacer un seguimiento de los hashes que provienen de dónde, Google separa los archivos current.txt de HIDL en diferentes secciones: la primera sección es Lanzada en Android 8 y la siguiente será Lanzada en Android 8 MR1. Te recomendamos que uses un diseño similar en tu archivo current.txt.

Genera un hash con hidl-gen

Puedes agregar un hash a un archivo current.txt de forma manual o con hidl-gen. En el siguiente fragmento de código, se proporcionan ejemplos de comandos que puedes usar con hidl-gen para administrar un archivo current.txt (se acortaron los valores hash):

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 una interfaz que se haya lanzado 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 la ABI.

Cada biblioteca de definición de interfaz que genera hidl-gen incluye hashes, que se pueden recuperar llamando a IBase::getHashChain. Cuando hidl-gen compila una interfaz, verifica el archivo current.txt en el directorio raíz del paquete HAL para ver si se cambió el HAL:

• Si no se encuentra un hash para el HAL, la interfaz se considera sin lanzar (en desarrollo) y se continúa con la compilación.
• Si se encuentran hashes, se comparan con la interfaz actual:
  • Si la interfaz coincide con el hash, se continúa con la compilación.
  • Si la interfaz no coincide con un hash, se detiene la compilación, ya que esto significa que se está cambiando una interfaz lanzada anteriormente.
    • Para realizar un cambio que conserve la ABI (consulta Estabilidad de ABI), se debe modificar el archivo current.txt antes de que se pueda continuar con la compilación.
    • Todos los demás cambios deben realizarse en una actualización de versión secundaria o principal de la interfaz.

Estabilidad de la ABI

Una ABI incluye los vínculos binarios, las convenciones de llamadas, etcétera. Si cambia la ABI o la API, la interfaz ya no funciona con un system.img genérico que se compiló con interfaces oficiales.

Asegurarse de que las interfaces tengan control de versiones y que la ABI sea estable es fundamental por varios motivos:

• Garantiza que tu implementación pueda aprobar el paquete de pruebas del proveedor (VTS), lo que te permite realizar actualizaciones OTA solo de framework.
• Como OEM, te permite proporcionar un paquete de asistencia de la placa (BSP) que sea fácil de usar y cumpla con los requisitos.
• Te ayuda a hacer un seguimiento de qué interfaces se pueden lanzar. Considera current.txt un mapa de un directorio de interfaces que te permite ver el historial y el estado de todas las interfaces que se proporcionan en la raíz de un paquete.

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