To be efficient in navigating the code base inform the agents of the basics of the repo layout, where skills can be found and a very quick overview of the source code, coding and commit styles.
Signed-off-by: Alex Bennée <[email protected]> --- v3 - split AGENTS.md into two commits --- .gitignore | 1 + AGENTS.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/.gitignore b/.gitignore index 61fa39967b5..4ccba871d16 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ .git-submodule-status .clang-format .gdb_history +.plan cscope.* tags TAGS diff --git a/AGENTS.md b/AGENTS.md index 133225957e0..3fd56fe3309 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,3 +21,64 @@ are treated as security vulnerabilities. In brief these are: - **Common devices for Virtualization**: e.g. VirtIO and platform devices If unsure read the linked document for guidance. + +## Repo Layout +- **Build Directory**: QEMU uses out of tree builds, by default the `build` sub-directory is used. +- **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`). +- **Documentation**: Developer docs live in `docs/devel`. +- **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks. + +## Agent Skills (see `.agents/skills`) +You should use the following specialized skills for common tasks: + +## Source Code Layout (see `docs/devel/codebase.rst`) +- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code. +- **`audio/`**: Host audio backends. +- **`authz/`**: QEMU Authorization framework. +- **`backends/`**: Host resource backends (RNG, memory, crypto). +- **`block/`**: Block layer, image formats (qcow2, raw), and protocol drivers. +- **`chardev/`**: Character device backends (TCP, serial, mux, etc.). +- **`crypto/`**: Cryptographic algorithms and framework. +- **`disas/`**: Disassembler support for various architectures. +- **`dump/`**: Guest memory dump implementation. +- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS). +- **`fpu/`**: Software floating-point emulation. +- **`gdbstub/`**: Remote GDB protocol support. +- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, `hw/pci`) or architecture. +- **`include/`**: Global header files, mirroring the source tree layout. +- **`io/`**: I/O channels framework. +- **`linux-user/` & `bsd-user/`**: User-space process emulation. +- **`migration/`**: VM migration framework. +- **`monitor/`**: HMP and QMP monitor implementations. +- **`nbd/`**: Network Block Device server and client code. +- **`net/`**: Networking stack and host backends. +- **`plugins/`**: TCG introspection plugins core. +- **`qapi/`**: QAPI schema and code generation infrastructure. +- **`qga/`**: QEMU Guest Agent. +- **`qom/`**: QEMU Object Model implementation. +- **`replay/`**: Deterministic record/replay support. +- **`rust/`**: Rust integration and Rust-based device models. +- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc. +- **`system/`**: Core system-level emulation logic (replaces `softmmu`). +- **`target/`**: CPU-specific emulation (ISA translation, CPU state). +- **`tcg/`**: The Tiny Code Generator (JIT) backends. +- **`tests/`**: Test suites (qtest, unit, functional, tcg). +- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice). +- **`util/`**: Low-level utility functions and data structures. + +## Code Style (see `docs/devel/style.rst`) +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100). +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions). +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file. +- **C Comments**: Use `/* ... */` only. No `//` comments. +- **Naming**: `snake_case` for variables/functions; `CamelCase` for types/enums. +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`). No `malloc`. +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors. +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` for Rust. + +## Commit Style +- **Small Commits**: Favour small discreet commits changing one thing. +- **Maintain Bisectability**: Each commit must compile and pass basic tests. +- **Separate Refactoring**: Split code movement or style fixes from functional changes. +- **Commit Messages**: Use a concise subject line, followed by a body explaining "why" (not just "what"). +- **Signed-off-by**: Every commit must have a `Signed-off-by` line. -- 2.47.3
