5.4 KiB

Raw Permalink Blame History

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.

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

5.4 KiB Raw Permalink Blame History