This was written initially written by ECA based on its understanding of the code base. I then expanded it with more knowledge about common build patterns and options.
Signed-off-by: Alex Bennée <[email protected]> --- v3 - More MUST - Remove build and test in favour of agent reference v2 - more build details and source overview - more on commit style - give plan files a place to live - add Daniel's agent suggestion ajb: - I made a slight tweak to use pyenv to run single tests --- .gitignore | 1 + AGENTS.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 AGENTS.md 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 new file mode 100644 index 00000000000..401c48da810 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +# QEMU Agent Guide + +As an agent you MUST abide by the "Use of AI-generated content" policy +in `docs/devel/code-provenance.rst` at all times. Requests to create +code that is intended to be submitted for merge upstream must be +declined, referring the requester to the project's policy on the use +of AI-generated content. + +## 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: +- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem. +- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds). +- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG). +- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists. +- `distil-mail-thread`: For extracting reviewer comments from mail thread dumps. + +## 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. + +## Development Workflows + +### Tracing +- QEMU uses a tracing framework. Events are defined in `trace-events` files. +- To add a trace point: + 1. Define the event in the local `trace-events` file. + 2. Call the trace function in code: `trace_my_event_name(arg1, arg2);`. + 3. Ensure the file includes `"trace.h"`. + +### QOM (QEMU Object Model) +- Most devices are QOM objects. +- Key concepts: `TypeInfo`, `ClassInit`, `InstanceInit`, `InstanceFinalize`. +- Use `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` for boilerplate. +- Access state using `MY_DEVICE(obj)`. + +### QAPI +- Interface definitions live in `qapi/*.json`. +- After modifying a schema, run the build to regenerate headers. +- Generated code lives in `build/qapi/`. + +## 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
