AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Build and Test

The build system is Meson (the legacy Makefile still works but is deprecated).

# Configure and build
meson setup build
meson compile -C build

# Run all tests
meson test -C build

# Run a specific test suite (libfdt, dtc, fdtget, fdtput, fdtdump, fdtoverlay, pylibfdt, utilfdt, dtbs_equal)
meson test -C build dtc
meson test -C build libfdt

# Legacy make (deprecated, still functional)
make
make check          # all tests
make checkm         # tests under valgrind

Optional build dependencies: libyaml (>= 0.2.3) for YAML output, valgrind for memory checking, swig + python3-dev for pylibfdt.

Architecture

The repo contains three main components:

dtc (Device Tree Compiler)

Compiles device tree source (.dts) to binary (.dtb) and vice versa. The pipeline is: parse source → live tree → flatten to blob (or reverse).

  • Parsing: dtc-lexer.l (flex) + dtc-parser.y (bison) produce a live tree from .dts source. flattree.c reads .dtb blobs. fstree.c reads /proc/device-tree style filesystem trees. yamltree.c writes YAML output.

  • Live tree (livetree.c, dtc.h): In-memory representation as struct node / struct property trees with labels, phandles, and source position tracking. The struct data type carries property values with type markers and cross-reference markers.

  • Checks (checks.c): ~50 semantic checks registered via WARNING(), ERROR(), and CHECK() macros into a check_table[]. Each check declares prerequisite checks, forming a DAG. Checks validate DT conventions (node naming, property types, interrupt structures, etc.). Use -W/-E flags to promote/demote.

  • Output: flattree.c writes .dtb blobs and assembler output. treesource.c writes .dts source.

libfdt (Flat Device Tree library)

C library for reading/writing .dtb blobs in-place, dual-licensed GPL-2.0-or-later OR BSD-2-Clause. Used in bootloaders, kernels, and hypervisors where the full compiler isn't available.

  • fdt_ro.c — read-only access (property lookup, node traversal)
  • fdt_rw.c — read-write modification of existing blobs
  • fdt_sw.c — sequential-write creation of new blobs
  • fdt_wip.c — “write in place” operations (in-place modification)
  • fdt_overlay.c — device tree overlay application
  • fdt_check.c — blob validation (fdt_check_full)
  • fdt_addresses.c — address/size cell helpers
  • version.lds — exported symbol list; new public functions must be added here

libfdt is designed to be embeddable: Makefile.libfdt can be included by external build systems. The FDT_ASSUME_MASK controls safety vs. performance tradeoffs (see libfdt_internal.h).

pylibfdt

SWIG-generated Python bindings for libfdt (pylibfdt/libfdt.i). Functions not supportable by SWIG should be behind #ifndef SWIG in libfdt.h.

Tests

Tests live in tests/. The test runner is tests/run_tests.sh which defines test groups: libfdt_tests, dtc_tests, fdtget_tests, fdtput_tests, fdtoverlay_tests, pylibfdt_tests, etc.

Individual C test programs link against libfdt and use helpers from tests/testutils.c. Binary test trees are built from assembler macros in tests/trees.S via tests/dumptrees.c — if you modify tests/test_tree1.dts, you must also update tests/trees.S.

AI Contribution Policy

See the “AI Coding Assistants” section in CONTRIBUTING.md. Key rules:

  • Do not add Signed-off-by tags — only humans can certify the DCO
  • Use Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] for attribution in commit messages
  • The human submitter is responsible for reviewing all AI-generated code and ensuring license compliance
  • Do not add Co-authored-by tags.

Tagging a New Release

Releases use the vMAJOR.MINOR.PATCH tag format (e.g., v1.7.2).

An AI agent can prepare the release; the human maintainer reviews, adds Signed-off-by, and signs the tag.

  1. Update VERSION.txt and commit — run the prepare script:

    scripts/prepare-release X.Y.Z

    This updates VERSION.txt and creates the version bump commit (without Signed-off-by, per the AI contribution policy).

  2. Draft the tag message — write it to a temporary file (e.g., tag-message.txt) for the maintainer to review. The format is:

    DTC X.Y.Z

Changes since vPREV include:
 * Component
   - Change description
   - ...

    Group changes by component (dtc, libfdt, pylibfdt, fdtget, fdtoverlay, Build, General, etc.) with a bullet per notable change. Generate the changelog from git log vPREV..HEAD.

  3. Human review — the maintainer reviews the commit and tag message, then runs the finalize script which amends the commit to add Signed-off-by, creates the signed annotated tag, pushes the release commit and tag to origin, and optionally uploads to kernel.org via kup:

    scripts/finalize-release tag-message.txt

Agents must never run scripts/finalize-release or scripts/kup-dtc. These perform signing, push, and upload operations that only a human maintainer may execute.

Coding Conventions

  • License: GPL-2.0-or-later for dtc tools; (GPL-2.0-or-later OR BSD-2-Clause) for libfdt
  • SPDX identifiers on every file
  • C style follows kernel conventions: tabs for indentation, lower_case names
  • Compiler warnings are errors (-Werror)
  • libfdt functions return negative FDT_ERR_* codes on failure (never errno)