Fuchsia 组件检查概览

Fuchsia 中的组件可能会按照 Inspect API 的要求公开关于自身的结构化信息。本文档介绍了组件检查的概念、接口、接口的 C++ 语言实现，以及与提供信息的组件交互的面向用户的工具。

不知从何下手？

概念

组件可以公开节点树，其中每个节点都有一组属性。

图：节点树

节点

节点是组件内的导出实体，可有 0 个或多个子项。每个节点都有一个名称，且节点的每个子级都必须具有唯一的名称。

图：节点

属性

节点可以具有任意数量的属性。属性具有字符串键和值，该值可以是多种类型中的任意一种：

数字类型

  • UintProperty - 64 位无符号整数。
  • IntProperty - 64 位有符号整数。
  • DoubleProperty - 64 位浮点值。
  • BoolProperty - 布尔值。

字符串类型

  • StringProperty - UTF-8 字符串。
  • ByteVectorProperty - 字节矢量。

数组类型

  • UintArray、IntArray、DoubleArray - 相应数值类型的数组。

直方图类型

  • LinearUintHistogram、LinearIntHistogram、LinearDoubleHistogram

包含存储在数组中的固定大小存储分区的直方图。

  • ExponentialUintHistogram、ExponentialIntHistogram、ExponentialDoubleHistogram

以数组形式存储指数级大小的直方图。

检查文件格式

检查文件格式是一种二进制格式，支持在运行时高效插入、修改和删除节点和属性。读者无需与作者交流即可拍摄一致的内容快照。

文件系统接口

顶级节点在以扩展程序 .inspect 结尾的组件的传出目录中以 VmoFile 的形式公开。组件通常将其主要树或根树公开为 out/diagnostics/root.inspect。

语言库

C++

C++ Inspect 库为检查文件格式提供完整的写入和读取支持。

写入检查数据的组件应避免读取这些数据。读取操作需要遍历整个缓冲区，开销非常高。

Inspector 类提供了一个封装容器，用于创建一个新缓冲区，该缓冲区具有一个可添加到的根节点。节点和属性具有类型封装容器，这些封装容器在底层数据超出范围时会自动从缓冲区中删除。

inspect_component 库提供了一个简单的 ComponentInspector 单例接口，可帮助应对公开组件中的单个层次结构这种常见情况。

运行状况功能支持以健康检查工具已知的格式公开结构化的健康信息。

test matchers 库提供了 GMock 匹配器，用于验证从测试中的检查层次结构中读取的数据。

朗读支持

读取库支持将检查文件解析为某个层次结构。Hierarchy 包含 NodeValue 和 PropertyValues，它们分别是 Node 和 Property 的解析版本。

Hierarchy 的 NodeValue 由 node() 返回，子 Hierarchy 由 children() 在矢量中返回。GetByPath 函数支持按路径读取特定的子级层次结构。

特定 NodeValue 的属性可通过 properties() 访问器获取。您可以通过将相应的 PropertyValue 类型作为模板参数传递给 Contains<T>() 方法来确定属性是否包含某种类型：

  // Returns true if the first property of the hierarchy's node is an INT value.
  if (hierarchy.node().properties()[0].Contains<IntPropertyValue>()) {
    // ...
  }

使用 Get<T>() 方法获取该属性：

  // Get the IntPropertyValue of the first property on the node.
  // Note: This causes a runtime exception if the property does not contain
  // the given type, crashing the program.
  hierarchy.node().properties()[0].Get<IntPropertyValue>();

您还可以根据其他可能的格式类型进行切换：

  const auto& property = hierarchy.node().properties()[0];
  switch (property.format()) {
    case FormatType::INT:
      const auto& value = property.Get<IntPropertyValue>();
      /* ... */
      break;
    /* ... */
  }

数组类型可能会采用特殊格式，以包含直方图。GetBuckets() 方法支持从 {Int,Uint,Double}ArrayValue 类型返回一组直方图存储分区。如果基础数组不是采用特殊格式的直方图，则数组将为空。

Rust

Rust Inspect 库为检查文件格式提供完整的写入和读取支持。

写入检查数据的组件应避免读取这些数据。读取操作需要遍历整个缓冲区，开销非常高。

Inspector 类提供了一个封装容器，用于创建一个新缓冲区，该缓冲区具有一个可添加到的根节点。节点和属性具有类型封装容器，这些封装容器在底层数据超出范围时会自动从缓冲区中删除。

component 模块支持一个简单的 inspector 函数，用于处理从组件公开单个层次结构的常见用途。

health 模块支持以健康检查工具已知的格式公开结构化的健康信息。

testing 模块支持 assert_data_tree! 宏来匹配检查数据以进行测试。

测试

验证器架构描述了用于检查语言库的集成测试框架。

用户空间工具

如需检查组件的检查层次结构，您可以使用 ffx inspect show 命令：

  • 输出所有检查层次结构：

    ffx inspect show

  • 输出特定组件（例如 core/font_provider）的检查层次结构：

    ffx inspect show core/font_provider

或者，运行 ffx target snapshot 以生成包含系统诊断信息（其中包括检查信息）的 ZIP 归档文件：

ffx target snapshot