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 框架的相关 HAR 框架 enum 和 struct 实例。

特性名称 实现名称 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 平台构建系统的一部分进行编译，其执行由 atest 管理。

运行测试套件

如需测试单个平台，请执行以下操作：

使用 atest 命令以及相关测试目标（例如 atest <module_name>）。此命令会在 Android 设备或模拟器上部署并运行测试。