HAR 平台抽象层

使用高可用性渲染程序 (HAR) 显示 Android 无法显示的车辆信息。这可能是由于启动、可用性、安全或法规等问题造成的。HAR 是一个使用 Rust 编写的内置便携式应用。

HAR（也称为 HAR 框架）包含用于构建应用的代码。使用 HAR 构建的应用是基于 HAR 的应用。HAR 框架包含适用于不同平台的代码部分。例如，在 Linux 系统上，您可以使用 tinyalsa 等库来播放声音。QNX 有自己独特的音频库。

平台包括硬件、操作系统、系统库和其他因素。平台专用代码包含称为子系统的部分。每个子系统负责处理一项平台功能，例如音频、EVS 摄像头或车辆数据。为了支持某个平台，HAR 框架需要实现其所有子系统。

平台专用子系统代码可能与基于 HAR 的应用在同一进程中运行，也可能在单独的进程中运行。分开时，此代码会处理进程间通信 (IPC)，以帮助验证平台是否支持应用。复杂的 IPC 机制必须是平台专用代码的一部分。

HAR 测试套件会对为平台实现的所有子系统运行测试。使用此套件可检查平台是否满足 HAR 要求，并发现任何新问题。

术语

本页使用了以下术语：

基于 HAR 的应用
使用 HAR 框架构建的 OEM 或特定于功能的应用。应用因应用状态和其他可自定义方面而异。
HAR 框架
提供用于构建应用的一组核心工具。
HAR 平台抽象
HAR 框架的一部分，提供所有目标平台都必须实现的已知 API。
HAR 测试套件
一系列针对平台实现的已知测试，有助于验证平台实现是否支持给定平台上的 HAR 框架。

不在范围内

HAR 不会解决以下问题：

  • 针对所有平台目标的单独实现：针对目标平台的实现。相反，本页介绍了平台实现必须满足的接口以及测试套件必须满足的接口。

  • 测试用例：适用于所有接口的特定测试用例。相反，本页面介绍了接口的各个函数，包括参数、返回值、预期行为和预期副作用。本页介绍了您可以在其中实现和运行测试用例的测试套件。

平台抽象高级 crate 结构

Rust 项目由 crate 组成。图 1 显示了 HAR 平台抽象层的 crate 结构。平台抽象层会影响两个或更多 Rust crate：

  • 抽象（Rust trait 描述）位于 HAR 框架 crate 中。

  • 平台的实现由单独的 har-platform-x crate 完成。例如 har-platform-linux 或 har-platform-android。

如果没有指定的平台实现，您将无法构建或测试 HAR crate。这是有意为之，因为 HAR 框架是一个框架。

指定了平台的应用必须使用此框架进行构建，才能正常运行和接受测试。下图展示了 HAR 框架与平台之间的连接：

HAR crate

图 1. HAR crate。

display-safety 中的常规结构

此设计向 display_safety 代码库添加了一系列新的 crate，如图 2 所示：

HAR crate、框架和应用

图 2. 抽象模块。

测试套件在结构上与应用类似，但仅依赖于给定的平台实现 crate。测试套件必须引用 HAR 框架中定义的特征和结构，但不应引用更复杂的实现。

平台抽象层简要说明

下表介绍了由 HAR 平台抽象层定义的平台专用子系统。

抽象化名称 相关函数 说明 备注
OpenGL 2D 渲染 为 HAR 框架 crate 提供 OpenGLES 2.0/3.0 渲染功能。
Audio 音频呈现 提供类似于 Android SoundPool 的接口，用于管理和播放系统音频。
Camera 车载摄像头显示屏 提供类似 EVS HAL 的接口，用于管理和显示车载摄像头信息。
Looper 应用主循环和显示配置 提供类似于 Android Looper 的接口，用于管理平台专用应用主循环和显示配置。
UserInput 触控、键盘、方向盘或旋控器，以及其他平台专用输入 提供一个接口，用于为基于 HAR 的应用提供轻触和键盘输入。基于 Linux evdev 的参考实现，位于 har-user-input-evdev 中。
VehicleData 车辆状态输入 提供一个接口，用于向基于 HAR 的应用提供任意车辆数据流，例如由 Android VHAL 或 CAN 总线提供的数据。
ResourceManager 应用专属缓存设计文档 提供 HAR 启动所需资源的内存缓存，例如缓存的图片和设计文档。尚未实现磁盘缓存。
Logging 系统日志记录和遥测 使用跟踪系统提供特定于平台的日志记录支持。这样可以根据平台要求启用遥测收集。
Tracing 系统跟踪 提供一种抽象机制，用于与跟踪和性能分析系统集成。
Monitoring 系统监控 用于监控 HAR 框架内性能和延迟时间的工具包。
Commlib 车辆数据 使用 protobuf 序列化的参考实现。 已废弃：使用 reference/harry-control-api 中定义的 API 以及实现 harry-grpcio-server 和 harry-tonic-server（参考实现）。
TestSupport 测试支持钩子 支持测试用例的构建和拆解、测试事件的生成以及测试工件的创建。例如，生成模拟触摸事件以测试 UserInput，以及生成屏幕截图以进行分析。 此功能已被 Rust 锁定，以防止包含在正式版 build 中。

命名惯例和框架结构

下表列出了这些名称和结构：

  • HAR 框架提供的预期子系统 trait 实例。每个 trait 都代表一个必须实现的平台专用子系统。

  • 任何平台 crate 中平台专用子系统实现的预期名称。基于 HAR 的应用需要实现这些特定名称。

  • 相关的 HAR 框架 enum 和 struct 实例，通常用于将信息从平台相关实现传递到 HAR 框架。

特征名称 实现名称 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（结构体） ResourceManager harry::ResourceManagerMessage
harry::ResourceToken
harry::RawImageData
PlatformTracing Tracing 不适用
HarPerformanceMonitor Monitoring harry::Renderer
harry::ResolveLatencyToken
PlatformTestSupport TestSupport harry::TestConfig
harry::TestDisplayConfig

错误和错误处理

建议的 API 使用 Rust Result<> 类型。Rust 要求您检查包含错误的 Result 类型。否则，编译器会生成警告或错误。构建时检查会强制执行平台专用代码中的错误检查。

平台实现返回的错误属于 harry::error::Error 类型。为确保平台错误类型不会泄露到应用代码中，请使用 HAR 框架提供的标准错误类型。

harry::error::Error 类型会展开，以包含所有子系统的特定错误：

// 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),
}

不可恢复的错误主要通过定义的接口和回调返回。

测试套件详细设计

本部分介绍了测试套件的设计，该套件用于验证抽象的平台专用实现。

构建测试套件测试

对于 Soong build（由 Android.bp 文件定义），测试会作为 Android 平台 build 系统的一部分进行编译，其执行由 atest 管理。

运行测试套件

如需测试单个平台，请将 atest 命令与相关测试目标（例如 atest <module_name>）搭配使用。此命令会在 Android 设备或模拟器上部署并运行测试。