安全设计工具链

使用安全设计工具链交付从 Figma 设计文档生成的安全监控器解决方案。按顺序使用这一系列工具。

安全设计编译器会生成安全制品，以驱动后续的代码生成，从而构建安全监控器。设计编译与代码生成工具之间的分离使代码生成工具能够达到 TCL-3 的 ISO-26262 评级。

图 1. 安全设计工具链。

编译器生成制品后，工具链会创建一个报告，OEM 安全工程师可以检查该报告，以验证从 Figma 设计生成的制品。

图 2. 安全设计工具链工作流。

设计编译器输入

序列化设计文档表示从设计工具导入并使用工具包架构处理的界面设计。该文件包含从设计中解析出的以下信息：

• 设计的完整节点树
• 映像和组件
• 名称、版本和上次修改日期等元数据

设计方案的根节点必须在节点列表中定义，并且必须是设计方案中标识出的安全相关元素的根节点。

此文件与 Android Automotive OS 集成，用于渲染仪表盘，并使用在 SDV Media 上运行的高可用性渲染器 (HAR) 显示非安全相关元素，以叠加层的形式向用户显示安全相关元素。

设计编译器使用 DesignCompose 自定义设置来生成输出，以切换设计中安全关键元素的可见性。设计通过 Impeller 以无头模式呈现。在自定义更改之间，系统会向渲染后端发出屏幕截图命令，以生成图片制品。

图 3. 用于构建安全监控器的示例 Figma 设计文件。

输出目录

这是编译器在本地文件系统上存储生成的制品的位置。

JSON 配置文件

通常情况下，OEM 安全工程师会编写 JSON 配置文件，其中包含未在界面设计中捕获的车辆安全相关信息。此文件包含以下数据：

• 指定为安全相关显示根的设计元素。 此设计元素的大小适合车辆显示屏。尺寸必须与显示屏的分辨率相同。所有与安全相关的元素都必须是此元素的后代。它们不必是直接后代，但可以嵌套在中间节点中。此根是根节点对象，其名称必须与设计文档中的某个节点匹配。

• 设计的目标显示设备。为了支持在多个屏幕上显示元素的界面，配置文件可以指定多个设计，每个设计都旨在显示在单独的屏幕上。

• 车辆总线信号名称与关联的界面元素的字典。此字典的键和值如下：

  • 键：包含含义的车辆总线信号名称，以便在相应信号处于有效状态时显示关联的界面元素。当信号处于非活动状态时，关联的界面元素不会显示。

  • 值：由车辆总线信号控制的安全相关元素的 Figma 节点 ID。

请参阅以下 JSON 配置文件示例：

{
  "documents" : [
    {
    "rootnode" : "#Stage",
    "display_id" : 1,
    "document_id": "GLJJrR1JI4HVEjL1qB40zq",
    "states" : {
      "abs": "#cluster/telltale/abs",
      "airbag": "#cluster/telltale/airbag",
      "low_tire_pressure": "#cluster/telltale/low-tire-pressure",
      "brake": "#cluster/telltale/brake",
      "traction": "#cluster/telltale/traction",
      "lowbeam": "#cluster/telltale/lowbeam",
      "hibeam": "#cluster/telltale/hibeam",
      "park_lights": "#cluster/telltale/park-lights",
      "fog_lights": "#cluster/telltale/fog-lights",
      "seatbelts" : "#cluster/telltale/no-seatbelt"
    }
    }
  ]
  ,
  "displays": [
    {
      "id": 1,
      "width": 1920,
      "height": 720
    }
  ]
 }

运行设计编译器

运行设计编译器：

/path/to/safety-design-compiler -c path/to/<input-file>.json
-o path/to/output_directory

下表介绍了设计编译器输入：

输入	短边	类型	说明
配置	-c	字符串	用于保存安全配置 JSON 文件的路径。
输出	-o	字符串	用于保存生成的制品的路径。

设计编译器输出

设计编译器会生成输出并将其保存到您调用编译器工具时指定的输出目录。此输出会生成用于在安全监控器中定义运行时像素测试的头文件，以及生成便于用户理解的报告。设计编译器输出以 Zip 文件的形式提供，其中包含：

• 导出资源根目录中的 data.json 文件元数据文件，用于描述导出设计的结构。文件中的所有路径都相对于此文件。

• 一系列孤立的界面元素图片，用于显示处于活动状态的与安全相关的界面元素，这些元素将在后续的代码生成过程中使用。这些图片中的 Alpha 通道包含不会影响安全性的像素信息。

• 一系列完整的界面图片，用于在测试生成的代码时显示处于有效和无效状态的安全相关界面元素。

• 编译器作为输入所使用的序列化 Figma 文档的更新版本。HAR 通过在工具包架构中设置 RenderOptions::PixelPerfect 标志，标记并更新 Config.json 中指定的指示性节点，以便进行进一步处理。

此图显示了一个 Figma 设计文件。

图 4. ZIP 文件内容。

创建输入文件

为安全监控器生成器创建 data.json 输入文件。输出以数组形式呈现，包含每个与安全相关显示元素的维度数据和图片链接。下表介绍了此输出文件的结构：

元素	类型	单位	说明
static_ui_elements	字典	N/A	一种结构，包含从 Figma 文档中提取的所有与安全相关的界面元素的元数据。
x	int	像素	安全相关元素的水平坐标。
y	int	像素	安全相关元素的垂直坐标。
width	int	像素	安全相关元素的宽度
height	int	像素	与安全相关元素的高度。
name	字符串	N/A	从 Figma 文档中提取的与安全相关的界面元素的名称。 表示使用此元素生成的图片的相关路径。
screen			用于描述界面所定位屏幕的字典。
width	int	像素	Figma 文档界面的宽度。
height	int	像素	Figma 文档界面的高度。
build			包含设计编译器相应调用的 build 信息的字典。
figma_document_id	字符串	N/A	用于生成一组制品文件的 Figma 文档的 ID。
design_compiler_version	字符串	N/A	用于生成一组制品的设计编译器版本。

本部分提供了一个生成的 data.json 文件示例：

{
 "static_ui_elements": [
   {
     "x": 71,
     "y": 663,
     "width": 38,
     "height": 47,
     "name": "cluster/telltale/no-seatbelt"
   },
   {
     "x": 149,
     "y": 667,
     "width": 40,
     "height": 39,
     "name": "cluster/telltale/low-tire-pressure"
   },
      {
     "x": 1727,
     "y": 676,
     "width": 43,
     "height": 27,
     "name": "cluster/telltale/hibeam"
   },
   {
     "x": 1810,
     "y": 675,
     "width": 43,
     "height": 30,
     "name": "cluster/telltale/lowbeam"
   },
  ...
  ...
 ],
 "screen": {
   "width": 1920,
   "height": 720
 },
 "build": {
   "figma_document_id": "taQnsdPS96wZY8dB1TbzOH",
   "design_compiler_version": "0.1.0"
 }
}

导出的设计图片

系统会根据序列化设计文档中安全相关节点的命名，在嵌套目录结构中渲染并保存这些节点的图片。

图 5. 验证图片。

系统会为每个指定的指示灯生成与安全相关联的元素信息图片。这些图片包含安全关键元素在屏幕上可见时的预期像素。出于运行时像素测试的目的，安全监控器可能会忽略这些图片中的透明像素。

系统还会生成界面测试和验证映像。它会渲染包含每个单独的迹象的全界面屏幕截图，并提供这些屏幕截图以生成人类可读的报告，以便安全工程师可以查看和批准安全配置。

您还可以使用这些图片对安全监控器进行后续测试。 系统会生成处于开启和关闭状态的所有指示灯的验证映像。

这些图片展示了包含所有安全相关元素（无论处于有效状态还是无效状态）的设计。

图 6 和图 7。有效和无效的安全相关元素。

图 8 显示了未系安全带指示灯的安全相关信息图片：

图 8. 未系安全带指示灯。

图 9 显示了 Telltale 的界面测试和验证图片。

图 9. 针对信号灯的界面测试和验证。

系统会为已编译制品文件夹中的每个元素生成验证图片。系统会在代码生成步骤中处理这些图片，并将它们添加到头文件中，以便在安全监控器中用于运行时像素测试。

通俗易懂的报告生成器

从 Figma 文档生成制品后，您可以生成人类可读的报告。报告生成器位于 utils/human-readable-report-generator 中。

系统会在 HTML 文件中汇总由 Design Compiler 生成的安全相关节点的制品，包括包含处于活动状态的节点的界面屏幕截图。您可以在构建安全监控器之前查看已编译的制品。

通过命令行运行报告生成器：

cargo run --bin human-readable-report-generator -- -d /path/to/data.json
-o /path/to/output_folder

此表描述了人类可读的报告生成器输入。

输入	短边	类型	说明
data_folder	-d	字符串	由安全编译器生成的 data.json 的位置。
output_path	-o	字符串	用于保存生成的报告的路径。

安全审批工具

为了生成审批令牌，安全工程师在查看了人类可读的报告后，可以针对 output.json 运行安全审批脚本。此工具也位于 utils/human-readable-report-generator 中。例如：

cargo run --bin approve-hrr -- -f /path/to/compiler_inspection_output.html -n
"Your Name" -e [e-mail] -o output/path

图 10. HTML 报告示例。

本部分介绍了安全审批工具的输入。

输入	短边	类型	说明
file_path	-f	字符串	人类可读报告的文件路径。
approver_name	-n	字符串	审批工程师的姓名。
approver_email	-e	字符串	审批工程师的电子邮件地址。
output_path	-o	字符串	生成输出的目标位置。

本部分展示了 approval_file.json 的示例。

{
    "approver_name": //Name of the approver
    "approver_email": //Email of the approver
    "file_hash": //SHA-256 hash generated against the human readable report.
}

参考安全监控器

参考安全监控器是一个基于 Rust 的服务，位于 reference/safety-monitor 中。监控器使用 Design Compiler 生成的制品来监控系统状态，以确保显示安全合规性。

监控器以独立二进制文件 (har_safety_monitor) 的形式运行，并将 data.json 文件的路径和工件的基本路径作为实参。

/path/to/har_safety_monitor --data-json-path /path/to/data.json
--artifact-base-path /path/to/artifacts

监控器执行以下任务：

• 制品加载：加载 data.json 以识别与安全相关的界面元素及其预期位置和尺寸。
• 黄金映像比较：将当前屏幕内容与编译器生成的安全关键元素的黄金映像进行比较。
• 车辆数据集成：连接到车辆数据源，以确定每个指示灯的预期状态。
• 不一致检测：如果根据车辆数据得出的预期结果与屏幕上显示的结果不一致，则记录错误。

安全监控器旨在作为系统映像的一部分进行构建和部署，通常在专用 APEX 中。