mirror of
https://github.com/dgibson/dtc.git
synced 2026-07-10 13:29:48 -04:00
docs: Add AI contribution guidelines
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>
This commit is contained in:
David Gibson
parent
f57e7df35d
commit
5c35036b2c
2 changed files with 144 additions and 0 deletions
96
AGENTS.md
Normal file
96
AGENTS.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
# 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)
|
||||
|
|
@ -77,3 +77,51 @@ from people handling and transporting the patch, but were not involved
|
|||
in its development. SoB chains should reflect the **real** route a
|
||||
patch took as it was propagated to the maintainers, with the first SoB
|
||||
entry signalling primary authorship of a single author.
|
||||
|
||||
## AI Coding Assistants
|
||||
|
||||
AI tools helping with dtc/libfdt development must follow the standard
|
||||
contribution process described in this document.
|
||||
|
||||
### Licensing and Legal Requirements
|
||||
|
||||
All contributions must comply with the project's licensing requirements:
|
||||
|
||||
* All code must be compatible with GPL-2.0-or-later
|
||||
* All libfdt code must also be compatible with BSD-2-Clause
|
||||
* Use appropriate SPDX license identifiers
|
||||
|
||||
### Signed-off-by and Developer Certificate of Origin
|
||||
|
||||
AI agents MUST NOT add Signed-off-by tags. Only humans can legally
|
||||
certify the Developer Certificate of Origin (DCO). The human submitter
|
||||
is responsible for:
|
||||
|
||||
* Reviewing all AI-generated code
|
||||
* Ensuring compliance with licensing requirements
|
||||
* Adding their own Signed-off-by tag to certify the DCO
|
||||
* Taking full responsibility for the contribution
|
||||
|
||||
### Attribution
|
||||
|
||||
When AI tools contribute to development, proper attribution helps track
|
||||
the evolving role of AI in the development process. Contributions
|
||||
should include an `Assisted-by` tag in the following format:
|
||||
|
||||
```
|
||||
Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `AGENT_NAME` is the name of the AI tool or framework
|
||||
* `MODEL_VERSION` is the specific model version used
|
||||
* `[TOOL1] [TOOL2]` are optional specialized analysis tools used
|
||||
(e.g., coccinelle, sparse, smatch, clang-tidy)
|
||||
|
||||
Basic development tools (git, gcc, make, editors) should not be listed.
|
||||
|
||||
Example:
|
||||
```
|
||||
Assisted-by: Claude:claude-3-opus coccinelle sparse
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue