Driver Manifest Language Compiler (`dmlc`)

dmlc is the compiler for the Driver Manifest Language (DML) in Fuchsia's Driver Framework v2 (DFv2).

In DFv2, authoring device drivers and board drivers historically required maintaining multiple disconnected manifest files with duplicate information:

Component Manifests (.cml) specifying runner, binary path, service routing, and capabilities.
Bind Rules (.bind) specifying device matching bytecode and composite parent node definitions.
Board configurations (.fidl) and metadata serialization code.

DML consolidates these declarations into a single, unified JSON5 manifest (.dml). dmlc compiles this single source of truth into valid .cml, compiled .bind rules, board FIDL binaries, and auto-generated C++ / Rust metadata parser libraries.

Features

Unified Manifests: Define component lifecycle, service capabilities, and hardware bind rules in one file.
Hardware Bus Blocks: Native support for Platform Bus, PCI, USB, ACPI, and Devicetree.
Composite Binding: Automatic parent node binding, optional parents, and match_name: true matching.
Conditional Branching: Declarative one_of branches and accept value lists.
Automatic Init Step Filtering: Automatically configures init step bind rules (fuchsia.gpio.Init, etc.) and filters them out of runtime CML.
Schema-Driven Metadata Parsers: Auto-generates type-safe C++ and Rust parsers from embedded Draft-07 JSON Schemas.
Board Topology Compilation: Compiles board manifests, capability offers, and metadata mappings directly to FIDL board configs.

Schema & Validation

The official JSON Schema for DML files is located at:

src/devices/tools/dmlc/dml.schema.json

It is a Draft-07 JSON Schema providing syntax definitions and editor autocomplete for:

Driver manifests (name, program, use, capabilities, expose, include, config)
Board manifests (children, offer, metadata_mappings)
Bus blocks (pci, usb, acpi)
Composite parents and inline bind blocks (bind, requirements)

For full syntax reference, see the DML Reference Documentation.

Command-Line Usage

The dmlc binary supports two subcommands: compile-driver and compile-board.

1. Compile Driver Manifest (`compile-driver`)

Compiles a driver .dml file into .cml, .bind, and optional metadata parsers:

dmlc compile-driver <input.dml> \
  --cml-output <output.cml> \
  --bind-output <output.bind> \
  --h-output <output.h> \
  --cc-output <output.cc> \
  --rs-output <output.rs> \
  --namespace <namespace>

Options:

input_file (positional): Path to the input .dml file.
--cml-output: Path to the generated Component Manifest (.cml).
--bind-output: Path to the generated Bind source file (.bind).
--h-output: Path to the generated C++ metadata parser header (.h).
--cc-output: Path to the generated C++ metadata parser implementation (.cc).
--rs-output: Path to the generated Rust metadata parser source (.rs).
--namespace: Optional C++ namespace for generated metadata classes.

2. Compile Board Configuration (`compile-board`)

Compiles a board .dml manifest (and its shards) into a board CML, board bind rules, and serialized FIDL board configuration:

dmlc compile-board <board.dml> \
  --out-dir <out_dir> \
  --cml-output <board.cml> \
  --bind-output <board.bind> \
  --fidl-output <board-config.fidl> \
  --driver-dml <driver1.dml> \
  --driver-dml <driver2.dml>

Options:

input_file (positional): Path to the root board .dml file.
--out-dir: Output directory for generated artifacts.
--cml-output: Path to the generated board .cml.
--bind-output: Path to the generated board .bind.
--fidl-output: Path to the serialized fuchsia.hardware.platform.bus/BoardConfig FIDL binary.
--driver-dml: Additional driver DML files providing metadata schemas.

Driver Manifest vs Board Manifest

Driver Manifest (`compile-driver`)

Used by individual device drivers (standalone or composite).

{
  name: "acpi-battery",
  include: [
    "//sdk/lib/driver/compat/compat.shard.cml"
  ],
  program: {
    compat: "driver/acpi-battery.so",
    colocate: "true",
    default_dispatcher_opts: [ "allow_sync_calls" ]
  },
  use: [
    {
      service: "fuchsia.hardware.interrupt.Service",
      name: "irq000"
    },
    {
      service: "fuchsia.hardware.acpi.Service",
      name: "acpi",
      primary: true,
      bind: {
        banjo: "fuchsia.acpi.BIND_PROTOCOL.DEVICE",
        acpi: {
          hid: "PNP0C0A"
        }
      }
    }
  ]
}

Board Manifest (`compile-board`)

Used by board drivers (e.g. vim3.dml, test-board.dml) to instantiate platform devices, route capabilities, and aggregate device properties into board-level metadata.

{
  name: "vim3",
  program: {
    driver_name: "vim3-dml",
    bind: {
      service: "fuchsia.hardware.platform.bus.Service",
      transport: "Driver",
      vid: "fuchsia.khadas.platform.BIND_PLATFORM_DEV_VID.KHADAS",
      pid: "fuchsia.khadas.platform.BIND_PLATFORM_DEV_PID.VIM3"
    }
  },
  include: [
    "buttons.shard.dml",
    "gpio.shard.dml"
  ],
  metadata_mappings: [
    {
      metadata_id: "fuchsia.hardware.gpio.Metadata",
      aggregations: [
        {
          service: "fuchsia.hardware.gpio.Service",
          field: "pins"
        }
      ]
    }
  ]
}

Testing & Verification

Run the unit tests for dmlc:

fx test dmlc_bin_test

Format code:

fx format-code

Driver Manifest Language Compiler (dmlc)

Features

Schema & Validation

Command-Line Usage

1. Compile Driver Manifest (compile-driver)

2. Compile Board Configuration (compile-board)