驅動程式執行器

驅動程式庫執行元件是負責啟動驅動程式代管程序環境中執行的執行元件。

使用驅動程式庫執行元件

如要使用驅動程式庫執行元件，元件的資訊清單必須包含類似以下的 program 區塊：

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
    }
}

驅動程式庫元件的 program 區塊至少需要下列欄位：

• runner：這個欄位必須設為字串 driver。
• binary – 元件套件中驅動程式庫二進位輸出的路徑。
• bind：元件套件中編譯的繫結程式路徑。

選填欄位

除了必填欄位之外，驅動程式執行程式還會接受一組選用欄位，用於指定中繼資料或設定驅動程式庫元件的執行階段環境。

主機代管

如果 colocate 欄位設為字串 true，驅動程式庫會盡可能放入與父項驅動程式相同的驅動程式主機。不過，這只是建議。舉例來說，如果父項裝置已設定 MUST_ISOLATE，驅動程式管理員仍可能將驅動程式庫放入個別的驅動程式代管程序。在 DFv1 中，如果父項裝置是複合裝置，驅動程式庫一律會並置，在複合裝置的主要片段上設定 MUST_ISOLATE 仍可強制執行隔離。

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        colocate: "true"
    }
}

如果未指定 colocate 欄位，其值預設為字串 false。

colocate 與 host_restart_on_crash 欄位互斥。對於單一驅動程式庫，只能有其中一個值為 true。

預設調度器選項

default_dispatcher_opts 欄位提供建立驅動程式庫預設調度工具時使用的選項，例如：

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        default_dispatcher_opts: [ "allow_sync_calls" ]
    }
}

這個欄位中的選項會對應至 types.h 檔案中定義的旗標。目前支援的選項如下：

• allow_sync_calls：這個選項表示調度器可能不會與其他驅動程式共用 Zircon 執行緒。這項設定可讓驅動程式庫在調度器上進行 Banjo 或 FIDL 同步呼叫，且不會發生死鎖。

備用

如果 fallback 欄位設為字串 true，這個備用驅動程式庫只會在所有基礎驅動程式庫套件都建立索引後，才嘗試繫結。此外，如果這個驅動程式庫與節點相符，而非備用驅動程式庫也與同一節點相符，則非備用驅動程式庫會改為繫結至該節點。

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        fallback: "true"
    }
}

如果未指定 fallback 欄位，其值預設為字串 false。

下一個 vDSO

如果 use_next_vdso 欄位設為字串 true，系統就會將驅動程式庫放入驅動程式主機，並連結下一個 vdso。驅動程式也必須將 colocate 設為 true，否則系統會忽略這個欄位。

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        colocate: "true"
        use_next_vdso: "true"
    }
}

如果未指定 use_next_vdso 欄位，其值預設為字串 false。

裝置類別

device_categories 欄位會提供中繼資料，指出驅動程式庫控制的裝置類別，例如：

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        device_categories: [
            { category: "board", subcategory: "i2c" },
            { category: "sensor", subcategory: "temperature" },
        ]
    }
}

這項中繼資料可用於判定驅動程式庫在認證程序中必須通過的測試。如需裝置類別和子類別的完整清單，請參閱 FHCP 結構定義。

主機在當機時重新啟動

host_restart_on_crash 欄位會告知驅動程式庫架構，如果驅動程式意外關閉，應重新啟動驅動程式代管程序，以便驅動程式庫繫結至該節點。

包括：

• 驅動程式主機異常終止。
• 驅動程式會在執行時關閉其用戶端端點至 fuchsia.driver.framework/Node 通訊協定。

由於這會影響驅動程式代管程序，因此只有主機的根驅動程式庫可以設定。根驅動程式庫是主機建立時所用的驅動程式庫。只有在 colocate 欄位設為 false 時，才會發生這種情況。

因此，host_restart_on_crash 和 colocate 是互斥的。其中只有一個可以是驅動程式庫的 true。

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        host_restart_on_crash: "true"
    }
}

如果未指定 host_restart_on_crash 欄位，其值預設為字串 false。

當 host_restart_on_crash 為 false 時，如果驅動程式庫意外關閉，節點就會從驅動程式庫程式架構的節點拓樸中移除。

Service Connect 驗證

service_connect_validation 欄位會由驅動程式庫 SDK 的 DriverBase 使用，以便在服務能力連線上執行可用性驗證。

方法是查看可供驅動程式繫結節點使用的優惠，並確保所有 incoming()->Connect() 要求都會嘗試連線至有效的優惠。

在單一父項案例中，這項設定只會確保節點可使用服務，因為在使用者未指定任何執行個體的情況下，所有要求都會傳送至 "default" 執行個體。

在複合情況下，這可確保要求的執行個體名稱和 "default" 執行個體名稱情況，具有來自該父項的相應產品。

如果這些驗證失敗，Connect() 方法會立即傳回 ZX_ERR_NOT_FOUND，而不是建立連線，而這類連線只會在呼叫雙向方法時失敗。

{
    program: {
        runner: "driver",
        binary: "driver/example.so",
        bind: "meta/bind/example.bindbc",
        service_connect_validation: "true"
    }
}

如果未設定這個欄位，驗證功能預設為停用。

其他資訊

如要進一步瞭解如何繫結驅動程式，請參閱「驅動程式繫結」。