Camada de abstração da plataforma HAR

Use o renderizador de alta disponibilidade (HAR, na sigla em inglês) para mostrar informações do veículo que o Android não pode exibir. Isso pode acontecer devido a problemas como inicialização, disponibilidade, segurança ou regulamentações. O HAR é um app portátil integrado escrito em Rust.

O HAR, também chamado de framework HAR, inclui o código usado para criar apps. Um app criado com HAR é um app baseado em HAR. O framework HAR tem seções de código para diferentes plataformas. Por exemplo, em um sistema Linux, você usa bibliotecas como tinyalsa para sons. O QNX tem as próprias bibliotecas de áudio.

Uma plataforma inclui hardware, um sistema operacional, bibliotecas de sistema e outros fatores. O código específico da plataforma tem partes chamadas subsistemas. Cada subsistema processa um recurso da plataforma, como áudio, câmeras EVS ou dados do veículo. Para oferecer suporte a uma plataforma, o framework HAR precisa que todos os subsistemas sejam implementados.

O código do subsistema específico da plataforma pode ser executado no mesmo processo que o app baseado em HAR ou em um processo separado. Quando separado, esse código processa a comunicação entre processos (IPC, na sigla em inglês) para ajudar a verificar se a plataforma é compatível com o app. Mecanismos complexos de IPC precisam fazer parte do código específico da plataforma.

O pacote de testes do HAR executa testes em todos os subsistemas implementados para uma plataforma. Use esse pacote para verificar se as plataformas atendem aos requisitos de HAR e encontrar novos problemas.

Terminologia

Estes termos estão nesta página:

App baseado em HAR
Um app de OEM ou de função específica criado com o framework HAR. Os apps diferem pelo estado e por outros aspectos personalizáveis.
Framework HAR
Oferece um conjunto básico de ferramentas usadas para criar apps.
Abstração da plataforma HAR
Parte do framework HAR que fornece uma API conhecida que todas as plataformas de destino precisam implementar.
Pacote de testes HAR
Uma série de testes conhecidos em implementações de plataforma, ajudando a verificar se as implementações de plataforma são compatíveis com o framework HAR em uma determinada plataforma.

Fora do escopo

O HAR não aborda:

  • Implementações individuais para todas as plataformas de destino: implementações para plataformas de destino. Em vez disso, esta página descreve as interfaces que as implementações de plataforma precisam cumprir e que um pacote de testes precisa satisfazer.

  • Casos de teste: casos de teste específicos para todas as interfaces. Em vez disso, esta página descreve funções individuais para interfaces, incluindo argumentos, valores de retorno, comportamentos esperados e efeitos colaterais esperados. Nesta página, descrevemos o pacote de testes em que você pode implementar e executar casos de teste.

Estrutura de crate de alto nível de abstração de plataforma

Os projetos do Rust consistem em crates. A Figura 1 mostra a estrutura do crate para a camada de abstração da plataforma HAR. A camada de abstração da plataforma afeta dois ou mais crates do Rust:

  • As abstrações (descrições de trait do Rust) estão na caixa do framework HAR.

  • As implementações para uma plataforma são feitas por um crate har-platform-x separado. Por exemplo, har-platform-linux ou har-platform-android.

Não é possível criar ou testar o crate HAR sem uma implementação de plataforma especificada. Isso é intencional, já que o framework HAR é um framework.

Um app que especifica uma plataforma precisa ser criado com esse framework para funcionar e ser testado. As conexões entre o framework HAR e a plataforma estão neste diagrama:

Caixa HAR

Figura 1. Caixa HAR.

Estrutura geral em display-safety

Esse design adiciona uma série de novos crates ao repositório display_safety, conforme ilustrado na Figura 2:

Crate, framework e app de HAR

Figura 2. Módulos de abstração.

Um pacote de testes é estruturalmente semelhante a um app, mas depende apenas de um determinado crate de implementação de plataforma. O pacote de testes precisa se referir a características e estruturas definidas no framework de HAR, mas não a implementações mais complexas.

Descrição de alto nível da camada de abstração da plataforma

Esta tabela descreve os subsistemas específicos da plataforma definidos pela camada de abstração da plataforma HAR.

Nome da abstração Função relacionada Descrição Observações
OpenGL Renderização 2D Oferece recursos de renderização do OpenGLES 2.0/3.0 para o crate do framework HAR.
Audio Renderização de áudio Oferece uma interface semelhante ao SoundPool do Android para gerenciar e reproduzir áudio do sistema.
Camera Tela da câmera do veículo Oferece uma interface semelhante à HAL do EVS para gerenciar e mostrar informações da câmera do veículo.
Looper Loop principal do app e configuração de exibição Oferece uma interface semelhante ao Looper do Android para gerenciar loops principais de apps específicos da plataforma e exibir configurações.
UserInput Toque, teclado, volante ou controle giratório e outras entradas específicas da plataforma. Oferece uma interface para fornecer entrada por toque e teclado a apps baseados em HAR. Implementação de referência baseada no Linux evdev em har-user-input-evdev.
VehicleData Entrada de estado do veículo Oferece uma interface para fornecer aos apps baseados em HAR um stream de dados arbitrários do veículo, como os fornecidos pela VHAL do Android ou por um barramento CAN.
ResourceManager Documento de design em cache específico do app Fornece um cache em memória de recursos necessários para a inicialização do HAR, como imagens em cache e documentos de design. Nenhum cache em disco foi implementado ainda.
Logging Geração de registros e telemetria do sistema Oferece suporte a registros específicos da plataforma usando o sistema de rastreamento. Isso permite a coleta de telemetria conforme exigido pela plataforma.
Tracing Rastreamento do sistema Fornece uma abstração para integração com sistemas de rastreamento e criação de perfil.
Monitoring Monitoramento do sistema Kit de ferramentas para monitorar o desempenho e as latências no framework HAR.
Commlib Dados do veículo Uma implementação de referência que usa a serialização de protobuf. Descontinuado: use as APIs definidas em reference/harry-control-api e as implementações harry-grpcio-server e harry-tonic-server (implementação de referência).
TestSupport Como testar hooks de suporte Oferece suporte à criação e remoção de casos de teste, geração de eventos de teste e criação de artefatos de teste. Por exemplo, gerar eventos de toque simulados para testar UserInput e gerar capturas de tela para análise. Esse recurso é bloqueado pelo Rust para evitar a inclusão em builds de produção.

Convenções de nomenclatura e estruturas de framework

Esta tabela apresenta esses nomes e estruturas:

  • Instâncias esperadas do subsistema trait fornecidas pelo framework do HAR. Cada trait representa um subsistema específico da plataforma que precisa ser implementado.

  • Nomes esperados de implementações de subsistemas específicos da plataforma em qualquer crate de plataforma. Os apps baseados em HAR esperam que esses nomes específicos sejam implementados.

  • Instâncias relacionadas do framework HAR enum e struct normalmente usadas para transmitir informações de implementações relacionadas à plataforma para o framework HAR.

Nomes de atributos Nomes de implementação Tipo enumerado e structs do framework 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

Erros e tratamento de erros

As APIs propostas usam o tipo Result<> do Rust. O Rust exige que você verifique os tipos Result que carregam erros. Caso contrário, o compilador vai gerar um aviso ou erro. Uma verificação de tempo de compilação aplica a verificação de erros do código específico da plataforma.

Os erros retornados pelas implementações de plataforma são do tipo harry::error::Error. Para verificar se os tipos de erro da plataforma não vazam para o código do app, use o tipo de erro padrão fornecido pelo framework do HAR.

O tipo harry::error::Error se expande para incluir erros específicos de todos os 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),
}

Os erros irrecuperáveis são retornados principalmente pelas interfaces e callbacks definidos.

Design detalhado do pacote de testes

Nesta seção, descrevemos o design do pacote de testes, que verifica as implementações das abstrações específicas da plataforma.

Criar os testes do pacote de testes

Para builds do Soong (definidos por arquivos Android.bp), os testes são compilados como parte do sistema de build da plataforma Android, e a execução deles é gerenciada pelo atest.

Executar o pacote de testes

Para testar uma plataforma individual, use o comando atest com o destino de teste relevante (por exemplo, atest <module_name>). Esse comando implanta e executa os testes em um dispositivo ou emulador com tecnologia Android.