Shorten the document and ensure the criteria and rationale are upfront to avoid checklist scanning. Signed-off-by: Josh Boyer <[email protected]>
9.0 KiB
AGENTS.md
Guidance for AI coding agents (Claude Code, Codex, etc.) working in this repository. Humans should start with README.md; this file restates the contribution rules in the operational order an agent needs them. License-acceptability questions — whether a particular license text is acceptable for inclusion — are governed by LICENSE-CRITERIA.md.
What this repository is
This is linux-firmware, the upstream collection of binary firmware images loaded by the Linux kernel at runtime. It is not a normal software project:
- The payload is normally binary blobs rather than source you build here —
though contributors may provide source, and it's welcome where the firmware
owner permits it (see
keyspan_pda/for a built-from-source example). The large majority are redistributed binaries. - The most important file is
WHENCE— a hand-maintained manifest that records the origin, license, and redistribution terms of every file. - The repository's core value is licensing provenance, not code. Most of the rules below exist to keep that provenance accurate and auditable.
Upstream lives at https://gitlab.com/kernel-firmware/linux-firmware.git.
Golden rules (read before any change)
-
Every file in git must be accounted for — almost always by a
WHENCEentry. Adding a firmware blob without one breaks the build; removing or renaming one without updatingWHENCEdoes too. There are two kinds of exception:- Repository tooling/metadata (this file,
README.md,check_whence.py, etc.) is registered in theknown_filesallowlist insidecheck_whence.py. - License texts live in the
LICENSES/directory and are accounted for by being referenced from aLicence:line inWHENCE(e.g.See LICENCE.foo for details.) — not by aFile:entry.
If
make checkreports a file is unaccounted for, place it in the right bucket above. Don't add tooling or license files toWHENCEasFile:entries to silence a check (see "Things to leave alone"). - Repository tooling/metadata (this file,
-
Never invent license information. The license and the redistributability of a blob are facts that come from the firmware's owner — usually conveyed in the submitter's commit and
Signed-off-by. If you don't have it, don't guess. Surface the gap to the user instead. When evaluating whether a license text is acceptable, apply the criteria in LICENSE-CRITERIA.md sections 3.1–3.3 — do not guess at acceptability, and do not fabricate the underlying license facts. -
Always run
make checkbefore considering a change complete (see below). -
Preserve the
Signed-off-byline. It is a legal attestation of the right to redistribute. Never add, fabricate, or alter one on someone's behalf. -
Don't edit binary firmware files. Agents add, move, link, or remove blobs and document them; they do not modify blob contents.
The most common task: adding or updating a firmware file
- Place the blob(s) in the appropriate vendor/driver subdirectory (e.g.
qcom/,cirrus/,intel/). Match the directory convention of similar existing files. - Add a stanza to
WHENCE(see "WHENCE format" below) declaring the file and its license. Group it with related entries; keep the file roughly ordered as the surrounding content is. - If the firmware needs a new license, the license text must go in the
LICENSES/directory. PreferLICENSES/LICENSE.<vendor>for new files (LICENSES/LICENCE.<vendor>also exists in the tree and is still accepted, but new files should use theLICENSE.<vendor>spelling). Reference it fromWHENCEwithSee LICENSE.<vendor> for details.using the bare filename;check_whence.pyresolves it underLICENSES/. The license text must meet the criteria in LICENSE-CRITERIA.md section 3; new license texts require maintainer review (see section 5). - Run
make check. - Commit with a
Signed-off-byfrom someone authoritative on the license, and — if an agent helped produce the change — a trailer noting AI involvement (e.g.Assisted-by:). See "Commit conventions".
WHENCE format
WHENCE is parsed by check_whence.py, so the syntax is load-bearing. The
keywords that matter:
Driver: <name> - <description>— human-readable section header.File: <path>— a binary firmware file tracked in git. This is the usual one.RawFile: <path>— a file shipped verbatim (not converted to ihex form).Link: <linkname> -> <target>— a symlink. The target is relative to the link's directory.check_whence.pyverifies the target exists and that links don't point at other links.Source: <path>— source for firmware that is compiled here (rare).Version:/Info:— optional metadata lines.Licence:/License:— the license terms. Either name an inline word (e.g.Redistributable,GPLv2) or refer out withSee <LICENSE-file> for details.Referenced license files live in theLICENSES/directory and are cited by bare filename (the checker resolves the path); the file must exist there.
Spaces in paths are backslash-escaped (e.g. foo\ bar.bin).
Block structure. WHENCE is a series of blocks separated by a delimiter
line of dashes. A block opens with one or more Driver: lines, then one or
more sections separated by blank lines. A section is a group of
File:/RawFile: entries, optionally annotated, closed by a Licence: line.
By convention:
- If a
Driver:block for your device already exists, add your files to it instead of starting a duplicate block. - A
Version:/Info:line annotates theFile:directly above it. - A
Licence:line applies to the files in its section. This grouping is a convention for human readers —check_whence.pydoes not enforce which files aLicence:covers — so keep each section's license unambiguous. A license/section may precede its firmware files if that reads more naturally.
Study a few existing stanzas in WHENCE before writing a new one — matching an
existing pattern is the safest approach.
Validation: make check
Run make check before considering any change complete. It runs
pre-commit run --all-files — the same gate CI enforces — covering the
WHENCE↔tree check plus shell, Python, and Markdown linting. Treat
make check as the single source of truth; don't invoke the individual
checkers directly, so the rule set can grow without this doc going stale.
If pre-commit isn't installed: pip install pre-commit.
Note: the WHENCE check reads git ls-files, so stage new files
(git add) before running make check — otherwise they're invisible to the
check and it reports a phantom mismatch.
Commit conventions
- Subject line style:
<vendor/area>: <imperative summary>, e.g.qcom: Update DSP firmware for qcs8300 platformorcirrus: cs35l56: Add firmware for Cirrus Amps for a Dell laptop. - A
Signed-off-by:line is mandatory and must come from someone with authority over the firmware's licensing (typically from within the owning company). CI (ci-fairy check-commits --signed-off-by) rejects commits without it. Do not add one yourself — ask the user. - Include a firmware changelog in the commit message where possible — what changed in this firmware revision (fixes, new device support, version bumps). For binary blobs the commit message is often the only human-readable record of the change, so capture whatever the vendor provides.
- If an AI agent assisted in producing the commit, record it with a trailer
such as
Assisted-by: <tool/model>(an equivalentCo-developed-by:/Co-Authored-By:is fine). The exact tag isn't critical; surfacing that AI was involved is. - Never include a
CONFIDENTIALITY STATEMENTanywhere in the commit or MR; per README that causes the firmware to be rejected outright. - New work goes on a branch and is submitted as a GitLab MR, an emailed git
binary diff, or a pull request to
[email protected].
Repository tooling (don't reinvent these)
copy-firmware.sh— installs firmware to a destdir perWHENCE(used bymake install/install-xz/install-zst). Supports optional compression.dedup-firmware.sh— replaces duplicate installed files with symlinks (make dedup).build_packages.py— builds.deb/.rpm(make deb/make rpm); templates incontrib/templates/.make dist— builds a release tarball.contrib/process_linux_firmware.py— maintainer-side processing helper.
Things to leave alone unless explicitly asked
- The
known_files/executable_filesallowlists insidecheck_whence.py: only touch them when you are genuinely adding a new top-level tooling file, and understand you're changing the validator itself. - License text files (
LICENSE.*/LICENCE.*): treat as authoritative legal text. Add new ones when a new license is needed; don't reword existing ones.