mirror of
https://github.com/dgibson/dtc.git
synced 2026-07-10 13:29:48 -04:00
5c35036b2c
Add AI coding assistant policy to CONTRIBUTING.md, modelled on the Linux kernel's coding-assistants.rst. Covers DCO/Signed-off-by restrictions, licensing requirements, and the Assisted-by attribution format. Add AGENTS.md with codebase guidance for AI coding assistants. Assisted-by: Claude:claude-opus-4-6 Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
96 lines
4 KiB
Markdown
96 lines
4 KiB
Markdown
# 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).
|
|
|
|
```sh
|
|
# 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
|
|
|
|
## 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)
|