RFC-0287:通过 DML 实现配置驱动的驱动程序架构

RFC-0287:通过 DML 实现配置驱动的驱动程序架构
状态已接受
区域
  • 驱动程序
说明

使用驱动程序标记语言的配置驱动型架构。

问题
Gerrit 变更
作者
审核人
提交日期(年-月-日)2026-08-04
审核日期(年-月-日)2026-09-22

问题陈述

此提案旨在解决什么问题?

当前的 Fuchsia 驱动程序框架要求开发者在多个文件中协调配置信息,例如兼容字符串、设备属性、接口和功能路由。这种高度碎片化的模式会导致“协调成本”,从而严重拖慢硬件启动和驱动程序开发。

具体而言,驱动程序的配置目前最多可以来自 6 个不同的位置,其中几个位置包含重复的信息,并且需要驱动程序作者保持多个文件同步:

  1. 绑定规则 (.bind):定义驱动程序管理器的绑定程序用于将驱动程序与设备节点进行匹配的标准,但也包含重要的标签信息。
  2. 组件清单 (.cml):声明驱动程序需要使用、提供或公开的功能,这些功能必须与其父级提供的功能和公开的功能相对应。
  3. 构建系统 (BUILD.gn):指定驱动程序及其绑定标识的物理目标、依赖项和打包规则。
  4. 板级驱动程序(C++ 或 devicetree):手动实例化子节点,注册物理属性(MMIO、IRQ),并将其绑定到匹配的属性。
  5. 驱动程序源代码:以编程方式提取资源,并连接到驱动程序的 Start() 块内由驱动程序和组件框架提供的服务,依赖于必须与开发板驱动程序和清单中声明的字符串名称和索引匹配的硬编码索引或字符串标识符。
  6. FIDL:驱动程序配置和操作所需的元数据通常编码为 FIDL 结构体。

元数据重复的后果

  • 在构建或组装阶段,这些文件中的许多文件不会相互验证,从而增加了同步偏差的可能性。资源名称中的拼写错误或索引不匹配通常会成功编译,但会在运行时静默失败,导致驱动程序无法加载,或在操作期间无法访问资源。
  • 由于无法纯粹通过硬件定义来完成,因此启动新的 SoC 或开发板会遇到更大的阻力。它需要编写和修改板级驱动程序代码,以手动匹配、转换物理资源并将其路由到特定驱动程序实例。
  • 由于绑定系统难以配置和调试,因此通常不清楚驱动程序为何未绑定。由于绑定条件是任意的,并且有许多不同的模式用于匹配驱动程序,因此可能不清楚需要哪些信息。
  • Devicetree 访问器:虽然许多 Fuchsia 开发板目前都使用 devicetree(其中包含所有开发板特定的配置数据),但 devicetree 仍需要由“访问器”程序进行解释,以便在启动时将 devicetree 数据解析为 Fuchsia 所需的格式。虽然访问器对于弥合 Linux Devicetree 架构与 Fuchsia 功能模型之间的差距是必要的,但在运行时使用 C++ 维护和执行此转换层会增加运营开销,并使生成的拓扑更难进行静态检查和验证。
  • 自动化和工具障碍:驱动程序配置文件的多文件碎片化给人类和 AI 驱动程序作者在代码生成和调试方面带来了挑战。驱动程序作者必须同时成功修改和同步 C++ 代码、配置 JSON (.cml) 和特定于网域的绑定语法 (.bind)。

此提案不打算解决哪些问题?

此提案不会取代热插拔总线(例如 USB 和 PCIe)的运行时动态发现和绑定,因为这些总线的设备存在和匹配属性只能在运行时确定。

虽然驱动程序 DML 普遍适用于整个树,但主板 DML 仅针对静态硬件拓扑。我们不会替换 x86 平台上的运行时 ACPI 发现;x86 开发板将继续依赖 ACPI 开发板驱动程序在启动时发现硬件并构建设备节点。

Zircon 的 phys 启动 shim 保持不变;它会继续使用引导加载程序提供的设备树,以便进行早期内核启动和内存预留。

此提案并不能免除开发者编写其驱动程序的核心功能硬件寄存器/逻辑代码的需要。

最后,此提案不规定驱动程序框架元数据架构定义、汇总或反序列化。该架构正在并行设计文档中进行讨论。

背景

驾驶员的核心需求

从根本上讲,驱动程序与操作系统的关系可以分为几个不同的要求。

传入资源:

  • 来自内核:MMIO 寄存器、IRQ、BTI
  • 来自资源控制器:时钟、GPIO、PWM
  • 来自其他驱动程序:许多不同的特定于网域的协议
  • 隐式资源:存储空间和 CPU
  • 驱动程序必须能够假定所有资源都已正确路由,并且所有配置数据都正确无误。(驱动程序无法负责验证其是否连接到正确的服务实例)。

通告和传送输出:向下游客户端公开的逻辑功能(FIDL 协议、服务)。输出可能需要指定一个常规目标,但通常不需要指定特定连接。

内部配置数据:非系统资源参数,允许通用驱动程序针对特定硬件配置(例如,硬件版本、硬件启用标志、实体设备特性)。

生命周期和电源管理:一组定义的接口和 API 协定,涵盖:启动、重新加载、低功耗状态(暂停/恢复)和关机。驱动程序必须与框架达成协议,即如果驱动程序启动或恢复,其所有必需的资源和配置都可用,或者在查询时可用。

理想的系统:

  • 每条信息仅指定一次。
  • 将配置集中到逻辑位置。
  • 在构建或组装时验证是否存在任何配置问题
  • 具有足够的模块化程度,可让多个开发板重复使用驱动程序。

驱动程序配置与系统配置

如果模块化不是一项要求,我们可以将所有配置数据保存在一个位置(板级)。不过,为了保持模块化,我们必须将驱动程序配置拆分到两个位置:

  1. 司机专用 - 指示司机需要根据核心需求进行哪些操作。例如,显示驱动程序可能需要与以下组件进行交互:

    • 2 个时钟:(clock-pixel和clock-dsi),
    • 2 个 mmio 范围(dsi 和 mdp)和 1 个中断 (vsync),
    • 1 个 GPIO 引脚 (gpio-lcd-reset)
    • 输出 fuchsia.hardware.display.DisplayEngine 服务。
  2. 开发板专用 - 为开发板提供有关驱动程序连接方式、其功能来源以及所提供的开发板专用配置数据的特定信息。例如,显示驱动程序的:

    • 两个时钟服务从开发板的时钟控制器路由,其中 clock-pixel 由 main_pll_controller 提供,clock-dsi 由 dsi_pll 提供。
    • mmio 范围和中断由 pdev 驱动程序提供,其中 dsi 对应于偏移量 0x51280 和大小 0xfa0(4000 字节),mdp 对应于偏移量 0x56000 和大小 0x12c0(4800 字节),vsync 中断映射到 IRQ 35。
    • gpio-lcd-reset 引脚从 gpio-controller-20 的引脚 0 路由。

请注意,板级特定信息隐式依赖于驱动程序特定配置。如果驱动程序要保持模块化,这种拆分是不可避免的。

为何要立即启用?

在 Fuchsia 的大部分开发过程中,驱动程序都采用完全动态的模型。对于需要在运行时发现硬件的通用操作系统,此假设非常重要。不过,在可预见的未来,Fuchsia 可以安全地放弃这种灵活性。通过采用我们计划支持的开发板的静态硬件配置,我们可以大大简化驱动程序的发现和配置方式,从而使驱动程序的创建更加符合人体工程学。当然,在某些情况下,动态性仍然不可避免。如需查看这些情况的示例以及我们计划如何解决这些问题,请参阅非静态注意事项。

摘要

此提案引入了将与开发板及其驱动程序相关的所有配置整合到一种配置语言(称为驱动程序标记语言 [DML])中的方法。DML 文件分为 2 类:

  • 驱动程序 DML 文件:这些文件涵盖驱动程序的配置,并整合了当前 .bind 和 .cml 文件中的信息。
  • 开发板 DML 文件:这些文件涵盖整个开发板的配置,旨在提供与当前设备树类似的信息。

这种整合将实现以下架构目标:

  • 所有驱动程序和主板配置以及驱动程序拓扑都将在组装期间完成。
  • 绑定将根据板级 DML 静态完成,而动态绑定则隔离到特定的热插拔子系统(例如 PCIe、USB)。
  • 框架相关的驱动程序 build 配置和驱动程序基本配置样板是从驱动程序 DML 文件生成的。
  • 驱动程序特定配置数据、汇总元数据、资源标识和依赖项解析将基于主板 DML 进行,而不是基于驱动程序之间的父子关系。

此项变更将带来多项好处:

  • 在组装时已知并经过验证的静态配置可大大简化开发板启动。
  • 改进了静态可调试性:由于 DML 会继续为 cmc 生成标准 .cml 清单,因此现有的组件框架工具(例如 cmc 验证、审查和 ffx 组件)可以验证驱动程序组件之间的静态功能路由,而组装时 DML 验证器和 ffx 驱动程序则会处理特定于硬件的限制(MMIO、IRQ、引脚)和运行时诊断
  • 更易于理解的配置:通过消除设备树访问器并将配置整合到两组文件中,人类和 AI 都将更容易理解驱动程序配置。

利益相关方

辅导员:Abdulla Kamar (@abdulla)

Reviewers:

  • Claire Gonyeo (@cgonyeo) - 组件框架
  • Aidan Wolter (@awolter) - 软件组装
  • Suraj Malhotra (@surajmalhotra) - 驱动程序框架
  • Puneetha Ramachandra (@puneetha) - 平台驱动程序
  • Chris Anderson (@cja) - 平台驱动程序
  • Sarah Chan (@spqchan) - 驱动程序框架
  • Justin Mattson (@jmatt) - 驱动程序框架

宣传:此提案已在驱动程序框架和驱动程序团队中进行宣传,以便在架构目标和分阶段实施方面达成一致。

要求

为了解决核心问题,任何可接受的解决方案都必须满足以下架构要求:

  • 声明式开发板配置:必须纯粹通过声明式配置(开发板 DML)来启动新产品或开发板,而无需编写自定义编码的开发板驱动程序或 devicetree 访问器。
  • 单一事实来源:驱动程序的传入和传出依赖项必须在单个经过架构验证的配置文件中声明。
  • 静态验证:必须在编译/汇编时(而非运行时)验证功能路由、物理资源分配和配置。
  • 零样板运行时管道:所有用于诊断(日志记录、检查)、资源映射和 IPC 连接的运行时管道都必须由框架提供,而不是在驱动程序代码中要求手动编码的样板。
  • 直观:人类和 AI 应该能够轻松了解所有驱动程序的连接方式,以及路由了哪些功能和配置。
  • 可调试性:应该可以轻松诊断驱动程序是否缺少启动所需的资源,以及缺少的原因。

设计

1. 驱动程序标记语言 (DML) 与 CML

驱动程序被视为组件,因此需要指定组件清单 (CML),其中列举了组件所需的功能类型。遗憾的是,CML 无法提供驱动程序完全解析其连接所需的所有信息。目前,驱动程序框架使用多个其他信息源来补充 CML。DML 旨在成为 CML 架构的超集,并添加了一些重要方面。 使用单独但类似的配置语言可以快速完成转换,因为我们可以向 DML 添加临时功能,以满足各种驱动程序的需求。完成全面迁移后,我们将在适当的情况下将 DML 的新增功能合并到 CML 中,理想情况下实现完全集成,从而将 DML 完全合并回 CML。

实例身份。

驱动程序通常需要服务的多个不同实例。例如,显示控制器驱动程序可能需要两条单独的时钟线(一条用于像素时序,一条用于 dsi 时序流水线)以及一条 I2C 总线。所有这些功能都由核心驱动程序通过通用 FIDL 服务提供。

当单个 capability 的多个实例路由到驱动程序时,标准 CML 依赖于复合节点的绑定来路由正确的 capability 实例。而 DML 允许 use 块指定本地简称别名。

Driver DML

作者为每个驱动程序定义一个 .dml 文件,用于指定其平台依赖项。dmlc 编译器会在编译时根据驱动程序 DML 生成所需的组件清单(提供给组件框架)、拓扑绑定匹配器和特定于语言的基架。

Driver DML 会将目前通过 .bind 和 .cml 文件组合表达的信息合并到一个统一的 .dml 文件中。

通过这种整合,Driver DML 可以在路由多个相同类型的服务时同时指定身份和功能要求。连接到两个 clock.Service 实例需要 CML 功能声明,以及在 Bind 文件中手动匹配节点和自定义字符串属性。而使用 DML 时,作者可以直接明确声明本地功能身份。

CML(之前) json5 // my-display-driver.cml { capabilities: [ { service: "fuchsia.hardware.display.DisplayEngine" } ], use: [ // Broad declarations for all instances of the service type { service: "fuchsia.hardware.platform.device.Service" }, { service: "fuchsia.hardware.clock.Service" }, { service: "fuchsia.hardware.gpio.Service" }, ], expose: [ { service: "fuchsia.hardware.display.DisplayEngine", from: "self" } ] }

绑定(之前)

// my-display-driver.bind
using fuchsia.platform;
using fuchsia.amlogic.platform;
using fuchsia.amlogic.platform.clock;
using fuchsia.gpio;
using fuchsia.clock;
primary parent "pdev" {
  fuchsia.BIND_PROTOCOL == fuchsia.platform.BIND_PROTOCOL.DEVICE;
  fuchsia.BIND_PLATFORM_DEV_VID == fuchsia.amlogic.platform.BIND_PLATFORM_DEV_VID.AMLOGIC;
  fuchsia.BIND_PLATFORM_DEV_PID == fuchsia.amlogic.platform.BIND_PLATFORM_DEV_PID.A311D;
  fuchsia.BIND_PLATFORM_DEV_DID == fuchsia.amlogic.platform.BIND_PLATFORM_DEV_DID.DISPLAY;
}
parent "gpio-lcd-reset" {
  fuchsia.BIND_PROTOCOL == fuchsia.gpio.BIND_PROTOCOL.DEVICE;
  fuchsia.BIND_GPIO_PIN == fuchsia.amlogic.platform.BIND_GPIO_PIN.LCD_RESET;
}
parent "clock-pixel" {
  fuchsia.BIND_PROTOCOL == fuchsia.clock.BIND_PROTOCOL.DEVICE;
  fuchsia.BIND_CLOCK_ID == fuchsia.amlogic.platform.clock.BIND_CLOCK_ID.CLK_PIXEL;
}
parent "clock-dsi" {
  fuchsia.BIND_PROTOCOL == fuchsia.clock.BIND_PROTOCOL.DEVICE;
  fuchsia.BIND_CLOCK_ID == fuchsia.amlogic.platform.clock.BIND_CLOCK_ID.CLK_DSI;
}

DML(之后) json5 // my-display-driver.dml { name: "my-display-driver", capabilities: [ { service: "fuchsia.hardware.display.DisplayEngine" } ], use: [ { service: "fuchsia.hardware.platform.device.Service", name: "pdev", mmio: [ "dsi", "mdp" ], interrupts: [ "vsync" ], }, { service: "fuchsia.hardware.gpio.Service", name: "gpio-lcd-reset" }, { service: "fuchsia.hardware.clock.Service", name: "clock-pixel" }, { service: "fuchsia.hardware.clock.Service", name: "clock-dsi" }, ], expose: [ { service: "fuchsia.hardware.display.DisplayEngine", name: "display_engine" } ] }

在驱动程序 DML 中,功能要求包括 name 字段,该字段确切指定每个服务连接在本地履行的角色。此外,通过指定唯一的 name,DML 编译器 (dmlc) 可以自动生成可在驱动程序代码中使用的强类型 clock_pixel_ 和 clock_dsi_ 访问器。

为确保这些名称的唯一性并避免冲突,dmlc 将在组装时验证同一驱动程序中的任意两个 use 声明是否具有相同的 name 别名。由于这些别名的作用域仅限于每个单独的驱动程序组件,因此驱动程序作者只需确保其 .dml 文件中的唯一性,而无需与全局其他驱动程序进行协调。

驱动程序专用配置

驱动程序特定配置解析是运行时 panic 和驱动程序样板的重要来源。标准 CML 没有用于定义在组件之间传递的任意载荷字节的内部结构的机制,目前依赖于 FIDL 结构体来定义复杂配置。

在 DML 中,驱动程序将能够直接在定义的功能下嵌套配置架构。通过在协定中明确声明架构,dmlc 能够验证在板 DML 中编码的数据与接收驱动程序特定配置的驱动程序在构建/组装时是否一致。

(确切的配置架构和序列化格式待定,取决于并行设计)。

过渡架构

当前的 DML 架构包含与当前驱动程序框架对接所需的多个过渡 shim。例如,绑定属性会暂时与 capability use 块一起嵌入,以绕过离散的 .bind 文件,并且严格保留“主要父级”概念,以满足旧版复合节点初始化。这些结构是临时的;随着我们转向原生组件框架路由,并逐步消除复合节点和非复合节点之间的区别,这些结构将被完全淘汰。

由于 DML 正在整个树中积极推广,因此本 RFC 避免锁定详尽的架构规范。随着后续迁移暴露出新的极端情况,确切的结构化协定将继续演变。

2. Board DML

板配置目前依赖于 Linux 样式设备树或 C++ 板驱动程序。板级驱动程序负责手动实例化子节点并提供结构化样板代码;设备树则提供通用的 DTS,需要一个“访问者”解析层来将属性转换为 Fuchsia 特定的框架结构。

Board DML 将这两种范式替换为严格声明式、在组装时验证的拓扑。虽然 Board DML 与驱动程序 DML 共享 JSON5 语法,但它提供了互补组件:驱动程序主要使用 use 数组来声明要求,而 Board DML 则布局 children 和 offer 块,以便在驱动程序之间点对点路由功能。

开发板 DML 文件支持包含分片,这样就可以在各种开发板变体之间干净地共享和重复使用基本 SoC 配置。不过,由于板级 DML 代表特定于 Fuchsia 的配置,因此在启动新的 Fuchsia 设备期间,将 Linux 设备树转换为板级 DML 将是验证硬件的重要时机。

声明式功能路由本质上意味着硬件启动顺序和依赖关系图。此外,Board DML 配置将能够指定子组件是否应延迟到满足依赖项,或使用延迟依赖项解析启用并行驱动程序启动。 为了保持依赖项顺序,驱动程序管理器将保留运行器角色,并编排驱动程序启动顺序。

在 Board DML 中:

实例化驱动程序需要相应的条目板 DML 文件。作者在开发板拓扑中将驱动程序声明为子级,并使用 offers 数组中的名称将特定于硬件的实现路由到该驱动程序。这可确保将正确的物理硬件时钟路由到驱动程序内的相应逻辑需求:

// my-board.dml
{
    children: [
        { name: "pdev", url: "fuchsia-pkg://fuchsia.com/platform-bus#meta/platform-bus.cm" },
        { name: "gpio-controller-20", url: "fuchsia-pkg://fuchsia.com/aml-gpio#meta/aml-gpio.cm" },
        { name: "main_pll_controller", url: "fuchsia-pkg://fuchsia.com/aml-clk#meta/aml-clk.cm" },
        { name: "dsi_pll", url: "fuchsia-pkg://fuchsia.com/aml-dsi-pll#meta/aml-dsi-pll.cm" },
        { name: "display", url: "fuchsia-pkg://fuchsia.com/my-display-driver#meta/my-display-driver.cm" }
    ],
    offers: [
        // Route core memory-mapped registers and IRQs
        {
            service: "fuchsia.hardware.platform.device.Service",
            from: "#pdev:display",
            to: "#display:pdev",
            constraints: {
                mmio: [
                    { name: "dsi", address: 0x51280, size: 0xfa0 },
                    { name: "mdp", address: 0x56000, size: 0x12c0 }
                ],
                interrupts: [
                    { name: "vsync", number: 35, mode: "EdgeHigh" }
                ]
            }
        },
        // Route pin 0 to the display for the LCD reset line
        {
            service: "fuchsia.hardware.gpio.Service",
            from: "#gpio-controller-20:lcd_reset",
            to: "#display:gpio-lcd-reset",
            constraints: { pin: 0 }
        },
        // Route the high-frequency PLL to the display's pixel clock
        {
            service: "fuchsia.hardware.clock.Service",
            from: "#main_pll_controller:clock-pixel",
            to: "#display:clock-pixel"
        },
        // Route the dedicated serial interface clock to the display's DSI PHY
        {
            service: "fuchsia.hardware.clock.Service",
            from: "#dsi_pll:clock-dsi",
            to: "#display:clock-dsi"
        }
    ]
}

Board DML 使用驱动程序中的本地名称别名以及驱动程序的名称,明确声明驱动程序拓扑中特定服务实例之间的路由。

编译器 (dmlc) 和工具集成

DML 工具链在驱动程序构建和产品组装期间执行,并将同时对板级 DML 和驱动程序 DML 进行操作。驱动程序 DML 将被解析并嵌入到 meta.far 中,以便在组装期间使用,而主板 DML 将被打包到 BoardConfig 中,替换现有的 devicetree 字段。

构建期间:

  • 组件清单合成:编译驱动程序 DML 以生成驱动程序组件清单 (.cm)。
  • 驱动程序基架生成:输出驱动程序专用代码,用于处理连接到驱动程序 DML 指定的资源所涉及的所有样板,从而大大简化驱动程序设置代码。不同语言绑定的确切结构模式(例如,C++ 对象继承与 Rust 组合)将在后续 RFC 中最终确定。

组装期间:

  • 系统将提供一个 Rust 库 (assembly_dml),该库将关联到程序集二进制文件。
  • 系统将交叉验证主板和驱动程序 DML,以确保所有连接均有效,并提供驱动程序所需的功能。
  • 当前的组件框架验证器(例如硬件资源边界强制执行和结构化配置验证)将扩展为应用于新静态驱动程序。
  • 系统将生成静态节点图,其格式为 json5,可由驱动程序管理器提取。

实现

发布过程分为五个关键运营阶段,以确保平台稳定性:

第 1 阶段:CML 和绑定自动生成

  • dmlc 会解析驱动程序 DML,以生成驱动程序 CML 和 .bind 文件。
  • dmlc 还会编译板 DML,以生成板驱动程序在 Fuchsia 启动时将提取的 fidl 输入。板级 DML 与驱动程序 DML 保持完全隔离。

驱动程序 DML 文件将纯粹作为开发者实用程序引入,而不会更改底层驱动程序框架执行引擎。系统会为所有驱动程序签入驱动程序 DML 文件,并使用这些文件生成现有驱动程序框架代码所使用的 .cml 和 .bind 文件。生成的 .cml 和 .bind 文件将带有“AUTOGENERATED”通知,以便不影响任何活跃的驱动程序开发。.cml 和 .bind 文件将在构建时自动重新生成,并与黄金文件进行比较,以捕获因 dml 文件或 dml 编译器本身发生更改而引入的任何更改。 任何差异都会导致编译器错误。这样,驱动程序就可以迁移到使用驱动程序 DML,而不会中断驱动程序开发,并且驱动程序框架团队可以建立语法架构并收集开发者反馈。

第 2 阶段:为所有开发板生成开发板 DML

以 VIM3 为测试平台,系统地将现有设备树和开发板驱动程序迁移到配置驱动型模型。 * Hide actual conversion to Board DML behind configuration flag * No validation will take place between Board DML and Driver DML yet. * 元数据格式将在单独的设计文档中提出,FIDL 元数据将转换为 DML 格式。

第 3 阶段:验证并切换到开发板 DML

我们将添加一个组装验证器,用于根据驱动程序 DML 验证主板 DML,以便在产品组装期间捕获缺失或不匹配的功能。同时,一个单独的板 DML 验证器将确保切换到板 DML 对运行时驱动程序拓扑或配置没有影响。经过验证后,基于 Devicetree 的开发板将切换到 Board DML,并且其对应的 C++ 开发板驱动程序和 Devicetree 访问器流水线将被删除。 x86 ACPI 板级驱动程序在此阶段保持不变;它将继续在运行时发现设备并发布节点。 请注意,Zircon 的 physboot shim 保持不变,它会使用引导加载程序提供的设备树进行早期内核/物理内存初始化。 将动态引导加载程序提供的运行时参数(例如主板修订版带)桥接到静态主板 DML 拓扑中,这一点在“非静态注意事项和未知因素”下进行了说明。

第 4 阶段:直接原生编译和 Bedrock 集成

Driver Framework 将更新为直接使用 Board DML 和 Driver DML 文件的编译版本。

  • dmlc 会将驱动程序 DML 和开发板 DML 编译为原生格式,并将其用于静态绑定。它仍会生成 .cml 文件,供 cmc 编译器使用。
  • 驱动程序管理器将根据静态拓扑来绑定驱动程序。
  • 动态绑定将与驱动程序索引分离,并隔离到单独的绑定程序中,供总线节点使用。
  • 静态绑定将作为驱动程序管理器的子结构与资源解析分开。
  • 自动生成的 .bind 和 .cml 文件将被移除,dmlc 将仅发出一个临时 cml 文件,供 cmc 编译器使用。

第 5 阶段:其他增强功能

驱动程序代码生成

dmlc 工具会生成特定于语言的脚手架代码(例如 C++ 头文件或 Rust 模块),这些代码会直接编译到驱动程序的二进制文件中。此生成的框架会根据 Driver DML 文件自动执行资源获取样板(例如映射 MMIO、连接到 FIDL 服务或注册中断),但不会拥有驱动程序的生命周期,也不会取代标准 Driver Framework ABI。

驱动程序作者通过其驱动程序的初始化或 Start() 函数(扩展点)内的强类型访问器与此基架进行交互。使用此生成的基架是可选的,但强烈建议使用。预计采用过程将逐步推进。

与组件框架集成

DML 文件和 CML 文件之间的差异可以随着时间的推移而消除,尤其是当 DML 文件包含的添加内容被证明有用时。随着组件框架采用更多 DML 功能,可以使用标准组件框架基元从驱动程序管理器中分流更多静态绑定逻辑。

我们预计会将多个 DML 概念“上游”到标准 CML 和组件框架基元中,例如:

  • 服务功能实例的过滤支持:提供一种标准机制,让使用者能够根据元数据或标识符,区分从同一提供方路由的同一服务协议的多个实例。
  • 嵌套配置/元数据架构:允许组件直接在其清单中定义丰富的结构化配置或载荷架构。

非静态注意事项

并非驱动程序实例化的所有方面都可以在组装时静态得知。 有几个重要的用例需要明确说明,以便系统的其余部分能够过渡到静态拓扑假设。

动态总线上的静态已知驱动程序:

从技术上讲,某些 USB 设备和许多 PCI 设备必须通过总线协议进行“发现”,但在我们对产品的理解中,它们仍然是静态组件 - 我们可以保证它们始终会被发现。我们可以像对待无法动态发现的总线设备(例如 I2C 总线上的设备)一样对待此类设备。唯一的区别在于,设备的实际地址可能会发生变化,但在使用命名连接时,总线驱动程序将有足够的信息将连接路由到正确的设备。

此用例涵盖需要主板提供边带资源的所有设备;例如,SDIO Wi-Fi 芯片通过标准 SDIO 数据引脚进行通信,但依赖于 SoC 的带外 GPIO 中断引脚、电源启用线路和外部参考时钟。 由于物理布线固定在主板上,因此我们在主板 DML 中将这些设备视为静态已知设备,它们不需要全局动态复合匹配。

板级叠加层和组件变体

我们支持硬件配置可以是一组已知选项之一的开发板。例如,我们可能有一个主板的两个不同显示面板,并在启动时使用 strap 引脚或 I2C 读取来发现哪个面板存在。在这种情况下,开发板配置仍然可以是静态的,只是我们加载的配置可能会发生变化。我们建议枚举可能加载到设备上的所有可能的主板配置,并像往常一样在组装时验证所有这些配置。如何支持组件变体的语法将在这些开发板迁移时确定,但可能如下所示:

  • 所有候选变体(例如 display_panel_vendor_a 和 display_panel_vendor_b)都在主板 DML 中声明(通过条件/变体组),以便 dmlc 和 Assembly 在构建时验证每个可能的变体路由,并将所有候选驱动程序打包到同一系统映像中。
  • 在启动时,拓扑选择器(由电路板修订版本/strap 引脚通知)会激活驱动程序管理器中的匹配变体子图,或者单个驱动程序会根据探测到的 strap/I2C ID 绑定并选择活跃的硬件配置。

完全动态发现的驱动因素

对于真正的热插拔设备(例如大多数 USB 设备以及某些 WLAN 设备),必须动态绑定一组有限的驱动程序。幸运的是,这些设备具有以下特征:

  • 它们存在于没有其他资源要求的总线上,因此只有一个功能来源:总线驱动程序
  • 它们有标准的身份标识方式

    这些特性使我们能够创建仅限于总线驱动程序的更简单的绑定程序。系统会为总线驱动程序提供一个有限的驱动程序索引,并且该驱动程序可以动态添加子节点,这些子节点会立即绑定到指定的驱动程序,从而实质上将动态绑定限制为驱动程序图上的隔离节点。

目前,我们还没有支持 ACPI 等完全动态框架的计划。

性能

DML 不会产生任何运行时开销。所有阶段完成后,静态编译时映射会消除启动期间的动态搜索。

工效学设计

“Roughing Out”工作流

工程师无需编写复杂的 C++ 板级驱动程序来连接引脚、电源轨和时钟,而是可以立即“粗略设计”板级。它们将标准硬件参考架构 (.dts) 映射到单个板 DML 文件中,通过驱动程序 DML 中声明的逻辑名称直接绑定资源。

减少框架管道

通过依赖生成的代码,开发者可以避免在 Start() 中手动提取服务、解析 MMIO 或注册传出目录。dmlc 流水线会生成大部分此类标准框架管道,从而简化驱动程序的启动流程。

向后兼容性

  • 共存阶段:旧版复合驱动程序和绑定规则将与新 DML 驱动程序共存。

安全注意事项

  • 自动化沙盒:对 .dml 文件进行额外验证,有助于防止人为配置错误。dmlc 会自动强制执行最低可行沙盒,直接根据声明的输入和输出编译 Bedrock 路由字典。

隐私注意事项

此提案不涉及用户个人数据。

测试

  • 工具链验证:dmlc 将通过单元测试进行验证,以确保正确解析架构属性,并准确生成 .cm 文件和生成的基架。
  • 系统集成测试:主板验证测试将确保节点拓扑、属性和功能图在基础架构发生变化时保持不变。
  • 黄金测试:我们将纳入基于复合节点规范和配置黄金的测试,以防止生成的开发板绑定中出现意外回归。

文档

  • 开发者指南:撰写“DML 使用入门”教程,向开发者展示如何使用 fx driver create 从头开始启动其第一个驱动程序。
  • 参考规范:添加 DML YAML 架构和 Board DML 属性映射规则的参考规范。
  • 迁移指南:专门撰写一份指南,介绍如何将现有驱动程序、绑定和开发板配置迁移到 DML 模型。

缺点、替代方案和未知因素

缺点: * 增加了构建复杂性:增加了构建系统的编译和代码生成阶段的复杂性。 * 降级的主板启动移植:目前,主板启动严重依赖于供应商提供的 .dts 文件。即使存在 Fuchsia 特有的绑定差异,标准设备树也支持针对供应商资料进行直接差异比较和移植。由于 Board DML 引入了完全独立的架构,因此会显著增加开发板启动工程师的前期手动验证/转换负担。

考虑过的替代方案

添加到现有 CML 清单

我们曾考虑将实例命名和类型化数据架构直接构建到 CML 中。不过,在原型设计期间,在核心组件框架内迭代架构定义既缓慢又存在风险。从 bind 迁移还涉及添加许多临时选项,这会给 cml 编译器带来大量变动。DML 则是提供了一个过渡沙盒。我们计划全面评估所有成功的 DML 功能,以便将其纳入上游 CML,长期目标是取代大部分驱动程序 DML。

使用 Fuchsia 专用架构扩展 Devicetree

将所有开发板转换为标准设备树并将绑定规则更改为兼容性字符串会简化绑定,但会丢弃驱动程序接收正确实例所需的服务拓扑信息。 虽然当前的 Devicetree 部署成功证明了声明式开发板配置的价值,但将 Linux devicetree 调整为与 Fuchsia 兼容的功能仍需要使用定制的访问者程序付出相当大的努力。DML 简化了这一启动过程。通过预先将设备树重新格式化为 Fuchsia 原生格式,我们可以直接将硬件资源映射到组件框架功能;这样,无需将标准 .dts 文件转换为 Fuchsia 专用方言,即可在编译时立即验证驱动程序兼容性。

未知数

  • 架构演变和版本控制:目前尚未指定驱动程序 DML 和主板 DML 如何处理跨 API 级别的架构演变和向后兼容性。
  • 不匹配故障模式:当驱动程序 DML 和主板 DML 不一致时(例如,缺少功能别名或元数据架构不匹配),我们预计这会导致 dmlc 编译期间发生硬故障,以避免静默运行时错误。确切的错误显示和不匹配处理需要进一步设计。
  • 在主板编译阶段和最终系统组装阶段之间定义最佳验证边界。

在先技术和参考资料

  • RFC-0192:Fuchsia 上的设备树。
    • 请注意,此 RFC 覆盖了用户空间驱动程序对设备树的需求。
  • Linux Devicetree 规范:使用 devicetree 节点进行声明式硬件表示。