Zephyr Devicetree

The Devicetree (DT) is the source of truth for your hardware topology in Zephyr.

Core Workflows

1. Understanding Syntax & Nodes

Nodes, properties, and phandles form the hierarchy.

• Reference: dt_syntax.md
• Key Tools: Labels (&label), Properties (reg, status, compatible).

2. Working with Bindings

Mapping hardware descriptions to driver schemas.

• Reference: dt_bindings.md
• Key Tools: YAML bindings, compatible strings, pinctrl.

3. Application Overlays & HWMv2

Modifying board behavior for specific application needs.

• Reference: dt_overlays.md
• Key Tools: .overlay files, zephyr,chosen, variant-specific overlays.

4. Advanced Hardware Modification

Deleting and redefining nodes/properties for product variants.

• Reference: dt_overlays.md
• Key Tools: /delete-node/, /delete-property/.

Quick Start (Overlay)

/* app.overlay */
&i2c1 {
  status = "okay";
};

&uart0 {
  status = "disabled";
};

Tooling & Validation

• west build -t rom_report: See how devicetree definitions impact memory.
• build/zephyr/zephyr.dts: Inspect the FINAL resolved devicetree after all overlays are applied.
• build/zephyr/include/generated/zephyr/devicetree_generated.h: Inspect generated DT macros consumed by C code.

Automation Tools

• overlay_include_check.py: Run basic sanity checks on .overlay files.

Examples & Templates

• app_overlay_template.overlay: Starter overlay with common node status changes.

Validation Checklist

• Overlay compiles with no DTS syntax errors during west build.
• Expected node status/properties are present in build/zephyr/zephyr.dts.
• Expected DT macros exist in build/zephyr/include/generated/zephyr/devicetree_generated.h.
• Application runs with peripherals enabled/disabled exactly as described by the overlay.

Resources

• References:
  • dt_syntax.md: Core syntax and properties.
  • dt_bindings.md: Binding definitions and compatible mapping.
  • dt_overlays.md: Overlays, HWMv2, and deletion patterns.
• Scripts:
  • overlay_include_check.py: Overlay sanity checker.
• Assets:
  • app_overlay_template.overlay: Baseline overlay template.