在驱动程序加载失败时进行调试

本指南提供了在新驱动程序中无法加载时进行调试的最佳实践。 紫红色系统。

检查您的驱动程序当前是否在系统中运行

在 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 系统中加载的驱动程序时，请考虑执行以下步骤：

  1. 检查组件清单。
  2. 在驱动程序框架中注册驱动程序。
  3. 验证绑定规则是否正确。

1. 检查组件清单

对于将组件视为驱动程序的 Fuchsia 系统，组件的 runner 字段在 组件清单 (.cml) 必须设置为 driver，例如：

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

2. 在驱动程序框架中注册驱动程序

接下来，确认您的组件在 Fuchsia 系统中已列为驱动程序。

要使某个组件被识别为驱动程序，您需要将该组件明确注册为 作为 Fuchsia 系统中的驱动程序。如果某个组件在系统中未显示为驱动程序， 这意味着驱动程序框架不知道该组件，因此 此类组件绝不会考虑用于驱动程序绑定。因此，让您的 应该将新组件作为驱动程序显示在 Fuchsia 系统中， 编写新驱动程序。

如需在 Fuchsia 系统中将组件注册为驱动程序，请执行以下操作：

  1. 将 Fuchsia 软件包（包含驱动程序组件）上传到您的 Fuchsia 软件包服务器。

  2. 在系统中将该组件注册为驱动程序：

    ffx driver register <URL>

    将 URL 替换为 Fuchsia 软件包服务器中的组件网址，例如：

    ffx driver register fuchsia-pkg://fuchsia.com/my_example#meta/my_new_driver.cm

  3. 查看系统中当前注册（但不一定正在运行）的驱动程序列表：

    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 系统中的所有节点及其节点属性，请运行以下命令：

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);

如需详细了解此宏，请参阅实现驱动程序钩子 驱动程序 Codelab。