Capa de abstracción de la plataforma de HAR

Usa el renderizador de alta disponibilidad (HAR) para mostrar la información del vehículo que Android no puede mostrar. Esto puede ocurrir debido a problemas como el inicio, la disponibilidad, la seguridad o las reglamentaciones. HAR es una app integrada y portátil escrita en Rust.

El HAR, también llamado framework de HAR, incluye el código que usas para compilar apps. Una app compilada con HAR es una app basada en HAR. El framework de HAR tiene secciones de código para diferentes plataformas. Por ejemplo, en un sistema Linux, usas bibliotecas como tinyalsa para los sonidos. QNX tiene sus propias bibliotecas de audio únicas.

Una plataforma incluye hardware, un sistema operativo, bibliotecas del sistema y otros factores. El código específico de la plataforma tiene partes llamadas subsistemas. Cada subsistema controla una función de la plataforma, como el audio, las cámaras de EVS o los datos del vehículo. Para admitir una plataforma, el framework de HAR necesita que se implementen todos sus subsistemas.

El código del subsistema específico de la plataforma puede ejecutarse en el mismo proceso que la app basada en HAR o en uno independiente. Cuando está separado, este código controla la comunicación entre procesos (IPC) para ayudar a verificar que la plataforma admita la app. Los mecanismos de IPC complejos deben formar parte del código específico de la plataforma.

El paquete de pruebas de HAR ejecuta pruebas en todos los subsistemas implementados para una plataforma. Usa este paquete para verificar si las plataformas cumplen con los requisitos de HAR y para encontrar problemas nuevos.

Terminología

Estos términos se encuentran en esta página:

App basada en HAR
Es una app de OEM o específica de una función que se compila con el framework de HAR. Las apps se diferencian por el estado de la app y otros aspectos personalizables.
Framework de HAR
Proporciona un conjunto básico de herramientas que se usan para compilar apps.
Abstracción de la plataforma de HAR
Es parte del framework de HAR que proporciona una API conocida que deben implementar todas las plataformas de destino.
Paquete de pruebas de HAR
Una serie de pruebas conocidas sobre las implementaciones de la plataforma, que ayudan a verificar que las implementaciones de la plataforma admitan el framework de HAR en una plataforma determinada.

Fuera de alcance

El HAR no aborda lo siguiente:

  • Implementaciones individuales para todos los destinos de la plataforma: Implementaciones para las plataformas de destino. En su lugar, en esta página, se describen las interfaces que deben cumplir las implementaciones de la plataforma y que debe satisfacer un paquete de pruebas.

  • Casos de prueba: Casos de prueba específicos para todas las interfaces. En su lugar, en esta página, se describen las funciones individuales de las interfaces, incluidos los argumentos, los valores que se muestran, los comportamientos esperados y los efectos secundarios esperados. En esta página, se describe el paquete de pruebas en el que puedes implementar y ejecutar casos de prueba.

Estructura de crate de alto nivel de abstracción de la plataforma

Los proyectos de Rust consisten en crates. En la figura 1, se muestra la estructura de cajas de la capa de abstracción de la plataforma de HAR. La capa de abstracción de la plataforma afecta a dos o más cajas de Rust:

  • Las abstracciones (descripciones de Rust trait) se encuentran en el contenedor del framework de HAR.

  • Las implementaciones para una plataforma se realizan mediante un cajón har-platform-x independiente. Por ejemplo, har-platform-linux o har-platform-android.

No puedes compilar ni probar la caja de HAR sin una implementación de plataforma específica. Esto es intencional, ya que el framework de HAR es un framework.

Una app que especifica una plataforma debe compilarse con este framework para que funcione y se pruebe. Las conexiones entre el framework de HAR y la plataforma se encuentran en este diagrama:

Caja de HAR

Figura 1: Caja de HAR.

Estructura general dentro de display-safety

Este diseño agrega una serie de cajas nuevas al repositorio display_safety, como se ilustra en la Figura 2:

Crate, framework y app de HAR

Figura 2: Módulos de abstracción

Un paquete de pruebas es estructuralmente similar a una app, pero solo depende de un crate de implementación de plataforma determinado. El paquete de pruebas debe hacer referencia a los rasgos y las estructuras definidos en el framework de HAR, pero no debe hacer referencia a implementaciones más complejas.

Descripción de alto nivel de la capa de abstracción de la plataforma

En esta tabla, se describen los subsistemas específicos de la plataforma que define la capa de abstracción de la plataforma de HAR.

Nombre de la abstracción Función relacionada Descripción Notas
OpenGL Renderización en 2D Proporciona capacidades de renderización de OpenGLES 2.0/3.0 al framework de HAR.
Audio Renderización de audio Proporciona una interfaz similar a SoundPool de Android para administrar y reproducir audio del sistema.
Camera Pantalla de la cámara del vehículo Proporciona una interfaz similar a la HAL de EVS para administrar y mostrar información de la cámara del vehículo.
Looper Bucle principal de la app y configuración de la pantalla Proporciona una interfaz similar a Android Looper para administrar los bucles principales de la app específicos de la plataforma y la configuración de la pantalla.
UserInput Entrada táctil, de teclado, de volante o de control giratorio, y otras entradas específicas de la plataforma Proporciona una interfaz para suministrar entrada táctil y de teclado a las apps basadas en HAR. Implementación de referencia basada en Linux evdev en har-user-input-evdev.
VehicleData Entrada de estado del vehículo Proporciona una interfaz para suministrar a las apps basadas en HAR un flujo de datos arbitrarios del vehículo, como los que proporciona la VHAL de Android o un bus CAN.
ResourceManager Documento de diseño almacenado en caché específico de la app Proporciona una caché de la memoria de los recursos necesarios para el inicio de HAR, como imágenes almacenadas en caché y documentos de diseño. Aún no se implementó la memoria caché del disco.
Logging Registro y telemetría del sistema Proporciona compatibilidad con el registro específico de la plataforma a través del sistema de seguimiento. Esto habilita la recopilación de telemetría según lo requiera la plataforma.
Tracing Registro del sistema Proporciona una abstracción para la integración con sistemas de seguimiento y generación de perfiles.
Monitoring Supervisión del sistema Es un kit de herramientas para supervisar el rendimiento y las latencias dentro del framework de HAR.
Commlib Datos del vehículo Es una implementación de referencia que usa la serialización de protobuf. Obsoleto: Usa las APIs definidas en reference/harry-control-api y las implementaciones harry-grpcio-server y harry-tonic-server (implementación de referencia).
TestSupport Hooks de asistencia para pruebas Admite la compilación y el desglose de casos de prueba, la generación de eventos de prueba y la creación de artefactos de prueba. Por ejemplo, generar eventos táctiles simulados para probar UserInput y generar capturas de pantalla para el análisis. Rust bloquea esta función para evitar que se incluya en las compilaciones de producción.

Convenciones de nombres y estructuras de frameworks

En esta tabla, se presentan estos nombres y estructuras:

  • Se esperan instancias del subsistema trait proporcionadas por el framework de HAR. Cada trait representa un subsistema específico de la plataforma que se debe implementar.

  • Nombres esperados de las implementaciones de subsistemas específicos de la plataforma en cualquier crate de plataforma. Las apps basadas en HAR esperan que se implementen estos nombres específicos.

  • Instancias relacionadas de enum y struct del framework de HAR que se suelen usar para pasar información de implementaciones relacionadas con la plataforma al framework de HAR.

Nombres de rasgos Nombres de implementación Enum y structs del framework de HAR
GlContextFactory OpenGL trait harry::Renderer
harry::DisplayRotation
AudioApiFactory Audio harry::AudioApi
harry::AudioDevice
harry::VolumeMillibel
ICameraManager Camera harry::ICameraDevice
harry::CameraDescriptor
Looper Looper harry::LooperMessage
harry::LooperOptions
harry::DisplayId
PlatformVehicleData VehicleData harry::VehicleDataType
harry::VehicleDataListener
ResourceManager (Struct) ResourceManager harry::ResourceManagerMessage
harry::ResourceToken
harry::RawImageData
PlatformTracing Tracing N/A
HarPerformanceMonitor Monitoring harry::Renderer
harry::ResolveLatencyToken
PlatformTestSupport TestSupport harry::TestConfig
harry::TestDisplayConfig

Errores y manejo de errores

Las APIs propuestas usan el tipo Result<> de Rust. Rust requiere que verifiques los tipos Result que contienen errores. De lo contrario, el compilador genera una advertencia o un error. Una verificación en el momento de la compilación aplica la verificación de errores del código específico de la plataforma.

Los errores que devuelven las implementaciones de la plataforma son del tipo harry::error::Error. Para verificar que los tipos de errores de la plataforma no se filtren en el código de la app, usa el tipo de error estándar que proporciona el framework de HAR.

El tipo harry::error::Error se expande para incluir errores específicos de todos los subsistemas:

// This is Rust
pub enum Error {
  Msg(String), // A generic message string
  // Legacy error type, likely to be removed or merged into Msg
  Audio(String),
}

Los errores irrecuperables se devuelven principalmente a través de las interfaces y devoluciones de llamada definidas.

Diseño detallado del paquete de pruebas

En esta sección, se describe el diseño del paquete de pruebas, que verifica las implementaciones de las abstracciones específicas de la plataforma.

Compila las pruebas del paquete de pruebas

En el caso de las compilaciones de Soong (definidas por archivos Android.bp), las pruebas se compilan como parte del sistema de compilación de la plataforma de Android, y su ejecución la administra atest.

Ejecuta el paquete de pruebas

Para probar una plataforma individual, usa el comando atest con el destino de prueba pertinente (por ejemplo, atest <module_name>). Este comando implementa y ejecuta las pruebas en un dispositivo o emulador con Android.