RFC-0287:透過 DML 進行設定驅動的驅動程式架構

RFC-0287:透過 DML 建立設定導向的驅動程式架構
狀態已接受
區域
  • 駕駛
說明

使用 Driver Markup Language 的設定導向架構。

問題
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2026-08-04
評論日期 (年-月-日)2026-09-22

問題描述

這項提案能解決什麼問題?

目前的 Fuchsia 驅動程式架構要求開發人員在多個檔案中協調設定資訊,例如相容字串、裝置屬性、介面和能力轉送。這種高度分散的模型會產生「協調稅」,嚴重拖慢硬體啟動和驅動程式庫開發速度。

具體來說,驅動程式庫程式的設定目前最多可來自六個不同的位置,其中有幾個位置包含重複的資訊,且需要驅動程式庫程式作者保持多個檔案同步:

  1. 繫結規則 (.bind):定義驅動程式管理員繫結程式用於比對驅動程式庫與裝置節點的條件,但也包含重要的標籤資訊。
  2. 元件資訊清單 (.cml):宣告驅動程式庫需要使用、提供或公開的功能,這些功能必須與父項提供的功能和公開的功能相對應。
  3. 建構系統 (BUILD.gn):指定驅動程式庫及其繫結身分的實體目標、依附元件和封裝規則。
  4. 主機板驅動程式 (C++ 或 devicetree):手動例項化子節點、註冊實體屬性 (MMIO、IRQ),並繫結至相符的屬性。
  5. 驅動程式原始碼:以程式輔助方式擷取資源,並連線至驅動程式庫 Start() 區塊內驅動程式和元件架構提供的服務,並依賴硬式編碼索引或字串 ID,這些 ID 必須與主機板驅動程式庫和資訊清單中宣告的字串名稱和索引相符。
  6. FIDL:驅動程式設定和作業所需的中繼資料,通常會編碼為 FIDL 結構。

重複中繼資料的影響

  • 在建構或組裝階段,許多檔案不會相互驗證,因此同步處理偏差的可能性會增加。資源名稱拼寫錯誤或索引不相符,通常會編譯成功,但會在執行階段失敗,導致驅動程式庫無法載入,或在作業期間無法存取資源。
  • 由於無法單純透過硬體定義完成,因此啟動新的 SoC 或主機板會遇到較高的摩擦。這需要編寫及修改板級驅動程式庫程式碼,手動比對、轉譯實體資源,並將其轉送至特定驅動程式庫程式執行個體。
  • 由於繫結系統難以設定和偵錯,因此通常不清楚驅動程式庫未繫結的原因。由於繫結條件是任意的,且有許多不同的模式可用於比對驅動程式,因此可能不清楚需要哪些資訊。
  • Devicetree 訪客:雖然許多 Fuchsia 主機板目前使用 devicetree,其中包含所有主機板專屬設定資料,但 devicetree 仍需由「訪客」程式解譯,以便在啟動時將 devicetree 資料剖析為 Fuchsia 所需的格式。雖然訪客必須彌補 Linux Devicetree 結構定義與 Fuchsia 能力模型之間的落差,但在執行階段以 C++ 維護及執行這個轉譯層,會增加作業負擔,並導致產生的拓撲更難以靜態檢查及驗證。
  • 自動化和工具障礙:驅動程式庫設定檔分散在多個檔案,無論是人類或 AI 驅動程式庫作者,在生成程式碼和偵錯時都會面臨挑戰。驅動程式庫作者必須同時成功修改及同步處理 C++ 程式碼、設定 JSON (.cml) 和特定領域繫結語法 (.bind)。

這項提案不打算解決哪些問題?

這項提案不會取代熱插拔匯流排 (例如 USB 和 PCIe) 的執行階段動態探索和繫結,因為裝置存在和比對屬性只能在執行階段判斷。

Driver DML 適用於整個樹狀結構,Board DML 則僅適用於靜態硬體拓撲。我們不會取代 x86 平台上的執行階段 ACPI 探索;x86 主機板會繼續依賴 ACPI 主機板驅動程式庫,在啟動時探索硬體並建構裝置節點。

Zircon 的 phys 開機 shim 保持不變,會繼續使用系統啟動載入程式提供的 Devicetree,用於早期核心開機和記憶體預留。

這項提案並未消除開發人員編寫驅動程式核心功能硬體暫存器/邏輯程式碼的需求。

最後,這項提案不會規定驅動程式架構中繼資料結構定義定義、匯總或反序列化。該架構將在並行設計文件中討論。

背景

駕駛的核心需求

基本上,驅動程式庫與作業系統之間的關係可分為幾項不同的需求。

傳入資源:

  • 核心: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. Board Specific:提供板卡專屬資訊,說明驅動程式庫的連接方式、功能來源,以及提供的板卡專屬設定資料。例如,顯示驅動程式庫的:

    • 兩項時鐘服務會從主機板的時鐘控制器轉送,其中 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)。
  • 架構相關的驅動程式庫建構設定和驅動程式庫基礎設定樣板,是從驅動程式 DML 檔案產生。
  • 驅動程式專屬設定資料、匯總中繼資料、資源身分和依附元件解析,都會根據主機板 DML 進行,而非驅動程式之間的父項與子項關係。

這項異動有幾項優點:

  • 在組裝時已知並經過驗證的靜態設定,可大幅簡化主機板啟動程序。
  • 提升靜態偵錯能力:由於 DML 會繼續為 cmc 產生標準 .cml 資訊清單,現有的元件架構工具 (例如 cmc 驗證、審查和 ffx 元件) 可以驗證驅動程式庫元件之間的靜態能力轉送,而組裝時 DML 驗證器和 ffx 驅動程式庫則會處理硬體專屬限制 (MMIO、IRQ、接腳) 和執行階段診斷
  • 設定更容易理解:移除 devicetree 訪客,並將設定整合為兩組檔案,無論是人類或 AI,都能更輕鬆地理解驅動程式庫設定。

相關人員

講師:Abdulla Kamar (@abdulla)

審查者:

  • 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. Driver Markup Language (DML) 與 CML

驅動程式視為元件,因此必須指定元件資訊清單 (CML),列舉元件所需的功能類型。不過,CML 並未提供驅動程式庫所需的完整資訊,無法完全解析連線。目前,驅動程式庫架構會使用多個其他資訊來源來補充 CML。DML 的設計大致上是 CML 結構定義的超集,並加入了一些重要面向。使用獨立但類似的設定語言,可讓我們在 DML 中加入暫時性功能,滿足各種驅動程式的需求,進而快速完成轉換。完成完整遷移後,我們會盡可能將 DML 的新增功能合併至 CML,理想情況下會達成完整整合,進而將 DML 完全合併回 CML。

執行個體身分。

驅動程式通常需要多個不同的服務執行個體。舉例來說,顯示控制器驅動程式庫可能需要兩條獨立的時鐘線 (一條用於像素時序,一條用於 DSI 時序管道) 以及一條 I2C 匯流排。所有功能都由核心驅動程式透過一般 FIDL 服務提供。

標準 CML 仰賴複合節點的繫結,在多個單一能力轉送至驅動程式庫時,轉送正確的功能執行個體。DML 則允許 use 區塊指定本機簡稱別名。

Driver DML

作者會為每個驅動程式庫定義單一 .dml 檔案,指定平台依附元件。dmlc 編譯器會在編譯時,根據驅動程式庫程式 DML 產生必要的元件資訊清單 (提供給元件架構)、拓撲繫結比對器,以及特定語言的鷹架。

Driver DML 會將目前透過 .bind 和 .cml 檔案組合表示的資訊,合併至統一的 .dml 檔案。

這項整合可讓驅動程式 DML 在轉送多個相同類型的服務時,同時指定身分和能力需求。如要連結兩個 clock.Service 執行個體,必須在繫結檔案中宣告 CML 能力,並手動比對節點和自訂字串屬性。而使用 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 檔案中的唯一性,而不必與其他驅動程式進行全域協調。

驅動程式專屬設定

驅動程式專屬設定剖析是執行階段恐慌和驅動程式庫樣板的重要來源。標準 CML 沒有機制可定義元件之間傳遞的任意酬載位元組內部結構,目前依賴 FIDL 結構定義複雜的設定。

在 DML 中,驅動程式可以直接在定義的能力下方,建立巢狀設定結構定義。在合約中明確宣告結構定義後,dmlc 就能在建構/組裝時,驗證主機板 DML 中編碼的資料,以及接收驅動程式庫專屬設定的驅動程式庫是否一致。

(確切的設定結構定義和序列化格式待定,視平行設計而定)。

過渡結構定義

目前的 DML 結構定義包含多個過渡期填充碼,用於與目前的驅動程式架構互動。舉例來說,繫結屬性會暫時嵌入能力 use 區塊旁,以略過離散的 .bind 檔案,而「主要父項」概念則嚴格保留,以滿足舊版複合節點初始化。這些建構項目只是暫時性的,隨著我們轉向原生元件架構轉送,並逐步淘汰複合節點和非複合節點之間的區隔,這些建構項目將完全淘汰。

由於 DML 正在整個樹狀結構中積極推出,因此本 RFC 避免鎖定詳盡的結構定義規格。隨著後續遷移作業公開新的極端案例,確切的結構合約將繼續演變。

2. Board DML

主機板設定目前仰賴 Linux 樣式的裝置樹狀結構或 C++ 主機板驅動程式。主機板驅動程式會指定手動子節點例項化和結構化樣板;裝置樹狀結構會提供一般 DTS,需要「訪客」剖析層將屬性轉譯為 Fuchsia 專屬架構建構。

Board DML 會以嚴格的宣告式、組裝時驗證拓撲取代這兩種範式。Board DML 與驅動程式庫程式 DML 共用 JSON5 語法,但提供互補元件:驅動程式大多使用 use 陣列宣告需求,Board DML 則會配置 children 和 offer 區塊,在驅動程式之間點對點轉送功能。

主機板 DML 檔案支援包含 shard,可讓基本 SoC 設定在各種主機板變化版本之間共用及重複使用。不過,由於板 DML 代表 Fuchsia 專屬設定,因此在啟動新的 Fuchsia 裝置時,將 Linux 裝置樹狀結構轉換為板 DML,會是驗證硬體的重要時機。

宣告式能力轉送本質上隱含硬體啟動順序和依附元件圖。此外,Board DML 設定可指定子元件是否應延遲到依附元件滿足後再啟動,或使用延遲依附元件解析功能啟用平行驅動程式庫啟動。為維持依附元件順序,驅動程式管理工具會保留執行元件角色,並安排驅動程式庫啟動順序。

在 Board DML 中:

如要例項化驅動程式庫,必須有對應的 Entry Board 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)。
  • 驅動程式 Scaffold 生成:輸出驅動程式庫專屬程式碼,處理與 Driver DML 指定資源連線時涉及的所有樣板,大幅簡化驅動程式庫設定程式碼。不同語言繫結的確切結構模式 (例如 C++ 物件繼承與 Rust 組合) 將在後續的 RFC 中定案。

組裝期間:

  • 系統會提供 Rust 程式庫 (assembly_dml),並連結至組件二進位檔。
  • 系統會交叉驗證主機板和驅動程式 DML,確保所有連線都有效,且驅動程式庫程式具備必要功能。
  • 目前的元件架構驗證工具 (例如硬體資源邊界強制執行和結構化設定驗證) 將擴充,以套用至新的靜態驅動程式。
  • 系統會產生靜態節點圖,格式為 json5,由驅動程式管理員擷取。

實作

推出作業分為五個主要階段,確保平台穩定:

第 1 階段:CML 和繫結自動生成

  • dmlc 會剖析驅動程式庫 DML,產生驅動程式庫 CML 和 .bind 檔案。
  • dmlc 也會編譯主機板 DML,產生 Fuchsia 啟動時,主機板驅動程式庫會擷取的 fidl 輸入。Board 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 為基礎的板會切換至板 DML,並刪除對應的 C++ 板驅動程式和 Devicetree 訪客管道。x86 ACPI 主機板驅動程式庫在這個階段維持不變,會繼續在執行階段探索裝置及發布節點。請注意,Zircon 的 physboot shim 仍維持不變,該 shim 會使用開機載入器提供的裝置樹,進行早期核心/實體記憶體初始化。如要將動態開機載入器提供的執行階段參數 (例如主機板修訂版本綁定) 橋接至靜態主機板 DML 拓撲,請參閱「非靜態考量事項和未知事項」一節。

階段 4:直接原生編譯和 Bedrock 整合

Driver Framework 將更新,直接使用編譯版本的 Board DML 和 Driver DML 檔案。

  • dmlc 會將驅動程式 DML 和主機板 DML 編譯為原生格式,用於靜態繫結。它仍會產生 cmc 編譯器會使用的 .cml 檔案。
  • 驅動程式管理員會根據靜態拓撲繫結驅動程式。
  • 動態繫結會與驅動程式庫索引分開,並隔離至獨立的繫結程式,可供匯流排節點使用。
  • 靜態繫結將與資源解析分開,做為驅動程式管理器的子結構。
  • 系統會移除自動產生的 .bind 和 .cml 檔案,且 dmlc 只會發出暫時的 cml 檔案,供 cmc 編譯器使用。

階段 5:其他強化功能

生成驅動程式碼

dmlc 工具會產生特定語言的鷹架程式碼 (例如 C++ 標頭或 Rust 模組),直接編譯到驅動程式庫的二進位檔中。這個產生的鷹架會根據驅動程式 DML 檔案,自動執行資源取得的樣板 (例如對應 MMIO、連線至 FIDL 服務或註冊中斷),但不會擁有驅動程式庫的生命週期,也不會取代標準驅動程式架構 ABI。

驅動程式作者會透過驅動程式庫程式初始化或 Start() 函式 (擴充點) 內的強型別存取子,與這個鷹架互動。您可以選擇是否使用這個產生的鷹架,但強烈建議您使用。預計會逐步完成。

與元件架構整合

DML 和 CML 檔案之間的差異可以隨著時間解決,尤其是當 DML 檔案包含的新增內容證明有用時。隨著元件架構採用更多 DML 功能,驅動程式管理器工具可使用標準元件架構原始物件,卸載更多靜態繫結邏輯。

我們預計將多個 DML 概念「上游」至標準 CML 和元件架構原始物件,例如:

  • 服務能力執行個體的篩選支援:提供標準機制,讓消費者根據中繼資料或 ID,區分從同一供應商轉送的相同服務通訊協定的多個執行個體。
  • 巢狀設定/中繼資料結構定義:允許元件直接在資訊清單中定義豐富的結構化設定或酬載結構定義。

非靜態考量

並非所有驅動程式庫例項化層面都能在組裝時靜態得知。有幾個重要的用途需要明確說明,才能讓系統其餘部分轉換為靜態拓撲假設。

動態匯流排上的靜態已知驅動程式:

某些 USB 裝置和許多 PCI 裝置在技術上必須透過匯流排通訊協定「探索」,但就我們對產品的理解,這些裝置仍是靜態元件,我們可以保證這些裝置一律會被探索到。這類裝置可以視為無法動態偵測的匯流排裝置,例如 I2C 匯流排上的裝置。唯一的差別在於裝置的實際位址可能會變更,但使用具名連線時,匯流排驅動程式會有足夠的資訊,可將連線轉送至適當的裝置。

這個用途涵蓋所有需要主機板提供邊帶資源的裝置,例如 SDIO Wi-Fi 晶片會透過標準 SDIO 資料接腳通訊,但依賴 SoC 的頻外 GPIO 中斷接腳、電源啟用線和外部參考時鐘。由於實體線路固定在主機板上,因此在主機板 DML 中,我們會將這些裝置視為靜態已知裝置,不需要全域動態複合比對。

電路板疊加層和元件變化版本

我們支援硬體設定為已知選項之一的開發板。舉例來說,我們可能會有兩個不同的顯示面板,並使用綁定接腳或 I2C 讀取,找出開機時顯示的是哪一個。在這種情況下,棋盤設定仍可保持靜態,只是載入的設定可能會變更。我們建議列舉裝置上可能載入的所有電路板設定,並照常在組裝時驗證所有設定。支援元件變化的語法會在遷移這些面板時決定,但可能如下所示:

  • 所有候選變化版本 (例如 display_panel_vendor_a 和 display_panel_vendor_b) 都會在主機板 DML 中宣告 (透過條件式/變化版本群組),以便 dmlc 和 Assembly 在建構時驗證每個可能的變化版本路徑,並將所有候選驅動程式套件到同一個系統映像檔中。
  • 在啟動時,拓撲選取器 (由主機板修訂版本/strap 接腳提供資訊) 會在驅動程式管理工具中啟用相符的變體子圖,或單一驅動程式庫會根據探測到的 strap/I2C ID 繫結並選取有效的硬體設定。

完全動態探索的驅動因素

對於真正可熱插拔的裝置 (例如大多數 USB 裝置以及部分 WLAN 裝置),必須動態繫結一組有限的驅動程式。幸好,這些裝置具有以下特性:

  • 這類裝置位於匯流排上,沒有其他資源需求,因此只有一個功能來源:匯流排驅動程式
  • 他們有標準的身分識別方式

    這些特性可讓我們建立更簡單的繫結程式,僅限於匯流排驅動程式。匯流排驅動程式會提供有限的驅動程式庫索引,並可動態新增子節點,這些子節點會立即繫結至指定的驅動程式庫,基本上會將動態繫結限制在驅動程式庫圖表上的獨立節點。

目前我們不打算支援 ACPI 等完全動態的架構。

效能

DML 不會產生任何執行階段負擔。所有階段完成後,靜態編譯時間對應會消除啟動期間的動態搜尋。

人體工學

Board「Roughing Out」工作流程

工程師不必編寫複雜的 C++ 電路板驅動程式來連接接腳、電源軌和時鐘,而是可以立即「粗略設計」電路板。這類檔案會將標準硬體參考結構定義 (.dts) 對應至單一板 DML 檔案,並直接透過驅動程式庫 DML 中宣告的邏輯名稱繫結資源。

減少架構管道

開發人員可以仰賴產生的程式碼,避免手動擷取服務、剖析 MMIO,或在 Start() 中註冊傳出目錄。dmlc 管道會產生大部分的標準架構管道,簡化驅動程式庫啟動流程。

回溯相容性

  • 共存階段:舊版複合驅動程式和繫結規則會與新的 DML 驅動程式共存。

安全性考量

  • 自動化沙箱:對 .dml 檔案進行額外驗證,有助於避免人為設定錯誤。dmlc 會自動強制執行最低可行沙箱機制,直接從宣告的輸入和輸出內容編譯 Bedrock 轉送字典。

隱私權注意事項

這項提案不會處理使用者個人資料。

測試

  • 工具鍊驗證:dmlc 將透過單元測試進行驗證,確保正確剖析結構定義屬性,並精確產生 .cm 檔案和產生的鷹架。
  • 系統整合測試:主機板驗證測試可確保節點拓撲、屬性和能力圖在基礎架構變更期間保持不變。
  • 黃金測試:我們將整合複合節點規格和設定黃金測試,防止產生的板繫結發生非預期的迴歸。

說明文件

  • 開發人員指南:撰寫「DML 入門」教學課程,向開發人員說明如何使用 fx driver create 從頭開始建立第一個驅動程式庫。
  • 參考規格:新增 DML YAML 結構定義和 Board DML 屬性對應規則的參考規格。
  • 遷移指南:撰寫指南,專門說明如何將現有的驅動程式、繫結和主機板設定遷移至 DML 模型。

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

缺點: * 增加建構複雜度:增加建構系統編譯和程式碼產生階段的複雜度。* 板級啟動移植作業降級:目前的板級啟動作業高度仰賴供應商提供的 .dts 檔案。即使 Fuchsia 專屬繫結有所差異,標準 Devicetree 仍可針對供應商附屬資料進行簡單的差異比較和移植。由於 Board DML 採用完全獨立的結構定義,因此會大幅增加主機板啟動工程師的前期手動驗證/轉譯負擔。

考慮過的替代方案

新增至現有 CML 資訊清單

我們曾考慮直接在 CML 中建構執行個體命名和類型資料結構定義。不過,在原型設計期間,反覆調整核心元件架構中的結構定義定義,不僅速度緩慢,而且風險較高。從繫結遷移也涉及新增多個臨時選項,這會導致 cml 編譯器大量流失。而是提供過渡沙箱。我們計畫評估所有成功的 DML 功能,並將其納入 CML,長期目標是取代大部分的驅動程式 DML。

使用 Fuchsia 專屬結構定義擴充 Devicetree

將所有主機板轉換為標準裝置樹狀結構,並將繫結規則變更為相容性字串,可簡化繫結作業,但會捨棄驅動程式庫接收正確執行個體所需的服務拓撲資訊。雖然目前的 Devicetree 推出作業成功證明宣告式主機板設定的價值,但將 Linux devicetree 調整為 Fuchsia 相容功能,仍需要使用客製化訪客程式進行相當多的努力。DML 可簡化這項啟動程序。只要預先將裝置樹狀結構重新格式化為 Fuchsia 原生格式,就能直接將硬體資源對應至元件架構能力;這樣一來,系統就能在編譯時間立即驗證驅動程式庫相容性,而不必將標準 .dts 檔案轉換為 Fuchsia 專用方言。

未知

  • 結構定義演變和版本管理:目前尚未指定 Driver DML 和 Board DML 如何處理結構定義演變,以及跨 API 級別的回溯相容性。
  • 不相符失敗模式:如果驅動程式 DML 和主機板 DML 不一致 (例如缺少能力別名或中繼資料結構定義不相符),我們預期這會導致 dmlc 編譯期間發生硬失敗,避免執行階段發生無訊息錯誤。確切的錯誤顯示和不相符處理方式需要進一步設計。
  • 定義電路板編譯階段和最終系統組裝階段之間的最佳驗證界線。

既有技術和參考資料

  • RFC-0192:Fuchsia 上的 Devicetree。
    • 請注意,這項 RFC 會覆寫使用者空間驅動程式對裝置樹狀架構的需求。
  • Linux Devicetree 規格:使用 devicetree 節點宣告硬體表示法。