本頁面由 Cloud Translation API 翻譯而成。

對驅動程式載入失敗時進行偵錯

本指南將針對無法在 Fuchsia 系統。

在系統上檢查驅動程式目前是否正在執行

在 Fuchsia 中，當驅動程式庫與節點，代表硬體或虛擬裝置。一旦比對成功，驅動程式庫會開始運作，並向系統中的其他元件提供服務。

如要查看您的 Fuchsia 系統是否已載入 (目前執行中) 驅動程式庫，執行下列指令：

ffx driver list --loaded

這個指令會顯示系統中載入的驅動程式清單，例如：

$ ffx driver list --loaded
fuchsia-boot:///#meta/bus-pci.cm
fuchsia-boot:///#meta/fvm.cm
fuchsia-boot:///#meta/hid.cm
fuchsia-boot:///#meta/intel-rtc.cm
fuchsia-boot:///#meta/netdevice-migration.cm
fuchsia-boot:///#meta/network-device.cm
fuchsia-boot:///#meta/pc-ps2.cm
fuchsia-boot:///#meta/platform-bus-x86.cm
fuchsia-boot:///#meta/platform-bus.cm
fuchsia-boot:///#meta/ramdisk.cm
fuchsia-boot:///#meta/sysmem.cm
fuchsia-boot:///#meta/virtio_block.cm
fuchsia-boot:///#meta/virtio_ethernet.cm
fuchsia-pkg://fuchsia.com/virtual_audio#meta/virtual_audio_driver.cm
fuchsia-pkg://bazel.pkg.component/qemu_edu#meta/qemu_edu.cm
fuchsia-boot:///#meta/block.core.cm
fuchsia-boot:///#meta/intel-i2c-dfv2.cm

另外，如果您知道確切的驅動程式庫元件，可以使用 ffx component show 指令，查看元件狀態。例如：

$ ffx component show intel-i2c-dfv2
               Moniker: /bootstrap/boot-drivers:root.sys.platform.pt.pci.00_15_2.composite
                   URL: fuchsia-boot:///#meta/intel-i2c-dfv2.cm
                  Type: CML dynamic component
       Component State: Resolved
 Incoming Capabilities: fuchsia.boot.Items
                        fuchsia.driver.compat.Service
                        fuchsia.logger.LogSink
                        pkg
  Exposed Capabilities: diagnostics
                        fuchsia.driver.compat.Service
       Execution State: Running
          Start reason: Instance is in a single_run collection
 Outgoing Capabilities: fuchsia.driver.compat.Service

如果您發現系統未載入您的驅動程式庫，請參閱下一節的步驟可以協助你解決問題

偵錯的最佳做法

在編寫新的 Fuchsia 驅動程式庫的初始階段，您必須確認 Fuchsia 系統認定新元件為驅動程式庫。將該元件列出 Fuchsia 系統中的驅動程式庫，即可開始撰寫繫結規則讓驅動程式能夠繫結至在系統中代表目標裝置的特定節點。將驅動程式庫繫結至目標節點後 (如此一來，驅動程式庫就會在那麼接下來就進入下一句的開發階段專為驅動程式庫設計的功能

如要對無法載入 Fuchsia 系統中的驅動程式庫進行偵錯時，請考慮下列步驟：

檢查元件資訊清單。
使用驅動程式庫架構註冊驅動程式庫。
確認繫結規則正確無誤。

1. 查看元件資訊清單

如要讓 Fuchsia 系統將元件視為驅動程式庫，該元件的 runner 欄位位於元件資訊清單 (.cml) 必須設為 driver，例如：

    program: {
        runner: 'driver',
        ...
    }

2. 使用驅動程式庫程式架構註冊驅動程式

接著，請確認該元件已列為 Fuchsia 系統中的驅動程式庫。

您需要將元件明確註冊為 Fuchsia 系統中的驅動程式庫。如果元件不是在系統中顯示為驅動程式庫，代表驅動程式架構並不知道該元件系統絕對不會將這類元件視為驅動程式繫結。因此，有了並成為 Fuchsia 系統中的新元件，應該成為編寫新驅動程式庫

如要在 Fuchsia 系統中將元件註冊為驅動程式庫，請執行下列步驟：

將內含驅動程式元件的 Fuchsia 套件 (內含驅動程式庫元件) 上傳到您的 Fuchsia 套件伺服器。

注意： bazel 指令可執行建築物、上傳及註冊驅動程式庫套件組成如果您的 Fuchsia 開發環境使用 Bazel 建構系統可將此處的步驟 1 和 2 替換為 bazel run 指令。
在系統中將元件註冊為驅動程式庫：
```
ffx driver register <URL>
```
將 URL 替換為 Fuchsia 套件伺服器中的元件網址，例如：
```
ffx driver register fuchsia-pkg://fuchsia.com/my_example#meta/my_new_driver.cm
```

查看系統中目前已註冊 (但不一定正在執行) 的驅動程式清單：

ffx driver list

這個指令會輸出類似以下的輸出內容：

$ ffx driver list
fuchsia-boot:///#meta/block.core.cm
fuchsia-boot:///#meta/bus-pci.cm
fuchsia-boot:///#meta/fvm.cm
fuchsia-boot:///#meta/hid-input-report.cm
fuchsia-boot:///#meta/hid.cm
fuchsia-boot:///#meta/intel-rtc.cm
fuchsia-boot:///#meta/netdevice-migration.cm
fuchsia-boot:///#meta/network-device.cm
fuchsia-boot:///#meta/pc-ps2.cm
fuchsia-boot:///#meta/platform-bus-x86.cm
fuchsia-boot:///#meta/platform-bus.cm
fuchsia-boot:///#meta/ramdisk.cm
fuchsia-boot:///#meta/sysmem.cm
fuchsia-boot:///#meta/virtio_block.cm
fuchsia-boot:///#meta/virtio_ethernet.cm
fuchsia-boot:///#meta/zxcrypt.cm
fuchsia-pkg://fuchsia.com/virtual_audio#meta/virtual_audio_driver.cm
fuchsia-pkg://fuchsia.com/my_example#meta/my_new_driver.cm

確認新的驅動程式庫元件顯示在這份清單中。

3. 確認繫結規則正確無誤

最後，開始檢查駕駛員的繫結規則。

驅動程式的繫結規則會決定可以在 Fuchsia 系統中繫結至哪些節點。駕駛人架構只會在驅動程式與系統中特定節點的節點屬性相符時載入驅動程式。如果驅動程式已在系統中註冊，但尚未載入 (因此並未執行)，則：檢查駕駛的繫結規則，驗證其寫入是否與繫結規則相符建立 Fuchsia 系統目標節點的屬性。

如要查看 Fuchsia 系統中的所有節點及其節點屬性，請執行下列指令：

ffx driver list-devices -v

這個指令會輸出類似以下的輸出內容：

$ ffx driver list-devices -v
...
Name : I2C2
Moniker : root.sys.platform.pt.acpi.I2C2
Driver : None
6 Properties
[ 1/ 6] : Key fuchsia.BIND_ACPI_ID Value 0x000034
[ 2/ 6] : Key fuchsia.BIND_PCI_TOPO Value 0x0000aa
[ 3/ 6] : Key fuchsia.BIND_ACPI_BUS_TYPE Value 0x000001
[ 4/ 6] : Key "fuchsia.hardware.acpi.Device" Value true
[ 5/ 6] : Key fuchsia.BIND_PROTOCOL Value 0x00001e
[ 6/ 6] : Key "fuchsia.platform.DRIVER_FRAMEWORK_VERSION" Value 0x000002
...
Name : 00_15_2
Moniker : root.sys.platform.pt.pci.00_15_2
Driver : None
9 Properties
[ 1/ 9] : Key fuchsia.BIND_PROTOCOL Value 0x00001f
[ 2/ 9] : Key fuchsia.BIND_PCI_VID Value 0x008086
[ 3/ 9] : Key fuchsia.BIND_PCI_DID Value 0x009d62
[ 4/ 9] : Key fuchsia.BIND_PCI_CLASS Value 0x000011
[ 5/ 9] : Key fuchsia.BIND_PCI_SUBCLASS Value 0x000080
[ 6/ 9] : Key fuchsia.BIND_PCI_INTERFACE Value 0x000000
[ 7/ 9] : Key fuchsia.BIND_PCI_REVISION Value 0x000021
[ 8/ 9] : Key fuchsia.BIND_PCI_TOPO Value 0x0000aa
[ 9/ 9] : Key "fuchsia.platform.DRIVER_FRAMEWORK_VERSION" Value 0x000002
...

針對繫結規則進行偵錯時，建議您逐一檢視指令，確保 Fuchsia 系統包含具備正確節點屬性的節點。另外，請注意，一個節點只能與一個驅動程式庫繫結，別忘了您 Fuchsia 系統中的目標節點尚未繫結至該節點。

上述範例輸出顯示 PCI 節點和 ACPI 節點，intel-i2c 驅動程式庫可您可以按照下列方式，針對這兩個節點編寫驅動程式的繫結規則：

primary node "pci" {
    fuchsia.driver.framework.dfv2 == true;

    fuchsia.BIND_PROTOCOL == fuchsia.pci.BIND_PROTOCOL.DEVICE;
    fuchsia.BIND_PCI_VID == fuchsia.pci.BIND_PCI_VID.INTEL;
    accept fuchsia.BIND_PCI_DID {
        // For now we only add the DID for the touchpad.
        fuchsia.intel.platform.pci.BIND_PCI_DID.SUNRISE_POINT_SERIALIO_I2C2,
    }
}

node "acpi" {
    fuchsia.driver.framework.dfv2 == true;

    fuchsia.BIND_ACPI_ID == 0x000034;
    fuchsia.BIND_PCI_TOPO == 0x0000aa;
    fuchsia.BIND_ACPI_BUS_TYPE == 0x000001;
}

針對 ACPI 節點，透過視覺化的方式確認在繫結規則中指定的 ACPI 值與設定 ACPI 節點屬性的值 (如上方 ffx 指令的輸出內容所示)。如果是 PCI 節點，直接檢查 PCI 繫結程式庫，檢查值是否符合 PCI 節點的屬性值(如需更多資訊，請參閱為駕駛人編寫繫結規則)。

附錄

錯誤：找不到驅動程式庫生命週期

在 Fuchsia 系統中註冊元件成為驅動程式庫後，系統可能會顯示錯誤訊息類似以下的裝置記錄 (ffx log)：

Failed to start driver; driver lifecycle not found url=<DRIVER_URL>

如果發生此錯誤，請確認已新增 FUCHSIA_DRIVER_EXPORT() 巨集位於驅動程式庫元件的原始碼結尾，例如：

// Register driver hooks with the framework
FUCHSIA_DRIVER_EXPORT(qemu_edu::QemuEduDriver);

如要進一步瞭解這個巨集，請參閱「驅動程式庫掛鉤」一文：驅動程式程式碼研究室