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 consegue exibir. Isso pode acontecer devido a problemas como inicialização, disponibilidade, segurança ou regulamentações. O HAR é um app portátil e integrado escrito em Rust.

O HAR, também chamado de framework HAR, inclui o código usado para criar apps. Um app criado com o HAR é um app baseado no 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 bibliotecas de áudio exclusivas.

Uma plataforma inclui hardware, um sistema operacional, bibliotecas do sistema e outros fatores. O código específico da plataforma tem partes chamadas de 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 do app baseado no 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 oferece suporte ao 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 do HAR e para encontrar novos problemas.

Terminologia

Estes termos estão nesta página:

App baseado no HAR
Um app específico da função ou do OEM criado com o framework HAR. Os apps variam de acordo com o estado do app e outros aspectos personalizáveis.
Framework HAR
Fornece um conjunto principal 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 do HAR
Uma série de testes conhecidos em implementações de plataforma, ajudando a verificar se as implementações de plataforma oferecem suporte ao framework HAR em uma determinada plataforma.

Fora do escopo

O HAR não aborda:

  • Implementações individuais para todos os destinos de plataforma: implementações para plataformas de destino. Em vez disso, esta página descreve as interfaces que as implementações de plataforma precisam atender e 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. Esta página descreve 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 de 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 no crate do framework HAR.

  • As implementações de 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. Crate 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:

Caixa, framework e app 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 traits e estruturas definidas no framework 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 Fornece recursos de renderização OpenGLES 2.0/3.0 para o crate do framework HAR.
Audio Renderização de áudio Fornece uma interface semelhante ao SoundPool do Android para gerenciar e reproduzir áudio do sistema.
Camera Tela da câmera do veículo Fornece uma interface semelhante ao EVS HAL para gerenciar e mostrar informações da câmera do veículo.
Looper Loop principal do app e configuração de exibição Fornece uma interface semelhante ao Looper do Android para gerenciar loops principais de apps específicos da plataforma e configuração de exibição.
UserInput Toque, teclado, volante ou controlador rotativo e outras entradas específicas da plataforma Fornece uma interface para fornecer entrada de toque e teclado a apps baseados no HAR. Implementação de referência baseada em Linux evdev em har-user-input-evdev.
VehicleData Entrada de estado do veículo Fornece uma interface para fornecer aos apps baseados no HAR um fluxo de dados arbitrários do veículo, como os fornecidos pelo VHAL do Android ou um barramento CAN.
ResourceManager Documento de design armazenado em cache específico do app Fornece um cache na memória de recursos necessários para a inicialização do HAR, como imagens armazenadas em cache e documentos de design. Nenhum cache em disco implementado ainda.
Logging Registro e telemetria do sistema Fornece suporte de registro específico 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 usando a serialização de protobuf. Descontinuado: use as APIs definidas em reference/harry-control-api e implementações harry-grpcio-server e harry-tonic-server (implementação de referência).
TestSupport Hooks de suporte a testes Oferece suporte à criação e desmontagem 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 de trait de subsistema esperadas fornecidas pelo framework 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 no HAR esperam que esses nomes específicos sejam implementados.

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

Nomes de traits Nomes de implementação Enum 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 contêm erros. Caso contrário, o compilador gera um aviso ou erro. Uma verificação de tempo de build impõe 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 HAR.

O tipo harry::error::Error é expandido para incluir erros específicos para 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),
}

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

Design detalhado do pacote de testes

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

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 Android.