From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6B7D6CD4F39 for ; Thu, 14 May 2026 06:36:54 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wNPg5-0002Pe-JQ; Thu, 14 May 2026 02:36:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wNPg3-0002PC-R3 for qemu-devel@nongnu.org; Thu, 14 May 2026 02:36:11 -0400 Received: from mail-wm1-x333.google.com ([2a00:1450:4864:20::333]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wNPg1-0001o1-L4 for qemu-devel@nongnu.org; Thu, 14 May 2026 02:36:11 -0400 Received: by mail-wm1-x333.google.com with SMTP id 5b1f17b1804b1-488d2079582so77817215e9.2 for ; Wed, 13 May 2026 23:36:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778740564; x=1779345364; darn=nongnu.org; h=content-transfer-encoding:mime-version:message-id:date:user-agent :references:in-reply-to:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=34NpgzAmkivVJ3sYeBN5h3y/KeS4BVKwZ1aw2NoTVoM=; b=gwRwTqP4yh2MK7YzI3yO29zrMLxHOLffsl2GTRGVjupwTAJ5ikFZ0trNnrQL0KgqZe QZJgCxua9+1CZjoIuJF70wtSOdw8Jh6wQOfO9TCCYvWjL0bNgFxi23lB5hv4DZnThzDt ViaVEVgNt1xiRBdjPYWd2OLvHYeiHgEa980HwEPg5E0GY+GhUc394D0RAHuyyK2Fi18+ Rx4/VYxGnaGQagwqTOtG6FOQQVBLoGHwy3GvLA1r1UovWANLhpWUUSaU+8h9BhdbA1EI HCxXXrw/M7XcGfOQlzdXwD6lhul/O6Xzd7kM6LjQVhWiTenqxtWPofIEpKmOuj3w3sOG TLhg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778740564; x=1779345364; h=content-transfer-encoding:mime-version:message-id:date:user-agent :references:in-reply-to:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=34NpgzAmkivVJ3sYeBN5h3y/KeS4BVKwZ1aw2NoTVoM=; b=FQVXPJ/KsXmyTPWjkLW/3w2L4VDxt4CWTCJZnBQQC8llZiDjE5Xn9/ZzMOB1gV/C4U hHBmxmBrZgaqRcTkBgBuFxP2tyj8Zf6jXOqVLgbpx3cl7lm5/U9fK0bByTJlFwXjRE+1 4Udk+SstGmK3k/+D/rFFcjHMBQCMSZ8k7PYob9BqFB4cMqXPiim9na+0C37eIVc3VBtp HhnYol/XqgbOnJ4FANp2gPAZn6BF4iW6JmYBVIpjmLwfHK4uhmhWL3v0OOkJf52MMH0E 0kVUclWBNsEVF6ZFaAlAt9xL06dZfUS4fQQlpZkQUSRmUOnttosMy8BRPc+6Xjqs8pmN A8Fg== X-Gm-Message-State: AOJu0YwVaoCKc+STwlMpSmIX9Woh/masOvGwuWAqutt596bVhB1YqsLR ivEv1m66cutXpnep/CtE2mrkxd/j1iHCRnEx/k8LF6DCNF3IpcVq8IqtEz00kW50ttY= X-Gm-Gg: Acq92OG1kcxzufnilCitoidX0QiU17CUzZg3gnIaNxF1+mRClYexXKRwAhHE5D2fZvG qdmJzc+20j9Q6Em4d5yKIdpezO87PeKRkLeFv3rowgZ++tLt1yyVyI6IJt3P4zhzZ0aWswS3mJl VXmigzIgyRHpC3Xhx/KLiaLNVNJXTnF/Xpzfh60lIkgKqCQzhSvflZHaCK5lsM4uJGSoqOJOXkV 5QEnPmXp5FDmJfFW8HWBiH6cEyi/JA29pX11PvBEDCKbLefyJ9jpHIKmpjQXmfyIQufHijWYh0M 0gpKEL5r1ALQSWSvxTBQtAjcCLPqJ/1iE3GFufHrYee2PoJx2XkdXpAafibKVcj61WuvLppQrM6 ynOPWagfHCvrP4hbWt8OR1s0DtAglz3N6EOuQDeyo0pBQz/NfTYYFATXJdb50vEcB0wZ8vptSQB vqpJ/IhORtGAITQMfYVO23Cz74EY1kY9H99w== X-Received: by 2002:a05:600c:4746:b0:48e:635a:18d7 with SMTP id 5b1f17b1804b1-48fce7659c7mr92082785e9.0.1778740564004; Wed, 13 May 2026 23:36:04 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48fd7672ae9sm14913015e9.6.2026.05.13.23.36.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 13 May 2026 23:36:03 -0700 (PDT) Received: from draig (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id ECC315F86B; Thu, 14 May 2026 07:36:01 +0100 (BST) From: =?utf-8?Q?Alex_Benn=C3=A9e?= To: Chao Liu Cc: qemu-devel@nongnu.org, John Snow , Cleber Rosa Subject: Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU In-Reply-To: (Chao Liu's message of "Thu, 14 May 2026 10:58:03 +0800") References: <20260511170500.124211-1-alex.bennee@linaro.org> <20260511170500.124211-2-alex.bennee@linaro.org> User-Agent: mu4e 1.14.1; emacs 30.1 Date: Thu, 14 May 2026 07:36:01 +0100 Message-ID: <87bjeicxbi.fsf@draig.linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a00:1450:4864:20::333; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x333.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Chao Liu writes: > Hi Alex, > On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Benn=C3=A9e wrote: >> This was written initially written by ECA based on its understanding of = the >> code base. I then expanded it with links to the various documents and >> the general coding style. >>=20 >> Signed-off-by: Alex Benn=C3=A9e >>=20 >> --- >> v4 >> - will add AGENTS to list as we go >> - moved QOM, QAPI and trace details into qemu-code-explorer skill >> - add section on Security policy >> 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 | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 2 files changed, 79 insertions(+) >> create mode 100644 AGENTS.md >>=20 > Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific > prompt files that simply link to AGENTS.md, to better support different > agent CLIs? Surely all the mainline agents will read AGENTS.md by now? > > Thanks, > Chao >> 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..a97b4df5f7f >> --- /dev/null >> +++ b/AGENTS.md >> @@ -0,0 +1,78 @@ >> +# 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. >> + >> +## Security Policy >> +You MUST NOT report potential security vulnerabilities in public tracke= rs >> +(like GitLab issues). Refer to `docs/system/security.rst` for the proje= ct's >> +security stance. In brief: >> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types= ) is >> + the focus of security support. >> +- **Non-virtualization Use Case**: (TCG) does not currently provide gue= st >> + isolation guarantees. >> +- **Reporting**: Report vulnerabilities privately to `qemu-security@non= gnu.org`. >> + >> +## Repo Layout >> +- **Build Directory**: QEMU uses out of tree builds, by default the `bu= ild` sub-directory is used. >> +- **Multiple Builds**: Developers might create a `builds` directory wit= h 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 ar= chitecture-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 d= rivers. >> +- **`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/ne= t`, `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`, e= tc. >> +- **`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 i= n every `.c` file. >> +- **C Comments**: Use `/* ... */` only. No `//` comments. >> +- **Naming**: `snake_case` for variables/functions; `CamelCase` for typ= es/enums. >> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`q= emu_memalign`). No `malloc`. >> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` fo= r errors. >> +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clip= py` for Rust. >> + >> +## Commit Style >> +- **Small Commits**: Favour small discreet commits changing one thing. >> +- **Maintain Bisectability**: Each commit must compile and pass basic t= ests. >> +- **Separate Refactoring**: Split code movement or style fixes from fun= ctional changes. >> +- **Commit Messages**: Use a concise subject line, followed by a body e= xplaining "why" (not just "what"). >> +- **Signed-off-by**: Every commit must have a `Signed-off-by` line. >> --=20 >> 2.47.3 >>=20 >>=20 --=20 Alex Benn=C3=A9e Virtualisation Tech Lead @ Linaro