检查验证器 Puppet 架构

概览

验证器系统会发送 FIDL 命令来控制“傀儡”程序，该程序会调用库功能来修改验证器随后评估的某些状态。如需详细了解 Inspect 验证器，请参阅 README。

傀儡包含以下部分：

  • 提供 FIDL 协议。
  • 解压缩协议并进行库调用。
  • 构建包含傀儡和验证器程序的集成测试。

本文档重点介绍位于 //src/diagnostics/validator/inspect/lib/rust/src/main.rs 的 Inspect 验证器 Rust 傀儡。

FIDL 设计

Inspect 傀儡的 FIDL 协议在 //src/diagnostics/validator/inspect/fidl/inspect_puppet.fidl 中定义。 FIDL 协议与 Inspect 库 API 中的函数紧密对应，该 API 定义了要应用于任何 Inspect API 实现的操作。FIDL API 的编写与 Rust API 相对应。

（注意：Inspect API 可以与 Rust API 不同；此类 API 可能需要修改傀儡代码架构。）

提供 FIDL

main() 函数执行样板代码，以通过 run_driver_service() 提供单个 FIDL 客户端，该函数会从 FIDL 流接收 Initialize 或 Act 事件。Act 事件由 Actor 对象 维护控制 Inspect 库所需的状态。

Actor 和 Inspect 库

Actor 包含 Inspector（Inspect 库的入口点对象）、nodes 的哈希映射和 properties 的哈希映射。它实现了一个函数 act()，其中包含一个巨大的 match 语句（在其他语言中为“switch”或“case”），用于调用库实现的每个操作。 对于库不支持的操作，傀儡可以报告 Unimplemented。

验证器调用每个操作后，它将测试库对 VMO 的影响。库应处理操作效果的传播，以便验证器可以看到这些效果。

nodes 和 properties 的哈希映射存储由 Inspect 库返回的值。由于 Rust 是一种 RAII 语言，当内存引用丢失时会自动清理，因此如果未能存储节点或属性，会导致立即删除该节点或属性。此外，存储属性还允许响应 FIDL 命令来更新其值。

测试和构建系统

验证器和傀儡的组合应进行密封集成测试。

依赖项和名称

验证器的 BUILD.gn 文件 定义了一个 validator_bin 目标， Rust 傀儡的 BUILD.gn 文件 将其用作名为 inspect_validator_test_rust 的 test_package() 的依赖项， 该依赖项是执行 Rust 傀儡的测试。

Rust 傀儡本身就是 一个组件。 该构建规则会生成 inspect_validator_rust_puppet，该规则包含在 fuchsia_unittest_package() 的二进制文件中。

验证器的 Build.gn 文件 中的 validator_bin 目标包含在 fuchsia_unittest_package() 的 deps 中。

CQ/CI

将其 BUILD.gn 中的 inspect_validator_test_rust 放入 group("tests") 的 deps 中，可以轻松地将 inspect_validator/lib/rust:tests 放入 src/diagnostics/BUILD.gn 的 group("tests") 的 deps 中。构建系统会选择此项，并导致在 CQ 和 CI 中运行 Inspect 验证器 Rust 傀儡测试。

元 .cml 文件

//src/diagnostics/validator/inspect/meta 中包含以下 CML 文件：

  • puppet.shard.cml

    允许傀儡二进制文件运行、使用记录器和 Inspect，并提供验证协议。

  • validator.cml

    • use: protocol: 指定验证器运行所需的服务。
      • fuchsia.diagnostics.ArchiveAccessor 允许验证器读取傀儡发布的 Inspect 数据。
      • diagnostics.validate.InspectPuppet 允许验证器控制傀儡。
    • children: name: "puppet" 将傀儡放置在组件层次结构中。
    • children: url: "#meta/puppet.cm" 允许查找和加载傀儡。
    • 需要 offer: protocol: "fuchsia.logger.LogSink" 才能显示傀儡的日志。
    • 为每个傀儡的验证器提供必要的结构化配置。

  • test.shard.cml

    定义运行 Inspect 验证器测试管理器（验证器和组件的父级）所需的功能。

这些分片由每个傀儡目录中傀儡和验证器的 CML 文件使用，或由测试管理器使用。目前有 2 个傀儡：

验证器控制器的 CML 在 fuchsia_unittest_package()（对于 Rust 或 C++）或 fuchsia_unittest_component()（对于 Go）的 manifest 键中引用。