Interfaces y Paquetes

HIDL se basa en interfaces, un tipo abstracto utilizado en lenguajes orientados a objetos para definir comportamientos. Cada interfaz es parte de un paquete.

Paquetes

Los nombres de los paquetes pueden tener subniveles como package.subpackage . El directorio raíz de los paquetes HIDL publicados es hardware/interfaces o vendor/vendorName (por ejemplo, vendor/google para dispositivos Pixel). El nombre del paquete forma uno o más subdirectorios en el directorio raíz; Todos los archivos que definen un paquete están en el mismo directorio. Por ejemplo, package android.hardware.example.extension.light@2.0 se puede encontrar en hardware/interfaces/example/extension/light/2.0 .

La siguiente tabla enumera los prefijos y ubicaciones de los paquetes:

El directorio del paquete contiene archivos con extensión .hal . Cada archivo debe contener una declaración package que nombre el paquete y la versión de la que forma parte el archivo. El archivo types.hal , si está presente, no define una interfaz, sino que define tipos de datos accesibles para todas las interfaces del paquete.

Definición de interfaz

Aparte de types.hal , todos los demás archivos .hal definen una interfaz. Una interfaz normalmente se define de la siguiente manera:

interface IBar extends IFoo { // IFoo is another interface
    // embedded types
    struct MyStruct {/*...*/};

    // interface methods
    create(int32_t id) generates (MyStruct s);
    close();
};

Una interfaz sin una declaración extends explícita se extiende implícitamente desde android.hidl.base@1.0::IBase (similar a java.lang.Object en Java). La interfaz IBase, implícitamente importada, declara varios métodos reservados que no deben ni pueden volver a declararse. en interfaces definidas por el usuario o utilizados de otra manera. Estos métodos incluyen:

• ping
• interfaceChain
• interfaceDescriptor
• notifySyspropsChanged
• linkToDeath
• unlinkToDeath
• setHALInstrumentation
• getDebugInfo
• debug
• getHashChain

Importador

La declaración import es un mecanismo HIDL para acceder a interfaces y tipos de paquetes en otro paquete. Una declaración import se refiere a dos entidades:

• La entidad importadora , que puede ser un paquete o una interfaz; y
• La entidad importada , que también puede ser un paquete o una interfaz.

La entidad importadora está determinada por la ubicación de la declaración import . Cuando la declaración está dentro del types.hal de un paquete, lo que se está importando es visible para todo el paquete; esta es una importación a nivel de paquete . Cuando la declaración está dentro de un archivo de interfaz, la entidad importadora es la interfaz misma; esta es una importación a nivel de interfaz .

La entidad importada está determinada por el valor después de la palabra clave import . No es necesario que el valor sea un nombre completo; si se omite un componente, se completa automáticamente con información del paquete actual. Para valores totalmente calificados, se admiten los siguientes casos de importación:

• Importaciones de paquetes completos . Si el valor es un nombre de paquete y una versión (la sintaxis se describe a continuación), entonces se importa todo el paquete a la entidad importadora.
• Importaciones parciales . Si el valor es:
  • Una interfaz, los types.hal del paquete.hal y esa interfaz se importan a la entidad importadora.
  • Un UDT definido en types.hal , entonces solo ese UDT se importa a la entidad importadora (otros tipos en types.hal no se importan).
• Importaciones de solo tipos . Si el valor utiliza la sintaxis de una importación parcial descrita anteriormente, pero con la palabra clave types en lugar de un nombre de interfaz, solo se importan los UDT en types.hal del paquete designado.

La entidad importadora obtiene acceso a una combinación de:

• Los UDT comunes del paquete importado definidos en types.hal ;
• Las interfaces del paquete importado (para una importación de paquete completo) o la interfaz especificada (para una importación parcial) con el fin de invocarlas, pasarles identificadores y/o heredar de ellas.

La declaración de importación utiliza la sintaxis de nombre de tipo completo para proporcionar el nombre y la versión del paquete o interfaz que se está importando:

import android.hardware.nfc@1.0;            // import a whole package
import android.hardware.example@1.0::IQuux; // import an interface and types.hal
import android.hardware.example@1.0::types; // import just types.hal

Herencia de interfaz

Una interfaz puede ser una extensión de una interfaz previamente definida. Las extensiones pueden ser de uno de los tres tipos siguientes:

• Una interfaz puede añadir funcionalidad a otra, incorporando su API sin cambios.
• Un paquete puede agregar funcionalidad a otro, incorporando su API sin cambios.
• La interfaz puede importar tipos desde un paquete o desde una interfaz específica.

Una interfaz sólo puede extender a otra interfaz (sin herencia múltiple). Cada interfaz en un paquete con un número de versión menor distinto de cero debe extender una interfaz en la versión anterior del paquete. Por ejemplo, si una interfaz IBar en la versión 4.0 del paquete derivative se basa en (extiende) una interfaz IFoo en la versión 1.2 del paquete original y se crea una versión 1.3 del paquete original , la versión 4.1 IBar no puede extender la versión 1.3 de IFoo . En cambio, la versión 4.1 IBar debe extender la versión 4.0 IBar , que está vinculada a la versión 1.2 IFoo . La versión 5.0 IBar podría ampliar la versión 1.3 IFoo , si se desea.

Las extensiones de interfaz no implican dependencia de la biblioteca ni inclusión cruzada de HAL en el código generado; simplemente importan la estructura de datos y las definiciones de métodos en el nivel HIDL. Cada método en un HAL debe implementarse en ese HAL.

Extensiones de proveedores

En algunos casos, las extensiones de los proveedores se implementarán como una subclase del objeto base que representa la interfaz principal que extienden. El mismo objeto se registrará con el nombre y la versión de HAL base y con el nombre y la versión de HAL de la extensión (proveedor).

Versionado

Los paquetes tienen versiones y las interfaces tienen la versión de su paquete. Las versiones se expresan en dos números enteros, mayor . menor .

• Las versiones principales no son compatibles con versiones anteriores. Al incrementar el número de la versión principal, el número de la versión secundaria se restablece a 0.
• Las versiones menores son compatibles con versiones anteriores. Incrementar el número menor indica que la versión más nueva es totalmente compatible con la versión anterior. Se pueden agregar nuevas estructuras de datos y métodos, pero no se pueden cambiar estructuras de datos ni firmas de métodos existentes.

Pueden estar presentes varias versiones principales o secundarias de un HAL en un dispositivo simultáneamente. Sin embargo, se debe preferir una versión secundaria a una versión principal porque el código de cliente que funciona con una interfaz de versión secundaria anterior también funcionará con versiones menores posteriores de esa misma interfaz. Para obtener más detalles sobre el control de versiones y las extensiones de proveedores, consulte Control de versiones HIDL .

Resumen del diseño de la interfaz

Esta sección resume cómo administrar un paquete de interfaz HIDL (como hardware/interfaces ) y consolida la información presentada en toda la sección HIDL. Antes de leer, asegúrese de estar familiarizado con el control de versiones HIDL , los conceptos de hash en Hashing con hidl-gen , los detalles del trabajo con HIDL en general y las siguientes definiciones:

Para obtener más definiciones, consulte Terminología HIDL.

Cada archivo se puede encontrar en el mapeo raíz del paquete y su nombre completo

Las raíces del paquete se especifican en hidl-gen como el argumento -r android.hardware:hardware/interfaces . Por ejemplo, si el paquete es vendor.awesome.foo@1.0::IFoo y se envía hidl-gen -r vendor.awesome:some/device/independent/path/interfaces , entonces el archivo de interfaz debe estar ubicado en $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal .

En la práctica, se recomienda que un proveedor u OEM llamado awesome coloque sus interfaces estándar en vendor.awesome . Una vez seleccionada la ruta de un paquete, no se debe cambiar, ya que está integrada en la ABI de la interfaz.

El mapeo de ruta del paquete debe ser único

Por ejemplo, si tiene -rsome.package:$PATH_A y -rsome.package:$PATH_B , $PATH_A debe ser igual a $PATH_B para un directorio de interfaz consistente (esto también facilita mucho el control de versiones de las interfaces ).

La raíz del paquete debe tener un archivo de versiones

Si crea una ruta de paquete como -r vendor.awesome:vendor/awesome/interfaces , también debe crear el archivo $ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt , que debe contener hashes de interfaces creadas con -Lhash opción en hidl-gen (esto se analiza ampliamente en Hashing con hidl-gen ).

Las interfaces van en ubicaciones independientes del dispositivo

En la práctica, se recomienda compartir interfaces entre sucursales. Esto permite la máxima reutilización del código y la máxima prueba del código en diferentes dispositivos y casos de uso.