# Bind Debugger

Caution: This page may contain information that is specific to the legacy
version of the driver framework (DFv1).

The debugger can be used to run a bind rules against a particular device. It
outputs a trace of the bind rules's execution, describing why the driver
would or would not bind to the device.

You can run the debugger in the following ways:

 - **[As a host tool.](#running-the-debugger-host)** You provide the bind rules
   source file and a file listing the properties of the device. This is useful
   during bind rules development for testing the outcome of the rules against
   different combinations of node properties.
 - **[On the target device.](#running-the-debugger-target)** You specify the driver
   path and the device path within the system. This is useful for figuring out why
   a driver did or did not bind to a particular device.

Note: The debugger can only be used with bind rules written in the bind language
described in this page.

## Running the debugger as a host tool {#running-the-debugger-host}

You can run the debugger with the `--debug` option in the bind compiler.

```
fx bindc debug \
  --include src/devices/bind/fuchsia.usb/fuchsia.usb.bind \
  --debug tools/bindc/examples/gizmo.dev \
  tools/bindc/examples/gizmo.bind
```

The bind rules source and the library sources are in the formats described in
the [bind rules](/docs/development/drivers/concepts/device_driver_model/driver-binding.md#bind-rules) and
[bind libraries](/docs/development/drivers/concepts/device_driver_model/driver-binding.md#bind-libraries) sections,
respectively. The `--debug` option takes a file containing a specification of
the device to run the bind rules against.

Note: The `--debug` and `--output` options are mutually exclusive, so the C
header file will not be generated when running the compiler in debug mode.

### Device specification file {#device-specification}

The debugger takes a file specifying the device to run against the bind rules.
This specification is simply a list of key-value pairs describing the properties
of the device.

#### Example

This example device specification can be found at
[//tools/bindc/examples/gizmo.dev](/tools/bindc/examples/gizmo.dev).

```
fuchsia.BIND_PROTOCOL = fuchsia.usb.BIND_PROTOCOL.INTERFACE
fuchsia.BIND_USB_VID = fuchsia.usb.BIND_USB_VID.REALTEK
fuchsia.BIND_USB_CLASS = fuchsia.usb.BIND_USB_CLASS.VIDEO
fuchsia.BIND_USB_SUBCLASS = fuchsia.usb.BIND_USB_SUBCLASS.VIDEO_CONTROL
```

#### Grammar

```
device-specification = ( property )* ;

property = compound-identifier , "=" , value ;

compound-identifier = IDENTIFIER ( "." , IDENTIFIER )* ;

value = compound-identifier | STRING-LITERAL | NUMERIC-LITERAL | "true" | "false" ;
```

An identifier matches the regex `[a-zA-Z]([a-zA-Z0-9_]*[a-zA-Z0-9])?`.

A string literal matches the regex `”[^”]*”`, and a numeric literal matches the
regex `[0-9]+` or
`0x[0-9A-F]+`.

The bind compiler will ignore (treat as whitespace) any line prefixed by `//`,
and any multiple
lines delimited by `/*` and `*/`.

## Running the debugger on the target device {#running-the-debugger-target}

The debugger is run using its package URL. For example:

```
ffx driver debug-bind /system/driver/bt-hci-intel.so class/bt-transport/000
```

The command takes the path of the driver to debug and the path of the device to
debug it against.

### Device path

There are two ways to specify the device:

 - Its path within /dev/class, e.g. `class/bt-transport/000`.
 - Its topological path, e.g. `sys/platform/pci/00:14.0/xhci/usb-bus/003/003/ifc-000/bt_transport_usb`.

Both of the paths are relative to /dev/.

The topological path can be determined from the output of `driver dump`. For
example, tracing the path to the node `[bt_transport_usb]` in the output below
gives the topological path
`sys/platform/pci/00:14.0/xhci/usb-bus/003/003/ifc-000/bt_transport_usb`.

```
[root]
   <root> pid=3456
      [null] pid=3456 /boot/driver/builtin.so
      [zero] pid=3456 /boot/driver/builtin.so
   [misc]
      <misc> pid=3525
         [demo-fifo] pid=3525 /boot/driver/demo-fifo.so
         [ktrace] pid=3525 /boot/driver/ktrace.so
   [sys]
      <sys> pid=3369 /boot/driver/platform-bus.so
         [pci] pid=3369 /boot/driver/platform-bus-x86.so
            [00:00.0] pid=3369 /boot/driver/bus-pci.so
            [00:14.0] pid=3369 /boot/driver/bus-pci.so
               <00:14.0> pid=4384 /boot/driver/bus-pci.proxy.so
                  [xhci] pid=4384 /boot/driver/xhci.so
                     [xdc] pid=4384 /boot/driver/xhci.so
                     [usb-bus] pid=4384 /boot/driver/usb-bus.so
                        [001] pid=4384 /boot/driver/usb-bus.so
                           [001] pid=4384 /boot/driver/usb-composite.so
                              [ifc-000] pid=4384 /boot/driver/usb-composite.so
                                 [usb-hid] pid=4384 /boot/driver/usb-hid.so
                                    [hid-device-000] pid=4384 /boot/driver/hid.so
                        [002] pid=4384 /boot/driver/usb-bus.so
                           [002] pid=4384 /boot/driver/usb-composite.so
                              [ifc-000] pid=4384 /boot/driver/usb-composite.so
                                 [usb-hid] pid=4384 /boot/driver/usb-hid.so
                                    [hid-device-000] pid=4384 /boot/driver/hid.so
                        [003] pid=4384 /boot/driver/usb-bus.so
                           [003] pid=4384 /boot/driver/usb-composite.so
                              [ifc-000] pid=4384 /boot/driver/usb-composite.so
                                 [bt_transport_usb] pid=4384 /boot/driver/bt-transport-usb.so
                                    [bt_hci_intel] pid=4384 /system/driver/bt-hci-intel.so
                                       [bt_host] pid=4384 /system/driver/bt-host.so
```

It should be noted that if driver framework version 2 (DFv2) is enabled, the
node's topological path can't be determined from its place in the node graph.

## Debugger output

The output of the debugger is a trace of the bind rules' evaluation. The trace
contains information about whether each statement in the bind rules succeeded,
and why or why not. For example, if a condition statement failed because the
device did not have the required value, the debugger will output what the actual
value of the device was (or the fact that the device had no value for that
property). The trace also includes information about which branches were taken
in if statements.

### Example

The output of the debugger when running the host tool command
[above](#running-the-debugger-host) is:

```
Line 4: Condition statement succeeded: fuchsia.BIND_PROTOCOL == fuchsia.usb.BIND_PROTOCOL.INTERFACE;
Line 6: If statement condition failed: fuchsia.BIND_USB_VID == fuchsia.usb.BIND_USB_VID.INTEL
    Actual value of `fuchsia.BIND_USB_VID` was `fuchsia.usb.BIND_USB_VID.REALTEK` [0xbda].
Line 9: If statement condition succeeded: fuchsia.BIND_USB_VID == fuchsia.usb.BIND_USB_VID.REALTEK
Line 11: Accept statement succeeded.
    Value of `fuchsia.BIND_USB_CLASS` was `fuchsia.usb.BIND_USB_CLASS.VIDEO` [0xe].
Driver binds to device.
```

If you run the debugger on the Fuchsia target device, you will see similar output
information. However, information such as identifiers and source code snippets may
be missing, since the system only stores the bind rules bytecode, not the
source code.

The trace shows the outcome of each statement that was reached while executing
the bind rules:

- The device has the USB device protocol, so the first condition statement is
satisfied.
- The device's vendor ID is REALTEK, so the second branch of the if statement is
taken.
- The device has one of the two accepted classes (video), so the accept
statement is satisfied.

The debugger outputs that the driver would successfully bind to a device with
these properties.