Hash de interfaz

Este documento 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 examinen minuciosamente. Este mecanismo es necesario porque las interfaces HIDL tienen versiones, lo que significa que después de que se lanza una interfaz, no se debe cambiar, excepto para preservar la interfaz binaria de aplicación (ABI) (como una corrección de comentarios).

Disposición

Cada directorio raíz de 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 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 ayudar a realizar un seguimiento de qué hashes provienen de dónde, Google separa los archivos HIDL current.txt en diferentes secciones: La primera sección se lanzó en Android O ; La siguiente sección se lanzará en Android O MR1 . Recomendamos encarecidamente utilizar un diseño similar en su archivo current.txt .

Hash con hidl-gen

Puede agregar un hash a un archivo current.txt manualmente o usando hidl-gen . El siguiente fragmento de código proporciona ejemplos de comandos que puede usar con hidl-gen para administrar un archivo current.txt (los hashes se han acortado):

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 reemplace un hash de una interfaz publicada anteriormente. Al cambiar dicha interfaz, agregue un nuevo hash al final del archivo.txt current.txt . Para obtener más información, consulte Estabilidad ABI .

Cada biblioteca de definición de interfaz generada por hidl-gen incluye hashes, que se pueden recuperar llamando IBase::getHashChain . Cuando hidl-gen está compilando una interfaz, verifica el archivo current.txt en el directorio raíz del paquete HAL para ver si se ha cambiado el HAL:

• Si no se encuentra ningún hash para HAL, la interfaz se considera inédita (en desarrollo) y continúa la compilación.
• Si se encuentran hashes, se comparan con la interfaz actual:
  • Si la interfaz coincide con el hash, continúa la compilación.
  • Si la interfaz no coincide con un hash, la compilación se detiene, ya que esto significa que se está cambiando una interfaz publicada anteriormente.
    • Para un cambio que preserve ABI (consulte Estabilidad de ABI ), el archivo current.txt debe modificarse antes de que pueda continuar la compilación.
    • Todos los demás cambios deben realizarse en una actualización de la versión mayor o menor de la interfaz.

Estabilidad ABI

Una interfaz binaria de aplicación (ABI) incluye enlaces binarios/convenciones de llamada/etc. Si la ABI/API cambia, la interfaz ya no funciona con un system.img genérico que se compiló con interfaces oficiales.

Asegurarse de que las interfaces tengan versiones y que ABI sea estable es crucial por varias razones:

• Garantiza que su implementación pueda pasar el Vendor Test Suite (VTS), lo que lo encamina para poder realizar OTA solo en el marco.
• Como OEM, le permite proporcionar un paquete de soporte de placa (BSP) que es fácil de usar y compatible.
• Le ayuda a realizar un seguimiento de qué interfaces se pueden publicar. Considere current.txt como un mapa de un directorio de interfaces que le permite ver el historial y el estado de todas las interfaces que se proporcionan en la raíz de un paquete.

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