[PATCH] AGENTS.rst: Add AI coding assistant reference for kernel development

[Kenneth Daily]

Provide a condensed reference for AI coding agents working on the
Linux kernel, covering the codebase structure, build system, coding
style, maintainer lookup, patch submission process, key kernel
programming patterns, testing frameworks, and documentation
conventions.

This complements the existing coding-assistants.rst by serving as a
quick-start reference that agents can consult before each task,
reducing the likelihood of common mistakes like incorrect indentation,
forgetting Signed-off-by rules, or using GitHub pull requests instead
of email-based patch submission.

Assisted-by: opencode:big-pickle

Signed-off-by: Kenneth Daily <kenneth.daily@xxxxxxxxxxxxx>
---
 AGENTS.rst | 355 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 355 insertions(+)
 create mode 100644 AGENTS.rst

diff --git a/AGENTS.rst b/AGENTS.rst
new file mode 100644
index 000000000..7c163b206
--- /dev/null
+++ b/AGENTS.rst
@@ -0,0 +1,355 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+AGENTS: AI Coding Assistant Reference for Linux Kernel Development
+==================================================================
+
+This file provides AI coding agents with a condensed reference for working
+on the Linux kernel. It is not a formal kernel document; see
+:ref:`Documentation/process/coding-assistants.rst <coding_assistants>` for
+the official policy on AI contributions.
+
+Before contributing, all AI tools MUST read these in order:
+
+1. Documentation/process/coding-assistants.rst
+2. Documentation/process/coding-style.rst
+3. Documentation/process/submitting-patches.rst
+4. Documentation/process/development-process.rst
+5. Documentation/process/submit-checklist.rst
+
+Repository Map
+==============
+
+::
+
+    arch/          Architecture-specific code (x86, arm, riscv, loongarch, etc.)
+    block/         Block layer (I/O schedulers, bio, blk-mq)
+    crypto/        Kernel crypto API (ciphers, hashes, AEAD)
+    Documentation/ Sphinx RST documentation
+    drivers/       Device drivers (~37k files: net, gpu, iio, media, etc.)
+    fs/            Filesystems (ext4, btrfs, xfs, vfs, etc.)
+    include/       Kernel headers (linux/, uapi/, asm-generic/, dt-bindings/)
+    init/          Kernel init (main.c, version.c)
+    io_uring/      Async I/O framework
+    ipc/           Inter-process communication (msg, sem, shm)
+    kernel/        Core kernel (sched, signal, time, irq, workqueue, rcu, pm)
+    lib/           Library routines (crc, lzo, math, test_*.c)
+    mm/            Memory management (vmscan, slub, ksm, page_alloc)
+    net/           Networking stack (ipv4, ipv6, tcp, wireguard, mac80211)
+    rust/          Rust-for-Linux abstractions and examples
+    samples/       Sample code for various subsystems
+    scripts/       Build scripts, checkpatch.pl, kconfig, coccinelle
+    security/      LSM framework (SELinux, AppArmor, Smack, TOMOYO)
+    sound/         ALSA and ASoC audio subsystem
+    tools/         Userspace tooling (perf, objtool, selftests, bpftool)
+    usr/           initramfs generation
+    virt/          Virtualization (KVM)
+
+Build System
+============
+
+The kernel uses a three-layer build system:
+
+**Kconfig** -- ``Kconfig`` files define config symbols (``CONFIG_FOO``).
+Top-level ``Kconfig`` sources per-subsystem files. Use ``make menuconfig``
+(or ``nconfig``, ``xconfig``) to configure. See Documentation/kbuild/.
+
+**Kbuild** -- ``Kbuild`` files (or ``Makefile`` in some directories) drive
+the build. See ``Kbuild`` at root and ``Documentation/kbuild/makefiles.rst``.
+
+**Makefile** -- Top-level ``Makefile`` dispatches to subdirectories::
+
+    obj-y               += kernel/
+    obj-$(CONFIG_NET)   += net/
+    obj-$(CONFIG_RUST)  += rust/
+
+Typical targets::
+
+    make defconfig             # default config
+    make -j$(nproc)            # build kernel
+    make -j$(nproc) modules    # build modules only
+    make htmldocs              # build documentation (requires Sphinx)
+    make M=path/to/driver      # build a single module
+    make mrproper              # full clean
+
+Cross-compilation::
+
+    make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- defconfig
+
+Coding Style (abridged)
+=======================
+
+See ``Documentation/process/coding-style.rst`` for the full guide.
+
+- **Indentation**: tabs only, 8-character width (not 4, not spaces)
+- **Line length**: 80 characters preferred (100 is sometimes tolerated)
+- **Braces**: K&R style (open brace on same line for functions):
+  ``int foo(void) {``
+- **Braces required** for all blocks with multiple statements; optional
+  for single-statement blocks only if the condition fits one line
+- **Spaces**: after ``if``, ``switch``, ``case``, ``for``, ``while``;
+  not after ``sizeof``, ``typeof``, ``alignof``, or ``__attribute__``
+- **Function declarations**: return type on own line in ANSI C style
+- **Typedefs**: avoid them for struct/enum/union; use ``struct foo`` directly
+- **Comments**: C89 ``/* ... */`` style; do not use C99 ``// ...``
+- **Macros**: UPPERCASE; macros with multiple statements use ``do { } while (0)``
+- **NULL pointers**: test ``if (!ptr)`` not ``if (ptr == NULL)``
+- **SPDX**: every file must start with ``// SPDX-License-Identifier: GPL-2.0``
+  (or the appropriate identifier)
+- **Kernel-doc**: use ``/**`` for exportable function/struct documentation
+- **GNUC**: do not use ``__attribute__`` directly; use ``__printf`` etc.
+
+Run ``scripts/checkpatch.pl`` on every patch before submission.
+
+Subsystem Maintainers & MAINTAINERS
+====================================
+
+The ``MAINTAINERS`` file at the root maps files to maintainers. Format::
+
+    LINUX I2C SUBSYSTEM
+    M:      Wolfram Sang <wsa@xxxxxxxxxx>
+    R:      Andi Shyti <andi.shyti@xxxxxxxxxx>
+    L:      linux-i2c@xxxxxxxxxxxxxxx
+    S:      Maintained
+    F:      Documentation/i2c/
+    F:      drivers/i2c/
+    F:      include/linux/i2c.h
+    F:      include/linux/i2c-dev.h
+    K:      i2c
+
+Find the right maintainer with::
+
+    ./scripts/get_maintainer.pl <path-to-patch>
+
+The catch-all for unowned paths (including root-level files) is "THE REST",
+maintained by Linus Torvalds.
+
+Patch Submission
+================
+
+Kernel patches are submitted via email to maintainers and relevant lists.
+Never use GitHub pull requests.
+
+**Creation** -- One logical change per patch. Multi-patch series for
+complex changes. Each patch must stand alone and build cleanly::
+
+    git format-patch --cover-letter -M origin/main
+
+**Commit message format**::
+
+    subsystem: one-line summary (imperative mood, <= 75 chars)
+
+    Detailed explanation of what and why. Include problem description,
+    user-visible impact, and technical rationale.
+
+    Signed-off-by: Your Name <you@xxxxxxxxxxx>
+
+**Required trailer tags**:
+
+``Signed-off-by``
+  Developer Certificate of Origin (``git commit -s``). AI agents MUST
+  NOT add this tag — only humans can certify DCO (see
+  coding-assistants.rst).
+
+``Suggested-by``, ``Reviewed-by``, ``Tested-by``, ``Acked-by``,
+``Reported-by``, ``Co-developed-by``, ``Fixes:``, ``Closes:``,
+``Link:``, ``Cc:`` -- used as appropriate.
+
+``Assisted-by``
+  Required for AI-assisted contributions per
+  ``Documentation/process/coding-assistants.rst``. Format::
+
+    Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+
+**Sending**::
+
+    git send-email --to=<maintainer> --cc=<list> <patches>
+
+Or use ``scripts/get_maintainer.pl`` output::
+
+    git send-email --to-cmd='./scripts/get_maintainer.pl --nogit-fallback' \\
+        --cc-cmd='./scripts/get_maintainer.pl --nogit-fallback --nomultiline' \\
+        *.patch
+
+See ``Documentation/process/email-clients.rst`` for client configuration.
+
+**Before submitting**:
+
+- Build cleanly with ``make -j$(nproc)``
+- Run ``scripts/checkpatch.pl`` on every patch
+- Test with appropriate config options
+- For new features, add tests (KUnit or kselftest)
+- For bug fixes, include a ``Fixes:`` tag
+
+Key Kernel Programming Patterns
+===============================
+
+Error handling -- Return a negative errno on failure::
+
+    if (!ptr)
+        return -ENOMEM;
+
+Use the kernel's standard error codes (``include/linux/errno.h``):
+``-EINVAL``, ``-ENOMEM``, ``-EIO``, ``-EPERM``, ``-EFAULT``, ``-EBUSY``,
+``-ENOSYS``, ``-ENODEV``, ``-EAGAIN``, ``-ERESTARTSYS`` (for signal
+handling in syscalls).
+
+Linked lists -- Doubly-linked list (``include/linux/list.h``)::
+
+    struct list_head my_list;
+    INIT_LIST_HEAD(&my_list);
+    list_add_tail(&entry->list, &my_list);
+    list_for_each_entry(entry, &my_list, list) { ... }
+
+Reference counting -- Use ``kref`` (``include/linux/kref.h``)::
+
+    kref_init(&obj->refcount);
+    kref_get(&obj->refcount);
+    kref_put(&obj->refcount, obj_release);
+
+Wait/RCU -- Use ``rcu_assign_pointer`` for writers, ``rcu_dereference``
+for readers. For sleepable RCU readers, use ``srcu``.
+
+IDR/IDA -- Integer ID management (``include/linux/idr.h``)::
+
+    idr_alloc(&idr, ptr, 0, 0, GFP_KERNEL);
+    ptr = idr_find(&idr, id);
+    idr_remove(&idr, id);
+
+Memory allocation -- Always check return::
+
+    ptr = kmalloc(sizeof(*ptr), GFP_KERNEL);
+    if (!ptr)
+        return -ENOMEM;
+
+Use ``GFP_KERNEL`` for process context, ``GFP_ATOMIC`` for atomic context,
+``GFP_KERNEL_ACCOUNT`` for user-triggered allocations that should be
+charged to the user's cgroup.
+
+String handling -- Prefer ``kstrto*`` over ``sscanf``::
+
+    ret = kstrtoint(buf, 10, &val);
+    if (ret)
+        return ret;  /* already a negative errno */
+
+Use ``sysfs_emit`` in sysfs show functions:
+    sysfs_emit(buf, "%d\n", val);
+
+Printing -- Use logging helpers::
+
+    pr_info("msg %d\n", val);
+    pr_warn("msg %d\n", val);
+    pr_err("msg %d\n", val);
+    dev_info(dev, "msg %d\n", val);   /* preferred for drivers */
+
+Timekeeping -- Use ``ktime_get_*`` and ``ns_to_timespec64``::
+
+    u64 ts = ktime_get_ns();
+    ktime_t kt = ktime_get();
+
+Do not use ``do_gettimeofday`` or ``struct timeval`` (deprecated).
+
+Concurrency -- Standard locking::
+
+    spin_lock(&lock);    /* atomic context */
+    mutex_lock(&lock);  /* process context (can sleep) */
+
+For reference: ``include/linux/spinlock.h``, ``include/linux/mutex.h``.
+
+Memory barriers -- Must always include a comment explaining the pairing and
+the reason for the barrier. See
+``Documentation/process/submit-checklist.rst`` item 3.
+
+Testing
+=======
+
+**KUnit** -- Unit testing framework for kernel-space code. Tests live in the
+same directory as the code under test (``lib/test_*.c``, ``fs/*/test_*.c``)::
+
+    ./tools/testing/kunit/kunit.py run
+
+To run manually, enable ``CONFIG_KUNIT`` and individual ``*_KUNIT_TEST``
+options, then boot the kernel. See ``Documentation/dev-tools/kunit/index.rst``.
+
+**kselftest** -- Kernel self-tests live under ``tools/testing/selftests/``::
+
+    make -C tools/testing/selftests TARGETS=<subsystem> run_tests
+
+See ``Documentation/dev-tools/kselftest.rst``.
+
+**0-day / Kernel Test Robot** -- Intel's automated build/boot testing
+service. Patches sent to mailing lists are automatically tested.
+
+Documentation
+=============
+
+Kernel documentation uses Sphinx (reStructuredText). Build locally::
+
+    make htmldocs     # HTML output in Documentation/output/
+    make pdfdocs      # PDF output
+
+API documentation uses kernel-doc comments in C source files formatted with
+``/**``. See ``Documentation/doc-guide/kernel-doc.rst``.
+
+Do not invent new documentation formats or put markdown under
+``Documentation/``. Use ``.rst`` files and reference them from
+``Documentation/index.rst`` or the appropriate subsystem index.
+
+SPDX & Licensing
+================
+
+Every kernel source file must start with an SPDX identifier::
+
+    // SPDX-License-Identifier: GPL-2.0
+
+The kernel is licensed under GPL-2.0-only. Contributions must be compatible.
+See ``Documentation/process/license-rules.rst``.
+
+Kernel-specific Conventions
+===========================
+
+- Configuration: use ``Kconfig``, not Makefile conditionals for feature gating
+- Device Tree: bindings go in ``Documentation/devicetree/bindings/`` with
+  YAML schema (``.yaml``) and matching ``.dts`` updates
+- UAPI: user-space API headers live under ``include/uapi/``; they are
+  installed by ``make headers_install``
+- Static analysis: use sparse (``make C=1``), smatch, coccinelle
+- Deprecated APIs: do not introduce new users of symbols listed in
+  ``Documentation/process/deprecated.rst``
+
+Common Pitfalls
+===============
+
+- Forgetting ``-ENOMEM`` / ``-EINVAL`` checks after allocation/user input
+- Using ``//`` comments instead of ``/* */``
+- Mixing spaces for indentation (use ``:set noet ts=8`` in vim)
+- Adding ``Signed-off-by`` as an AI agent (forbidden per coding-assistants.rst)
+- Sending pull requests on GitHub instead of emailing patches
+- Forgetting ``Fixes:`` tag for bug fixes
+- Patching coding style of existing code as a standalone change (considered noise)
+
+Quick Reference: Build & Style Commands
+=======================================
+
+::
+
+    # Configure and build
+    make defconfig && make -j$(nproc)
+
+    # Build a specific module
+    make M=drivers/i2c/busses/
+
+    # Check coding style
+    ./scripts/checkpatch.pl --file <path>
+
+    # Find maintainers
+    ./scripts/get_maintainer.pl <path>
+
+    # Static analysis
+    make C=1                         # sparse
+    make coccicheck                  # coccinelle
+
+    # Build documentation
+    make htmldocs
+
+    # Run KUnit tests
+    ./tools/testing/kunit/kunit.py run
-- 
2.43.0