Hash de interfaz

Este documento describe el hashing 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 están versionadas, lo que significa que una vez que se libera una interfaz, no debe cambiarse, excepto en una interfaz binaria de aplicación (ABI) que conserva la forma (como la corrección de un comentario).

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 .txt actual que enumere todos los archivos de interfaz current.txt 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 publica en Android O ; la siguiente sección se estrenará en Android O MR1 . Recomendamos enfáticamente usar un diseño similar en su archivo current.txt .

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

Cada biblioteca de definición de interfaz generada por hidl-gen incluye hashes, que se pueden recuperar llamando a 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 un hash para la 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 de conservación de 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 versión principal o secundaria de la interfaz.

Estabilidad del ITB

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

Asegurarse de que las interfaces estén versionadas y ABI estable es crucial por varias razones:

• Garantiza que su implementación pueda pasar el Vendor Test Suite (VTS), lo que lo pone en camino para poder hacer OTA solo de 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 las interfaces que se pueden liberar. 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 del paquete.

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