From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519209; cv=none; d=zohomail.com; s=zohoarc; b=LaSDq97c3NrzXqK8ckhRn3UKP1zWmt2NvJFLrFYpqHdKWKHq5m0PkXYgdVaM49yChfVoihSzgJlAwQ+Dp1/nxrf9T/J4YNkHXC105WcFEiQssinWt0S3MWVQWtwldROyYsqMk4GYHTl2VJCltIJ27qIgudcZHRVQ9VtnY5lrfOY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519209; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=UfaB3+L+i4sQ/IYfKmKHU7JZ5c3J9BsgCMXTl8yVcMc=; b=g7I4+qN1N5qZC+jiricwsfM9W4AA7m1/n4rN3jpGS+RDLP4ybPzp6sGY+9ENaLqWaBvvMFKgouhK/DkLcr6/pJLxNjfDC2JWjkSx5pKWppplg9dOMYAJSjx7Ad1W8gDfv9RrPJnUqcYk263jJ77OX1rAdaQos4wZ/f59b5hx12w= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519209875432.87696455985804; Mon, 11 May 2026 10:06:49 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU48-0000wk-9T; Mon, 11 May 2026 13:05:12 -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 1wMU44-0000s6-RA for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:09 -0400 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU40-0007n4-Sc for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:08 -0400 Received: by mail-wm1-x32a.google.com with SMTP id 5b1f17b1804b1-4891d7164ddso26355615e9.3 for ; Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e8e5e08a5sm1125625e9.6.2026.05.11.10.05.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:01 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 93F495F8CE; Mon, 11 May 2026 18:05:00 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519103; x=1779123903; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=UfaB3+L+i4sQ/IYfKmKHU7JZ5c3J9BsgCMXTl8yVcMc=; b=y2r/pj6L8UCo6z1KaOiVCNukChkXnyYPK+MQ7/x3WirvMsB7AePuHkyiGRj6WzVVvS hS0IocHx1D6eYM6G/tp42CpmW7tPFEQrEmL6octWZG57hAvs1BZ0dfbbkR3tzBHpP4ny mTzdHWjWchis4MxyQI7/AYS4hYIQ9mXEJnb7eN0b4IwCqSJ3CXHHE5XLNLUitc63BHwk khWrKY9CkuZLxk/Srhm6r4F2X9DmbQcKse79rjbe9Aj8dBRRpwkAMfxFkeobi44wj9CA W6yTVdoY3RiGfmhCmhTPRIzcJNPek9lOmEAKWhhS7ufPYy5rNmONKi1ZzWn0Ev9msyEU OZnA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519103; x=1779123903; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=UfaB3+L+i4sQ/IYfKmKHU7JZ5c3J9BsgCMXTl8yVcMc=; b=HKCm9PeG/THGALAskuoG0TJpZ8VOGCQ7k16UvHiV7AvM73a+iwYkKWJ1CAjzHnJggY BT87m8xSpvZZscZYhhY/5o/VIDwfrfmOrRjf27Aru9tYtt43wEZ/G9loeQjcofsbkSjf t8s3IRu44icCIXuYQcTXG5/aGQnIu1d3yygO3gakJN767hwNlqn1EM1LCRlLY4dPCiLs 8h/Il7GzLRyHJ5dUJPHOO6aJsKlumRfRIcKE9wju20MTDMTYov54lhFZjBxiPFkLYxeJ EdDnpL+pfNaEeSDW3g75VvXK0/qIcpEJWHb3uN5d1pJO192a1J/XOrAJGgU692Gj0HdN 2VOQ== X-Gm-Message-State: AOJu0YwdvDkEtQ7GyLXzo0yyldAvLgNsPYbQ32cJsfrcIIdo39bXqNan 7Z57aW45mGhGJCglzaP38cZHQEWMuWMhQXMrKxz3+ZiTOzzoiEHmGbEBi47Ya/3ZFjE= X-Gm-Gg: Acq92OG6Hq7NszPvzDFrvV49zK3wwH43DLYISwqiafoK74LoL1SramfTc9dtEdiAOKN bUwPUyo8Ml8KKdbDbEszjCbIVTSUiGPYw3zgjlljOK/iUlHcjcDLAQKpJELPWkNeIRhqvv9AVAR cqUZ4rtaRQB7kqd737jNaDELAbpNj8zc2DCCZzDkkktEDKaW/PN9OxxxqXXlZLJcukdDFYRYZXN DAq1sx8pQt0gBKcQ2dRtwXFVBq7X2kSUTuPW0KixtXiQhOGFze83O61cuJ2mZ1dImeWeVLVoT2b e3NvSVEQBc+VKwTGfjaGn3jhQNs84TqYRipgkpI82SOYr6X57KVy3g4g27OGNH6Q2W8JfjRGKEi 8tVDRGcY+8su44quOXGfKBOif36tqdUPEO0JQi5u8HUQvJbCC/Do0EeSjFyGAzO9R5aBwh0nwwC Hhw+asl8EIPMutuKSscRU4Kmk= X-Received: by 2002:a05:600c:859b:b0:48e:7f1c:8776 with SMTP id 5b1f17b1804b1-48e7f1c8874mr105909695e9.25.1778519103172; Mon, 11 May 2026 10:05:03 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU Date: Mon, 11 May 2026 18:04:50 +0100 Message-ID: <20260511170500.124211-2-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32a; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32a.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519210332158500 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. Signed-off-by: Alex Benn=C3=A9e --- 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 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 trackers +(like GitLab issues). Refer to `docs/system/security.rst` for the project'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 guest + isolation guarantees. +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu= .org`. + +## 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 d= ifferent 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 inc= luded 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 archi= tecture-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 driv= ers. +- **`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 sam= e line (except functions). +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in e= very `.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 e= rrors. +- **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 test= s. +- **Separate Refactoring**: Split code movement or style fixes from functi= onal changes. +- **Commit Messages**: Use a concise subject line, followed by a body expl= aining "why" (not just "what"). +- **Signed-off-by**: Every commit must have a `Signed-off-by` line. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519206; cv=none; d=zohomail.com; s=zohoarc; b=LsT0GQSrwYW8GMD/zJcXtqIsO5CBTlWevvw5hu01QOiNkVhSuSx8LG0Ggnp+TMHmgUbPo21GWtRNKftRiSBvdkfN46Kuz5NBHNTzQ+uHon+fWgR6wspjx1nNPfZk4q3Eal+Tpq/FOH0eqv/ffN4yrmpr+U7dJZbUsLOFHAVV4Ms= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519206; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=pY01G0y61H4ZgAg1sGo2nwoYnnGiNl6d8dUdjpbrmt8=; b=dxapQEKoJsImNHV4k9S0lho+Yipvs5NnviIhZADCO4pYREHsJEeowPqm3TI6MLf/M3339DWjcwKRGhcvjHUPR0yQ4UT4r5kapLcis3lI7wD6tWmEkYPlVGYTbLWFmHR5p7FhQjOXtBWJCd/4lCd92bQ6AQDWYAY8O/pAh3sD95k= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519206743364.24417591500014; Mon, 11 May 2026 10:06:46 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU46-0000tH-J3; Mon, 11 May 2026 13:05:10 -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 1wMU43-0000r6-Cv for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:07 -0400 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU40-0007iY-E9 for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:07 -0400 Received: by mail-wm1-x32e.google.com with SMTP id 5b1f17b1804b1-48e8132c6d0so11919015e9.1 for ; Mon, 11 May 2026 10:05:03 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e702e0c70sm217274945e9.6.2026.05.11.10.05.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:01 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id AB7E85F94E; Mon, 11 May 2026 18:05:00 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519103; x=1779123903; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=pY01G0y61H4ZgAg1sGo2nwoYnnGiNl6d8dUdjpbrmt8=; b=HaC7npiYVwfV8+8HoMui9vNGqsfW5yYYKne8U3PxJP2Ltz4i5Tb3npndyvwf2984jc B1b6W3r+LggVY4mQ6d2gRZCh0+xX5A+zmcRiQszI9mO4k5/8pvYTA5qISAX6iY+l5yFw KeNysppWeDusczZVXvNRKaGyeBe9/x8Wf47LdklkA9mr+IXfQ4but/iwAWU7IjoOaDbV /hroKFdHMDUymwXl4OPviQUKpUwNNTUzWzlrX6/J8TBVVh5El9dk+EAFlywllCR0D+tz iCx724clq4vfZROoG5R9XC/nnTQOsTugIYLJhqk5MSLYsUIx7OhPcNThxi+fxX5v0jaG 30+g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519103; x=1779123903; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=pY01G0y61H4ZgAg1sGo2nwoYnnGiNl6d8dUdjpbrmt8=; b=VD3SvRvYu/N9cHR/jXUNePaku/RQyj5/7SVtSAPs5fT5Y6ZmdDknIDM52Xp2hPTuDY pcBzjTW7Qvl6GLDDRoRur8icMpp8n/pDas1Sxqx87bNJ62MFkecY+aOIcFqMNthizYxh hp44OkMsK0mRkEclWv3OC8tEBMnMTiFQbc6IKN7qdlfOXJ78k74ipy5e2EmnWDf6gy0v wKAF4PJTZ6YIxMg8c7+3Nn5szu9iZNtZp5llDSSaaqkQKJ8x5aiBhRQ0wI6D3wGpnomS q2M7lJ+Xb3pGRnBqiKBV+gwZ/iVH5mcKWCIe3/vR3SWWiwLt7LPT8UfkBzMkdKluwYVN xJDg== X-Gm-Message-State: AOJu0YyZDaDYjE/xMybT91Qm2Sx5NVRnF26vgjWIzwOQfVyjYZLi3HAp 8yCmmqaK0Et6cUBqeNZCZKJZxbnU/Kfu5XDnMqnviHi/Nd80N0k1BK0I/qb9aVHpxGI= X-Gm-Gg: Acq92OH+B6t/uyMbP/sf2VEoQaGfJfwe+d88BycCg0kuAxnhOcLyoYj1itK+JlhKuFy 9GltF3A3SWZo9vApbHuHg0JMvJlNp0bmfs7VMCb9T4qS0b8nz1eK1o3LpM5MLj2Prou+12yYd0S pvIKLResC04jiHjiPfdhYXWUFLiTBtb4SXAO6nbyPkULSO15/6G3rgZpaW1tWiuwvANTvzyRf8l fzb7KmmLuBfaJC+p4toXBfAcfNZ3Zhc+7v9LFXabhsrwQqSE+eG0Isg1gEWwzhnP5FrFS9zGKSU pzcilxzizCYZ3w0ragoAujLx2m5h7JcOHCKQdb4jfnnI4FSiw3k7CMS9wulrk30wg4p0ChhEJ6n LHqQfYSAHfCLv6k+ixiaRjv9M4tcYswlmKZB4mNR+mTYMQFG1lG3El71aDxenk2+Sz1jDfgbKpp kwRjOrDHJTWCfPV9/ItmEyJNGZvEaBE4Br1Q== X-Received: by 2002:a05:600c:1d18:b0:48a:8cb6:88b9 with SMTP id 5b1f17b1804b1-48e51f44621mr389731005e9.22.1778519102584; Mon, 11 May 2026 10:05:02 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros Date: Mon, 11 May 2026 18:04:51 +0100 Message-ID: <20260511170500.124211-3-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32e.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519208403158500 QEMU makes heavy use of C Macros which can be confusing to humans and seems almost impossible for AI agents to follow. In the past I've dealt with this by compiling with V=3D1 and manually copying and pasting the gcc command line and appending -E to run the pre-processor step. With the modern build system we now have a compile_commands.json so we can automate the process with a script. There is some trickiness involved in following the line markers so we know where in the source file we are. To handle this we implement a PreprocessorState object to track where in the include chain we are. This allows us to show the including location when we dump the expanded macro. Signed-off-by: Alex Benn=C3=A9e --- scripts/expand-macro.py | 272 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100755 scripts/expand-macro.py diff --git a/scripts/expand-macro.py b/scripts/expand-macro.py new file mode 100755 index 00000000000..581f20b9897 --- /dev/null +++ b/scripts/expand-macro.py @@ -0,0 +1,272 @@ +#!/usr/bin/env python3 +# +# Automate the expansion of QEMU macros based on compile_commands.json. +# +# This script runs the C preprocessor over a file to expand macros +# in a specified line range, using the compilation flags defined in +# compile_commands.json. +# +# Copyright (c) Linaro 2026 +# +import os +import sys +import json +import shlex +import subprocess +import argparse +import re + + +def find_compile_command(target_file, compile_commands): + """ + Search compile_commands to find the rule to build target_file + """ + target_abs =3D os.path.abspath(target_file) + for entry in compile_commands: + dir_path =3D entry.get('directory', '.') + file_abs =3D os.path.abspath(os.path.join(dir_path, entry['file'])) + if file_abs =3D=3D target_abs: + return entry + return None + + +def process_command(command_entry): + """ + Strip out output related options and return a command line that will + run the pre-processor only. + """ + command =3D command_entry.get('command') + if not command: + args =3D command_entry.get('arguments', []) + else: + args =3D shlex.split(command) + + if not args: + return None + + out =3D [] + it =3D iter(args) + for arg in it: + # the -M* options all deal with generating deps + if arg in ('-o', '-MF', '-MQ', '-MT', '-MD', '-MP'): + next(it, None) # Skip the option's argument + continue + if arg =3D=3D '-c': + continue + out.append(arg) + + # Enable pre-processor output, don't strip comments, trace includes + out.extend(['-E', '-CC', '-H']) + return out + + +def normalize_path(raw_path, working_dir): + """Normalize and make paths absolute.""" + if not os.path.isabs(raw_path): + return os.path.abspath(os.path.join(working_dir, raw_path)) + return os.path.normpath(raw_path) + + +class PreprocessorState: + """Tracks the state of the preprocessor as we parse its output.""" + def __init__(self): + self.stack =3D [] + self.current_path =3D None + self.current_line =3D 0 + self.current_instance_id =3D 0 + self.next_instance_id =3D 1 + self.sections =3D {} + + def update_on_marker(self, new_line, flags, path): + """Update the file stack and instance tracking based on markers.""" + # entering new file + if "1" in flags: + if self.current_path is not None: + self.stack.append((self.current_path, self.current_line, + self.current_instance_id)) + self.current_path =3D path + self.current_line =3D new_line + self.current_instance_id =3D self.next_instance_id + self.next_instance_id +=3D 1 + return + + # leaving file + if "2" in flags: + if self.stack: + _, _, popped_instance_id =3D self.stack.pop() + self.current_path =3D path + self.current_line =3D new_line + self.current_instance_id =3D popped_instance_id + else: + self.current_path =3D path + self.current_line =3D new_line + self.current_instance_id =3D self.next_instance_id + self.next_instance_id +=3D 1 + return + + # return to previous file without explicit flag 2 + if self.current_path !=3D path: + if self.stack and self.stack[-1][0] =3D=3D path: + _, _, popped_instance_id =3D self.stack.pop() + self.current_path =3D path + self.current_line =3D new_line + self.current_instance_id =3D popped_instance_id + else: + self.current_path =3D path + self.current_line =3D new_line + self.current_instance_id =3D self.next_instance_id + self.next_instance_id +=3D 1 + return + =20 + self.current_line =3D new_line + + def get_context_string(self, target_abs, working_dir): + """Generate a descriptive string showing the inclusion context.""" + if self.stack: + ctx_path, ctx_line, _ =3D self.stack[-1] + try: + rel_ctx =3D os.path.relpath(ctx_path, working_dir) + except ValueError: + rel_ctx =3D ctx_path + return f"{rel_ctx}:{ctx_line}" + + try: + rel_ctx =3D os.path.relpath(target_abs, working_dir) + except ValueError: + rel_ctx =3D target_abs + return f"{rel_ctx} (main file)" + + def add_line(self, line, line_range, target_abs, working_dir): + """Add a line to the sections if it is within the requested range.= """ + start_line, end_line =3D line_range + if self.current_path =3D=3D target_abs: + if start_line <=3D self.current_line <=3D end_line: + if self.current_instance_id not in self.sections: + ctx_str =3D self.get_context_string(target_abs, workin= g_dir) + self.sections[self.current_instance_id] =3D { + "context": ctx_str, + "lines": [] + } + self.sections[self.current_instance_id]["lines"].append(li= ne) + self.current_line +=3D 1 + + +def format_output_sections(sections, target_file, start_line, end_line): + """Format the accumulated sections into the final output string.""" + output_sections =3D [] + for _instance_id, data in sections.items(): + if not data["lines"]: + continue + header =3D f"/* Expansion from {data['context']} */" + body =3D "\n".join(data["lines"]) + output_sections.append(f"{header}\n{body}") + + if not output_sections: + return (f"/* Error: No lines found for {target_file} " + f"in range {start_line}-{end_line} */") + + return "\n/* end of expansion */\n".join(output_sections) + + +def extract_range(stdout, target_file, start_line, end_line, working_dir): + """ + Parse the output of the pre-processor while tracking where we + are in the source code from the markers so we can extract the + range asked for. + """ + state =3D PreprocessorState() + target_abs =3D os.path.abspath(target_file) + line_range =3D (start_line, end_line) + + # The format is undocumented but see: + # + # gcc/c-family/c-ppoutput.c:print_line_1 + # + # where 1 =3D entering file, 2 =3D leaving file + # and the 3 or 3 4 depends on linemap_location_in_system_header_p + line_marker_re =3D re.compile(r'^# (\d+) "(.*?)"(.*)') + + for line in stdout.splitlines(): + match =3D line_marker_re.match(line) + if match: + new_line =3D int(match.group(1)) + raw_path =3D match.group(2) + flags =3D match.group(3).split() + + path =3D normalize_path(raw_path, working_dir) + state.update_on_marker(new_line, flags, path) + continue + + state.add_line(line, line_range, target_abs, working_dir) + + return format_output_sections(state.sections, target_file, + start_line, end_line) + + +def main(): + """Main entry point for the script.""" + desc =3D 'Expand macros in a section of a file using compile_commands.= json' + parser =3D argparse.ArgumentParser(description=3Ddesc) + parser.add_argument('file', help=3D'Source file to expand macros in') + parser.add_argument('--range', help=3D'Line range (e.g. 100-120)') + + ctx_help =3D ('Context file (.c) to get compilation flags from ' + '(useful for headers)') + parser.add_argument('--context', help=3Dctx_help) + parser.add_argument('--compile-commands', default=3D'compile_commands.= json', + help=3D'Path to compile_commands.json') + parser.add_argument('--show-command', action=3D'store_true', + help=3D'Print the modified compile command and exi= t') + + args =3D parser.parse_args() + + if not os.path.exists(args.compile_commands): + print(f"Error: {args.compile_commands} not found.", file=3Dsys.std= err) + sys.exit(1) + + with open(args.compile_commands, encoding=3D"utf-8") as f: + compile_commands =3D json.load(f) + + query_file =3D args.context if args.context else args.file + entry =3D find_compile_command(query_file, compile_commands) + + if not entry: + print(f"Error: Could not find compile command for {query_file}", + file=3Dsys.stderr) + sys.exit(1) + + cmdline =3D process_command(entry) + if not cmdline: + print(f"Error: Failed to process command for {query_file}", + file=3Dsys.stderr) + sys.exit(1) + + if args.show_command: + print(shlex.join(cmdline)) + sys.exit(0) + + working_dir =3D entry.get('directory', '.') + result =3D subprocess.run(cmdline, stdout=3Dsubprocess.PIPE, + stderr=3Dsubprocess.PIPE, cwd=3Dworking_dir, + universal_newlines=3DTrue, check=3DFalse) + + if result.returncode !=3D 0: + print(f"Preprocessor failed:\n{result.stderr}", file=3Dsys.stderr) + sys.exit(result.returncode) + + content =3D result.stdout + if args.range: + try: + start, end =3D map(int, args.range.split('-')) + content =3D extract_range(content, args.file, start, end, + working_dir) + except ValueError: + print(f"Error: Invalid range format {args.range}. Use start-en= d.", + file=3Dsys.stderr) + sys.exit(1) + + print(content) + + +if __name__ =3D=3D "__main__": + main() --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519203; cv=none; d=zohomail.com; s=zohoarc; b=bDSZRI9x/d/SJ2Dysu3RaRrlY2tvWEWOaX/QdZQyqnwOXAABicm1QwmBb8uhLIbpLfhWUcLvovh4rsZoQcJdhOUnkXy9tPgu/ainB7imz5JGyKJ62bEVADfKE82xhxZenIaHMksQNKDQjP1ohrSFtFPT6dO0LokCBKTddKp/QhQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519203; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=rKUkvslWZr7sukogZRrX9QWlcGo8FSZeMYPKDhG7aV8=; b=fsGgOTjfg+uOx6Ra2blW5w9EOVVWIXE9GQwodsgYXyaUtv3BtN6ClK5jcDWZleHtGlm4Ej3O+4W/hEQKlzFR3Y+1euQZhbzZJCWd+ZHnmqwDT/9YAxAr9mcHAl7mwD3D5PAn5lUTvJWWRq2VwxfSxprF9O9PV3egqtPEqbfmoAs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519203492126.6483831576063; Mon, 11 May 2026 10:06:43 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU48-0000x7-FF; Mon, 11 May 2026 13:05:12 -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 1wMU45-0000sr-Of for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:10 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU43-0007nl-6n for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:09 -0400 Received: by mail-wm1-x331.google.com with SMTP id 5b1f17b1804b1-48909558b3aso48259825e9.0 for ; Mon, 11 May 2026 10:05:06 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e8e7491edsm592135e9.13.2026.05.11.10.05.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:01 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id C3AB560469; Mon, 11 May 2026 18:05:00 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519105; x=1779123905; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=rKUkvslWZr7sukogZRrX9QWlcGo8FSZeMYPKDhG7aV8=; b=nJ6lkhRq6fosPVk9nnClSzbg1RwXfvH/pa8+xNkG4iUEdGW98qRJmDk/VjzbKzyOQJ c+wkJ2kl57epSiZwKzi8RAo2CBImAYx8gV6cxCpnrRGKCIqh6ARnkTxkSsAIa7MFPZCX xfybjNu0WoVeAKPKQxJUC0UHKrJcagaanSZx9ttn9go5R+JAedX029FxFN5txexwXTFu bZEW0daHQLeJxCPZHBUdAc2q4XnMAA2Krav+rKIg1CRz2zcAnTrNWX4Km17erXJHsZgt bCgqI1bLXlTnP7hKyxtmBLGEtYOEuhL8PgbCL0QxV75FB7KrkQUtmnl1I1KXSbteJtx8 u8Kw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519105; x=1779123905; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=rKUkvslWZr7sukogZRrX9QWlcGo8FSZeMYPKDhG7aV8=; b=VBR5vk/xQISFrl1bGhpT2fuciCW2zF2f+Vgb6GIErraA9qjqTOE2M2wOVCYMZDDnXX GSFCfoxRhsm56ass/cMByVtwNo8xIhWwZuzslDIH2JkzvuTufKSAZfOL8ESalHVzVTbn TG/SuyLQLTvVnmxq4VWY95lj8UrrgtxqIgKtpOdcd9UwI8wJKBVI9xRvBJu3z2x2UA4u fiQdXyoIfMFs3bNMjqS5o65ZcB2HIet5XYRtY5/oxx2qp+iqcAJvrebVgki5wlBMsa3K SmpsvFUOS6DO5A4SpevS1iwsBHwYZzkaG/88Q31nib1kbY5osmWB9DcW7mdgqsfmrSGl Diug== X-Gm-Message-State: AOJu0Yzb17V8rABd81hFxHZejHa+SPHob8A+BVjCMtg/zzjO9FzuqDwX +XCud3wzpbiA9oPy2mux/kJKCDf9GhpSaqHyPJA68fy9GRLiCDTKg0KXA9l7OgIENwY= X-Gm-Gg: Acq92OEmgCNcmoak9hsButlwiUidR7V00xYQunCt806JOYSwgFzq0VKsOuhGFmFdcmH IxoKyAPk6MnfftkfAhkD8piY99mUbM6C2LOxU3dfmsKV34XfYXgZVFtfhYvkBl7Ka7SfMVqZLKx bM6XUGs9e10fDdpa7baxZnufCcCrnfoQBLrJUZcdX8po2RPEoSZst5BMqXWZxds6rwp/UKhTajv uz/N4BcLeer5I1vwSsJv64QYMrUuiBQBd4XJQ7/2DWVSV/luDkeKt275Tf3QorCv8rSJwzuQBWr ve9vcAjFaQhyrTHNFjrJX5oiO/FSAyHG7mjyJGT18sYq9RSMzXoT57fFapteWPydXKUgiYK+g+H bZeBXAxihd+cs1udBGtbNCTPemAyPPd5I7sT5EcSa+l2jn8nxjTaXgWIT7uNBbhhWYXfUBv63oQ T2c0tqkpm82c4+QwA1t4ApAik= X-Received: by 2002:a05:600c:4c25:b0:48a:65a5:750f with SMTP id 5b1f17b1804b1-48e51f46ddamr241162965e9.21.1778519104685; Mon, 11 May 2026 10:05:04 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill Date: Mon, 11 May 2026 18:04:52 +0100 Message-ID: <20260511170500.124211-4-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x331.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519204260158500 This provides a skill detailing how to explore the QEMU code base. It guides the agents to use the tags and git-grep by default and outlines some of the confusions that can occur with multiple build directories. Signed-off-by: Alex Benn=C3=A9e --- v2 - remove personal gtag skill references, add global stanzas directly - moved macro information from AGENTS.md into code explorer - more imperative language to trigger its use - add section on using scripts/expand_macro.py - remove eca reference from evals.json (maybe we should just drop this) --- .agents/skills/qemu-code-explorer/SKILL.md | 119 ++++++++++++++++++ .../qemu-code-explorer/evals/evals.json | 26 ++++ AGENTS.md | 1 + 3 files changed, 146 insertions(+) create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qe= mu-code-explorer/SKILL.md new file mode 100644 index 00000000000..d5b7d6a35cd --- /dev/null +++ b/.agents/skills/qemu-code-explorer/SKILL.md @@ -0,0 +1,119 @@ +--- +name: qemu-code-explorer +description: Systematic framework for deep-diving into the QEMU codebase. = Use this to find precise symbol definitions (functions, structs, globals), = locate all call sites or references, explore subsystem architectures, or se= arch generated code in build directories. You MUST use this skill when expl= oring code flow and dependencies. +license: GPL-2.0-or-later +--- + +# QEMU Code Base Explorer + +This skill provides a systematic approach to navigating and understanding = the large and complex QEMU codebase. + +## 1. Symbol Search with Tags (Primary) + +Tagging systems are the fastest and most accurate way to find global symbo= l definitions and references. QEMU supports `gtags`, `ctags`, `cscope`, and= `TAGS` (Emacs). + +### GNU Global (gtags) - Recommended +- **Best for**: Finding where a function, struct, or global variable is de= fined or used. +- **Commands**:=20 + - Find definition with context: `global -dx SYMBOL` + - Find references with context: `global -rx SYMBOL` + - Find related symbols (completion): `global -c PREFIX` +- **Note**: Using `-x` provides line numbers and the matching line's conte= nt, allowing for immediate analysis. This is significantly faster and more = accurate than `grep` for symbols. + +### Updating Tags +If you suspect the tags are out of date: +```bash +make gtags # or make ctags, make cscope, make TAGS +``` + +## 2. Text Search with `git grep` (Secondary) + +`git grep` is the preferred tool for general text searches within the sour= ce tree. + +- **Best for**: + - Searching for local variables within a function. + - Searching for string literals or comments. + - Finding occurrences of symbols defined in system headers (e.g., `optar= g`). + - Complex regex patterns that `gtags` doesn't support. +- **Why**: It is fast, respects `.gitignore`, and avoids searching through= build artifacts or other non-source files. +- **Usage**: `git grep "pattern"` or use a grep-like tool with the `path` = set to the repository root. + +## 3. Searching Generated Code + +Generated source files (e.g., from QAPI, trace-events, decodetree) do not = reside in the source tree but in the build directory. + +- **Best for**: + - Finding definitions of functions generated by QAPI (e.g., `qmp_marshal= _...`). + - Finding trace points and their implementations (e.g., `trace_..._heade= r`). + - Checking configuration fragments (`config-*.h`). +- **Tools**: Use a normal `grep` (or similar search tool) limited to the b= uild directory. +- **Crucial Note**: QEMU developers often have multiple build directories = (e.g., `build/`, `builds/debug/`, `builds/asan/`). Always verify which buil= d directory is active or intended. +- **Common Paths**: + - `build/qapi/`: Generated QAPI headers and C files. + - `build/config-host.h`: Host-specific configuration. + +### QOM (QEMU Object Model) (see `docs/devel/qom.rst` & `include/qom/objec= t.h`) +- Most devices are QOM objects. +- Key concepts: `TypeInfo`, `ClassInit`, `InstanceInit`, `InstanceFinalize= `. +- `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to boilerpl= ate. +- Also creates casting macros like `MY_DEVICE(obj)`. + +### QAPI +- Interface definitions live in `qapi/*.json`. +- Generated code lives in `build/qapi/`. + +### Tracing +- QEMU uses a tracing framework. Events are defined in `trace-events` file= s. + - `build/trace/`: Generated trace points. + - `trace_my_event_name(arg1, arg2);` calls the `my_event_name` trace poi= nt. + +### Decodetree (see `docs/devel/decodetree.rst`) +- QEMU uses `decodetree.py` to generate instruction decoders. +- A pattern like `- FOO ...` in a `.decode` file will: + 1. Generate code in the build tree (e.g. `decode-insns.c.inc`). + 2. Call a handwritten `trans_FOO(DisasContext *ctx, arg_FOO *a)` in the = source tree. + 3. The `arg_FOO` structure is automatically filled with fields from the = instruction. +- Some instructions may use a common structure if defined with `&`. + +### Common QEMU Macros +- **QOM**: `OBJECT_DECLARE_SIMPLE_TYPE(InstanceType, ClassType, MODULE_OBJ= _NAME, MODULE_OBJ_TYPENAME)` expands to type declarations, casting macros (= `MODULE_OBJ_NAME(obj)`), and more. +- **TCG**: `HELPER(foo)` expands to helper function declarations or calls. +- **Error**: `ERRP_GUARD()` ensures `errp` is not NULL for easy error prop= agation. +- **Bitwise**: `BIT(n)`, `MAKE_64BIT_MASK(shift, len)` for clear bit manip= ulation. +- **Structs**: `container_of(ptr, type, member)` to get parent struct poin= ter. +- **Memory**: `g_autofree` and `g_autoptr(Type)` for automatic cleanup (GL= ib). +- **Migration**: `VMSTATE_...` macros for defining device state save/load. + +## 4. Expanding Complex Macros + +QEMU makes heavy use of macros, which can sometimes be hard to follow by "= hand". To understand exactly how a macro expands in a specific file and con= text, you should use the `scripts/expand-macro.py` tool. + +- **Best for**: + - Expanding complex macros to see their generated C code. + - Understanding how nested macros evaluate. +- **Usage**: + ```bash + python3 ./scripts/expand-macro.py FILE --context CONTEXT_FILE --range ST= ART_LINE-END_LINE + ``` +- **Example**: + To see how `partsN_canonicalize` expands in `fpu/softfloat-parts.c.inc` = when included from `fpu/softfloat.c` between lines 191 and 264: + ```bash + python3 ./scripts/expand-macro.py fpu/softfloat-parts.c.inc --context fp= u/softfloat.c --range 191-264 + ``` + +## Decision Matrix: Which tool to use? + +| Goal | Tool | Reason | +|------|------|--------| +| Find a function definition | `gtags` | Precise and fast. | +| Find all call sites of a function | `gtags` | Comprehensive. | +| Find a local variable usage | `git grep` | `gtags` only tracks globals. | +| Search for a string literal | `git grep` | `gtags` doesn't index literal= s. | +| Find QAPI-generated code | `grep` in `build/` | Not in source tree. | +| Search in a specific subsystem | `git grep ` | Efficiently scoped.= | +| Understand complex macro expansion | `scripts/expand-macro.py` | Shows e= xact generated C code. | + +## Workflow Tips +1. **Scope your search**: If you know you are looking for a networking iss= ue, search `hw/net/` or `net/` first. +2. **Beware of Macros**: QEMU uses many macros (especially in QOM). If `gt= ags` fails, `git grep` might find where the macro is used to define the sym= bol. +3. **Verify the Build**: Before searching generated code, ensure a build h= as been performed in the target directory. diff --git a/.agents/skills/qemu-code-explorer/evals/evals.json b/.agents/s= kills/qemu-code-explorer/evals/evals.json new file mode 100644 index 00000000000..8eaa45b28b3 --- /dev/null +++ b/.agents/skills/qemu-code-explorer/evals/evals.json @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +{ + "skill_name": "qemu-code-explorer", + "evals": [ + { + "id": 0, + "prompt": "Where is the function 'qemu_mutex_lock' defined and where= is it used in the block layer (block/)?", + "expected_output": "The definition should be found (likely in util/q= emu-thread-posix.c or similar) and usages in block/ should be listed using = gtags." + }, + { + "id": 1, + "prompt": "I'm seeing a reference to 'qmp_marshal_query_status' in s= ome docs but I can't find it in the source tree. Can you find where it is d= efined?", + "expected_output": "The agent should identify this as QAPI generated= code and look in the build directory (e.g., build/qapi/qapi-commands-contr= ol.c)." + }, + { + "id": 2, + "prompt": "Find all implementations of trace points for 'virtio_net'= in the generated code.", + "expected_output": "The agent should search for 'trace_virtio_net_*'= in the build directory, specifically in generated trace headers/sources." + }, + { + "id": 3, + "prompt": "Find all occurrences of the string 'Could not open' in th= e 'hw/' directory.", + "expected_output": "The agent should use git grep scoped to hw/ to f= ind the string literals." + } + ] +} diff --git a/AGENTS.md b/AGENTS.md index a97b4df5f7f..74516c378ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,7 @@ security stance. In brief: =20 ## 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. =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519206; cv=none; d=zohomail.com; s=zohoarc; b=EnMb/Ec1WcSKHnXZDevGYaNW37oj9Oy3XsMskPoC+Mfbizf+/BVOipBzOo8xYng3mvzWsD5o6OiEwyEIsqkE4lGnLsimUmZ8TrV+viUnpv1D4VFwCFklHeqND99z61IQPbXH4Y8dBKD3e2b6rE80vn/5E8JMCM2gieTA8eBvatE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519206; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=oCvDLGdWpxj14o5+vhYsw/V00nmfdhF65oNI4ftCg/w=; b=HEDXQktZMzzfcDuhjnWEn3FT8EVAx190X7TSR6FhG+J5pNGdVuiocvVgALp6u9HRKojUyuqbk/PRl/Uo5GNYT1SRIorKZMXZC0UsEkuh1H94j1sBg0F5OrZSLk6pmfnxnk7ws8yPH1lKeU1/fPxBCyYYaSYCs7B1gc0z/PldhiM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519205914373.3519912497651; Mon, 11 May 2026 10:06:45 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU48-0000yR-Ur; Mon, 11 May 2026 13:05:14 -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 1wMU44-0000rv-PG for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:08 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU41-0007nU-R2 for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:08 -0400 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-48e6db3ff7eso14751045e9.0 for ; Mon, 11 May 2026 10:05:05 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e702e6d41sm254552155e9.7.2026.05.11.10.05.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:01 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id DCAFA6076B; Mon, 11 May 2026 18:05:00 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519104; x=1779123904; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=oCvDLGdWpxj14o5+vhYsw/V00nmfdhF65oNI4ftCg/w=; b=uRIji4tl30mtL+Qb+Lf83YAW/C25rBO71GhmK030jxE0Q3jvhQT0eHiCjvq4ykGoU6 r73gmIMsFTbbI1OTALSSwZE+/ShBu+oZ0pPORAcuUZOKiYZM6HBdtO4ut2mHXJHTPrZQ rpjZI5jXWONRczcJ6J3jfuG5F8o49F1MSCDmnFnKNjXupF5amBU890XenWGHDcbmQh5G yFKfnKFZ52+eoMDs1DR0PaTeEeCRAlmSGFwT5xxc2zWLgd8x17L9aOiRp32nwRrk/XTw Nm0FrM/UKEW2KNg2XPgpNjXdrEJaUNEgLcAxIA5rw3PEeRSbxkZjwjdBO3BmllPfcwQe XrJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519104; x=1779123904; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=oCvDLGdWpxj14o5+vhYsw/V00nmfdhF65oNI4ftCg/w=; b=bFCSAJmzghrGiLaWm93Q8kF5QI5EYIgl4Ar5Ec75WeC/cUn5OAR+id83K1CRRHh1i/ MRXsoX+ImpRjp0kmu5oj6Bk48EzEGFihQRdwzho/KXL058D4EcHICb0NsXqDmWU8buz7 ABxtUc7OlLF6aSjY1ejezXbD7YSDrFn/fmS0gOJpK0v/B85Sn/p9cvs3r7D3fXXPIHn0 Lpw6oXnI0Z7E5iD6pwd9jK6bIgepP0rxL9ACEP4O8r642EngIDHdJyUtwasMzRY6C+Yy 7WgIgmQ2hudEfRICttoIIWcWWz6w1pfiOah7wwfkse1UkLMNiFxaVewYXzfNLDIq5z9U 8Lqw== X-Gm-Message-State: AOJu0YyWA4ymM+tZa03FV7/KVlsYSc/rYKhAdEQmn4PlYIJY52wEOVW1 LysNTq5HipIlezD33Qv6xGa1ZfX0aPfBNvdoXB/xAdwV5dg9S6+SrHtlcqdZkTdJYq0= X-Gm-Gg: Acq92OGCdBnkGBSS50vYNDf+zjRc/oQ2WYADtwftIuzxfC8+fiVkrCQtnnyeBKSeCBD h07LGh6bWSJVrJ7rqbjAIrco0h0JsBxhKGC/2Yf14tiLwgjGQf4V3mcq2bv8RRgsrXEz/Cj+5cp AKZ/5QcV5wG4obhYwJSfdzSccuQFJcxUw+l73mU0nKheDE51zgbY1KRiBNfLYFVTxb+SlbDoWci QGPFfUp1AMBxa+xwNzl4yzziQYg/fuSqcEzAawlqooY3Df87bCykCrDuus2nmO/anoRl4MgM54d 4uTOemNKtNkwdT3GOX7T3ul0RHHshTQvmyh1R2EqsLg/tVnssKLJPF5fHnU2HdaElMbDHiub8FP xnUvwjHuhxLGjIDsEsOLjfTvI3dFYEQMllOuyxSOmZR5MOzulmsH5xnFsF4qT9koaKNyXmSbclR J6Wccjsnk2KxUFOn/uCGAPs4w= X-Received: by 2002:a05:600c:2e0c:b0:48e:526e:1011 with SMTP id 5b1f17b1804b1-48e526e106bmr217016445e9.25.1778519103962; Mon, 11 May 2026 10:05:03 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill Date: Mon, 11 May 2026 18:04:53 +0100 Message-ID: <20260511170500.124211-5-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32d; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32d.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519208332158500 This provides basic instructions for building QEMU. Signed-off-by: Alex Benn=C3=A9e Tested-by: Chao Liu --- v2 - drop ECA/qemu-helper-agent sub-agent language - mention configure --help - drop mention of full paths - not needed for compilation - moved earlier is series so code-reviewer can refer to it --- .agents/skills/qemu-build/SKILL.md | 50 ++++++++++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 51 insertions(+) create mode 100644 .agents/skills/qemu-build/SKILL.md diff --git a/.agents/skills/qemu-build/SKILL.md b/.agents/skills/qemu-build= /SKILL.md new file mode 100644 index 00000000000..91819a0992a --- /dev/null +++ b/.agents/skills/qemu-build/SKILL.md @@ -0,0 +1,50 @@ +--- +name: qemu-build +description: Provides step-by-step instructions on configuring and buildin= g QEMU. You MUST trigger this skill whenever the user asks to build QEMU or= debug build failures. It includes critical details on build directory reus= e and spawning sub-agents. +license: GPL-2.0-or-later +--- + +# Instructions + +## Examining and Re-using Build Directories +Before creating a new build directory, check if an existing one can be re-= used. QEMU uses out-of-tree builds, typically in `build` or `builds/` sub-d= irectories. + +1. **Check existing configs**: You can examine how an existing build direc= tory was configured by checking its `config.log`. Run `head -n 2 builds//config.log`. The second line typically contains the full `../configure` = command line used. +2. **Re-use and Reconfigure**: You have latitude to re-use existing direct= ories when appropriate (e.g., `builds/debug` which is a general-purpose deb= ug directory for whatever is currently going on). If an existing directory = has the right flags (like debug/sanitizers) but the wrong target list, you = can reconfigure it to keep the same config but change the `--target-list`: + ```bash + cd builds/debug + # Check the old config.log, then re-run configure with the new target-l= ist + ../../configure --target-list=3D + ``` + +## Launching Builds +**Crucial**: You MUST NEVER run builds directly in the main agent context.= You MUST ALWAYS launch them by spawning a sub-agent. +Pass the specific build commands, along with the required working director= y, in the `task` argument. Give the subagent explicit instructions on what = to verify and what to report back to you. +For example: `task: "Navigate to builds/debug and run ninja. If it fails, = report the exact compiler errors."` + +## Configuring a New Build +If no suitable build directory exists, create a new one. + +1. **Create build directory**: `mkdir -p builds/test-target; cd builds/tes= t-target` +2. **Basic Configure**: `../../configure --target-list=3D[list of targets]` + - Common targets: `x86_64-softmmu`, `aarch64-softmmu`, `riscv64-softmmu= `, `x86_64-linux-user`. +3. **Common Options**: + - `--enable-debug-info`: Include symbols. + - `--enable-debug`: Enable assertions. +4. **Sanitizers**: + - `--enable-asan`: Address Sanitizer. + - `--enable-tsan`: Thread Sanitizer. + - `--enable-ubsan`: Undefined Behavior Sanitizer. +5. **Help**: + - `--help`: will give a comprehensive list of options + +## Building +**Important**: Always re-run the build after making changes to the source = code. + +## Reporting Results +**Crucial**: After completing the build task, provide a concise summary of= the results to the user. +1. **Summary**: State whether the build passed or failed. +2. **Failure Excerpts**: If the build fails, include relevant excerpts fro= m the logs (e.g., compiler errors). + +## Debugging and Environment +- **Verbose**: `V=3D1` for detailed output. diff --git a/AGENTS.md b/AGENTS.md index 74516c378ed..08bfe13ebd2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,7 @@ security stance. In brief: ## 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 san= itizer builds). =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519145; cv=none; d=zohomail.com; s=zohoarc; b=H9xMuh3IBf6tYoN2O1klC9d49VzluJKlzxlEphYw+OjwiJ8Sm+yR5zdfUW08p4cW6e8ahjMy435IQeLr/Y3/OuGuWPnLgVsnhBGCS++Z5cWr+sViwVn1v68MmWo8pv23e4epgMFVmfZbapTdCF2lhorRxKQ1Dt5BcjPRYE7vdl0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519145; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=YKodQmYNNWaAk1teiRNN0+JW1aqt9sbMYp1HKpx3s6A=; b=Y2KTuV3I3Nb6v2NLVSIO5p0oAVSLi3HrlF9tsjYWGLA6JRygDrbl2a83IQ7Xl5+SBumPs9tlu9u/bqbqgNbB7Q74SXHFzKW3pX9umUooFpvqEJpWiBP9pw9byU/ilQBZXBOXAidWDml8sX5+hxWr7Z81nWj+NjrBOtHQQJb+jC0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519145156416.8496087471526; Mon, 11 May 2026 10:05:45 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4E-00015M-Mk; Mon, 11 May 2026 13:05:18 -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 1wMU46-0000tN-FP for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:10 -0400 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU43-0007nu-Ko for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:10 -0400 Received: by mail-wr1-x430.google.com with SMTP id ffacd0b85a97d-44c350a5b87so2807996f8f.3 for ; Mon, 11 May 2026 10:05:07 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-45492271510sm32228022f8f.37.2026.05.11.10.05.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 022DC60814; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519105; x=1779123905; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=YKodQmYNNWaAk1teiRNN0+JW1aqt9sbMYp1HKpx3s6A=; b=yYpbILam2SGaDpsfl6H2vW2T6pFiCRiAsD7DBAsnv37BSCg0F528dBo/spe1tSpXRD KAG7rxa4nDRobUrzTDWb30W4Rur7jbuDRcBlxz2mucZngH/Tm/YuBvt3GJP952O5YYns sexJikXO+pJILi9IT12PYxPU/7J6BmtokOMqlh2XWui1Z/A2auguCdKWsUrAL3RwRGSU GoioR91M9YctZfJME2cpY6jTi6jJKe89yQDBG41jQOQ/6nrScwTH1Cdy4T5rc171pZ7h 5o7v6KCLj+l24KpGHgfnt4Dhub4SUdUA3uUfxs6rQMk4UToEzNL1rc4r7ZxFqWTW2qZE PW7Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519105; x=1779123905; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=YKodQmYNNWaAk1teiRNN0+JW1aqt9sbMYp1HKpx3s6A=; b=Wo9WXd7YTopQJfN1Lzj3YFc63DcveBpuKwyeSKtPb44A7bw8ELHClmCgrV603WwsXx mm44Th+qwk0htwl3gu1uRS/wEsXwDQFBpU831QdrJd4Z0Wr5FmJ1v8PGECWA554BrTSM U3ustTYt120j4LUzmdpJor9zw0tf3f/284UcdEP1ndfRRdW0HZabb9XSpH9nwgM53OEg bj65XkkJUaZDzrM4oFHSvdk+1HsY0KZp5Illy1pMj8dWP0Gf75r+NYTiawZ406IWu6WE A3JQxTRPKTbzm8Lkc2vGPun4hOdPplqLXXLDF+9fTsnOy6Ugufm6jYg23o76CjJH2CQu EdCg== X-Gm-Message-State: AOJu0YxmVvBKkSoY2G/Mg4GdPyAtbDdLT1+q2Pn8xzAV7emNCZ2KkU6r 5yEao3pGnsNhN61kSJQ7KPVCPmdrkRJhrps5kcOpYoNYLgVeY4hLD+vPB9JFoVzKq74= X-Gm-Gg: Acq92OHN+lvZxHJowUAOIIE33TIBt3afZ9o3eBacs3BvIk02M7xCCIuSQayGtCV9r9u O1er3nm9UdQ9XP26KSGgwLeL8BGFIlrkl4itgbpfcQFNU8oJt1Pg7JGynKoXg6zhAS5FPwyZB7K vZxsACzhWjedp8VRMWKgANpR/awSwtsDkuwEvOvpMQhyFPKEbX+MgFavTWdcugXNzSpUS8QTPxk meVCG4rXdC8Y7MOZGOzr68+vdOsm5Ipxv4SkazHs8laHaylVC/0YI4RrVOZ/7IAZlFt7tkZJ1vF gMs63RUgI3wclXinOOXJe/Jp8n5IHMwzIUV3tW2Df1u6EE4iGzogpf9ulLw8f1qM3Umb4nH0uR/ J/pZyYWqMk94J755zoaTH+UGp5vpNMsCn/8leDls1fsxt5yvRm5HhCiIlVXWtco7AriqwYRwR/p eSQ/p5WPHsMqSJ/ekyQo+J30c= X-Received: by 2002:a5d:5f53:0:b0:45a:cea8:e4b2 with SMTP id ffacd0b85a97d-45acea8e4f1mr248012f8f.29.1778519105432; Mon, 11 May 2026 10:05:05 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 05/10] .agents/skills: add qemu-testing skill Date: Mon, 11 May 2026 18:04:54 +0100 Message-ID: <20260511170500.124211-6-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::430; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x430.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519147675158500 This provides basic instructions for running tests but doesn't try to exhaustively describe the whole setup. Signed-off-by: Alex Benn=C3=A9e --- v2 - add link to testing docs. --- .agents/skills/qemu-testing/SKILL.md | 56 ++++++++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 57 insertions(+) create mode 100644 .agents/skills/qemu-testing/SKILL.md diff --git a/.agents/skills/qemu-testing/SKILL.md b/.agents/skills/qemu-tes= ting/SKILL.md new file mode 100644 index 00000000000..e5979dfc1c5 --- /dev/null +++ b/.agents/skills/qemu-testing/SKILL.md @@ -0,0 +1,56 @@ +--- +name: qemu-testing +description: Provides instructions on how to find, list, and run individua= l tests for QEMU (Unit, QTest, Functional, TCG). You MUST use this skill wh= enever the user asks about tests, wants to list available tests, or wants t= o run any test in a build directory, even for simple exploratory queries li= ke "what tests can I run". It includes details about spawning sub-agents. +license: GPL-2.0-or-later +--- + +# Instructions +To run QEMU tests, you can use several different suites depending on what = you are testing. **Note**: Ensure you have a recent build of QEMU before ru= nning tests. Use the `qemu-build` skill if you need to configure or run a b= uild. + +For exhaustive details on the testing infrastructure, architectures, and s= pecific test requirements, you MUST refer to the official documentation in: +- `docs/devel/testing/` (specifically `main.rst`) + +## General Test Suites +- **Unit Tests**: `make check-unit` +- **QTest (Device emulation)**: `make check-qtest` +- **Functional Tests (Python based)**: `make check-functional` +- **TCG Tests (CPU instruction tests)**: `make check-tcg` + +## Launching Tests +**Crucial**: You MUST NEVER run a test suites directly in the main agent c= ontext. You MUST ALWAYS launch them by spawning a sub-agent. Pass the speci= fic build or test commands, along with the required build directory, in the= `task` argument. Give the subagent explicit instructions on what to verify= and what to report back to you. +For example: `task: "Navigate to builds/debug and check what meson tests t= ouch replay and report back."` or `task: "Run make check-tcg in builds/arm = and summarize any failing tests."` + +### From the Build Directory +Most individual tests from within a build directory. Most (unit, qtest, bl= ock, functional) can be individually selected and run via meson. + +As QEMU often needs a newer meson than the build host you should use the b= uild `pyenv` to launch it: +- **Example**: `./pyvenv/bin/meson test --suite thorough --list` to see wh= at tests are in the thorough test suite + +## Running Individual Tests + +### Meson Test Runner (Unit, QTest, Functional, softfloat etc) +To run a single test, you can use the meson test runner from within your p= yvenv: +`./pyvenv/bin/meson test [testname]` +Example: `./pyvenv/bin/meson test qtest-x86_64/boot-serial-test` + +### TCG Tests +To run individual TCG tests for a specific architecture: +1. Navigate to the relevant build directory, e.g.: `cd tests/tcg/aarch64-s= oftmmu` +2. Run a specific test with make: `make run-[testname]` + Example: `make run-memory-sve` +3. Use `make help` within the architecture directory to see the full list = of available tests. + +### Functional Tests +Individual functional tests can be run directly using the run script altho= ugh from the source directory: +- **Example**: `./builds/all/run tests/functional/aarch64/test_virt_vbsa.p= y` + +### Environment Variables +- `V=3D1` for verbose output from tests. +- `SPEED=3Dslow` to run slower tests that are normally skipped. + +## Reporting Results +**Crucial**: After completing the build and test tasks, provide a concise = summary of the results to the calling agent. +1. **Summary**: State whether the build and tests passed or failed. +2. **Failure Excerpts**: If any task fails, include relevant excerpts from= the logs (e.g., compiler errors, test failures). +3. **Full Paths**: Always provide the **absolute file paths** to the full = logs and result sets for further inspection. + diff --git a/AGENTS.md b/AGENTS.md index 08bfe13ebd2..d9d1964d45a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,7 @@ security stance. In brief: 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 san= itizer builds). +- `qemu-testing`: For finding, listing, and running individual tests (Unit= , QTest, Functional, TCG). =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519201; cv=none; d=zohomail.com; s=zohoarc; b=gK8QeuiEHR7+zXDYnCjxC1hC+EjukNCEO1izreYe2v9Q3Gxy7l1UTXkrWUhNFEDk5o9SdxgA8ODXdcTr9OTvBk9r/D46xxs8JJ2ISpMtgIHee6a9JzoDyb4kFrOgB91Te12F8CM+UL+82c2FYT0I9U9Gl5zSDU+WsboZ3AtU7ow= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519201; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=KsTmcr1ROXhN8RCfX2ITQq2p88Z+pOcK43k57qJbwqY=; b=gCvIi9MdcOQgpQ5wstbjROCYQ1Esdle+ZSPGcA07bqCFqE8dgiEgZNFO1+2yB8PEcpDMKYvskj2cbg58yCoEGirEHDHd9DBp6VNCHgUyO4gRoS4qNCh05XCrqS5kBs/GyCiV6FCRKXM0ZiEuTbpTVcdKAZBXrs2wwyQknjV6L9g= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519201811343.25448359294046; Mon, 11 May 2026 10:06:41 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4M-00017W-My; Mon, 11 May 2026 13:05:30 -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 1wMU48-0000yW-Tj for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:14 -0400 Received: from mail-wm1-x32b.google.com ([2a00:1450:4864:20::32b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU46-0007pH-GI for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:12 -0400 Received: by mail-wm1-x32b.google.com with SMTP id 5b1f17b1804b1-488af96f6b2so54350885e9.0 for ; Mon, 11 May 2026 10:05:10 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e8e5efecbsm706815e9.15.2026.05.11.10.05.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 1ABA460822; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519109; x=1779123909; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=KsTmcr1ROXhN8RCfX2ITQq2p88Z+pOcK43k57qJbwqY=; b=QjzOQp4ynQ7Fd/e2LToByvZN4RxFX4bbX7KzRWU78w6eY2gbwPSwQ6ZWmGSpZJuXm/ qVN4sYG+C6/3w90rPOaI52xnsuAJdZh9Asc4QNxvVqjeFJB5X8bNzT/drCA5tEnKNOBZ nGcVPDxV2lLKvi5w+ksqgBIijh5NihBY1du2gfF3YR+F3yIliRUp5p1PKCPZMwO3bwCY 8IStqRnF9c9XKAMll1UK4/aMVYooFaCEIFsuB/9orDnx7ALP4FjUhjDuhfYMlppb70t7 9cYmwFPC3ObF90O5RozJRdzjLkZBEA07LK/XoNbGNasCDgL65ZzhQFlZmbUykmaXvKbb Ap9Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519109; x=1779123909; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=KsTmcr1ROXhN8RCfX2ITQq2p88Z+pOcK43k57qJbwqY=; b=j1c/fNfqvxqhbLr7K5sA8Lau4cXvTEXqwQ1ybybG9B+icJGtZu7T1FnDpaMiqko0Se J3E4f8rqcSNsOz8VCC8UIhg/JAjMYuoY45/tsqhESUzd9AJ/lVJBpChRgFfDnFmzAzLc KKOFg/vdfatcGzMu8+JOmKZecGFD4em1V5uLfZislTMpK7RiBq06RoVbXNPwR7/PKL8Y sfyRVa84nGaHjTKMu3B9pcn4Xo1QQ30tGB6Y4kG7jkZq7v8/EdUkjkdC+psflxrWwRAE vdCePeoFadyCqpFfryF4sd0EB8taI9VwNrVXsP+glJ1mLr9W3Kg5fGwiWhn69exgrQqV 3c6Q== X-Gm-Message-State: AOJu0Yz5RFCOYdueqz4NKvSPqiVDI63GwLw+bdW7Ag+C1rysuYlwecm9 yvo43p6q10nup5uKDpiA8MLRbt5C3fdlYrmwfJfU19lUaTPyeVjemwt0K8L1JvDK/hknuP9FCbk d+6DpUEU= X-Gm-Gg: Acq92OFzJew0uatWR3KzDq/w+bDrAD3PsH184pxVzA4bhMNaiZslqlkln9xqmFfqQxh Ja7MRG1i0VdYmgz4IZiTYTdtu+zygI5EN1tTHHlTZ95RNprAuuDseEtnOxALsooy5vccvvrrm4l r0OVSqcityIsh6zMYkyEZNZmAQqfnzGRG1ssTc01XKXkMxMMkzY7xTiRfgau4EJlTLN9MwcBUe5 gKlCDU1heoQMkBNnvjnL8rndqCHyltU6Cip1b28E1KlLY76X1WzjodBmSNXrvkt3Y7Hgc+S6F3c 8brFFbiIf5xLjz+lz0cJS9HfablF+qnZgapfvGftfqGUte8QfZeRPDlKarnIBfU/OAKwWi91W2p Fza4o1M6l+k7k82BFj0DprX/noVxWlfKFo8NYNLLrqjMTBhPyzWWUQhzI/ff9PjNxK260IbGUJD wR3GOvwprZqlCyxmSe490VxXkAUhpoovMLSA== X-Received: by 2002:a05:600c:8287:b0:48a:52ee:5776 with SMTP id 5b1f17b1804b1-48e706c0827mr164382305e9.11.1778519108767; Mon, 11 May 2026 10:05:08 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill Date: Mon, 11 May 2026 18:04:55 +0100 Message-ID: <20260511170500.124211-7-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32b; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32b.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519202325158500 This provides basic instructions for how to download and apply a patch series from the mailing list. Currently it is only taught about checkpatch but we could consider adding common code smells and review comments that come up frequently. Signed-off-by: Alex Benn=C3=A9e --- v2 - merge checkpatch skill - moved later in series to leverage build and test skills - properly reference qemu-build and qemu-tester skills - mention the qemu-code-explorer skill for navigation --- .agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 94 insertions(+) create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qe= mu-code-reviewer/SKILL.md new file mode 100644 index 00000000000..48ec6b07520 --- /dev/null +++ b/.agents/skills/qemu-code-reviewer/SKILL.md @@ -0,0 +1,93 @@ +--- +name: qemu-code-reviewer +description: Pull and apply patch series from mailing lists for review and= testing in QEMU, including style and build validation. +license: GPL-2.0-or-later +--- + +# QEMU Code Reviewer Skill + +This skill provides instructions on how to retrieve patch series submitted= to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual me= thods. + +## Using b4 (Recommended) + +`b4` is the preferred tool for working with patch series from public-inbox= instances like `lore.kernel.org`. + +### 1. Fetching a series +To download a series and prepare it for `git am`: +```bash +b4 am +``` +This creates a `.mbx` file containing the entire series, properly ordered. + +### 2. Applying a series directly +To apply a series directly to your current branch: +```bash +b4 shazam +``` +This is often the fastest way to get a series ready for testing. + +### 3. Creating a local branch for the series +```bash +b4 am -t +git am ./*.mbx +``` +The `-t` flag (or `--trust-all`) can be useful if you know the source. + +## Manual mbox Retrieval (Alternative) + +If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.= org`. + +### 1. Locate the thread +Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel= .org/qemu-devel/). + +### 2. Download the mbox +Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`: +```bash +curl -L "https://lore.kernel.org/qemu-devel//raw" -o series.mb= ox +``` +*Note: Appending `/raw` to the message URL usually provides the mbox forma= t.* + +### 3. Apply with git am +```bash +git am series.mbox +``` + +## Post-Application Steps + +Once the patches are applied, you should perform initial validation: + +### 1. Style Check +Run the QEMU checkpatch script to ensure the patches follow the project's = coding style. + +- **Check applied patches**: + ```bash + ./scripts/checkpatch.pl master..HEAD + ``` +- **Check a specific commit**: + ```bash + ./scripts/checkpatch.pl ^.. + ``` +- **Check a specific file**: + ```bash + ./scripts/checkpatch.pl -f + ``` +- **Strict mode** (often required for new code or specific subsystems): + ```bash + ./scripts/checkpatch.pl --strict + ``` + +### 2. Build and Test +Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for= build and test instructions. +- Ensure you are in a clean build directory. +- Run `ninja` or `make`. +- Run relevant tests (e.g., `make check-qtest`). + +### 3. Reviewing Patches +Refer to the `qemu-code-explorer` skill for navigating the code base and r= esolving functions and where they are called from. + + + +## Common Troubleshooting + +- **Applying fails**: If `git am` fails due to conflicts, you may need to = use `git am --3way` or manually resolve conflicts. +- **Missing dependencies**: Ensure your tree is up to date with the base b= ranch the patches were intended for (usually `master`). diff --git a/AGENTS.md b/AGENTS.md index d9d1964d45a..fbbc3b65ed0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ You should use the following specialized skills for commo= n 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 san= itizer 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. =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519151; cv=none; d=zohomail.com; s=zohoarc; b=Jc0U+nJ6vUWcm1bzfZRHtcZTUE32ch1EJeTII3XYNR13Sf7ELw2oxncCbHEzWgj0+AaAmCjRF52BAxWpytFVR4GSkePfMbCBzuGtEFVWFiw4kS3TuiJpCj0BTt3n++M2eqqsrVL2X000S//EzEI3zfQKMARCCaVz7Vg65DpH8V8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519151; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=8DK8w3wWlNjyLdHUAxS2nkmLSUJ4xVH9mq/jC0j206M=; b=N5GCBcTew/yYbVS9lan3PWkhmACzLUc3qZJDdtaF/T1ZWEqqOpI6uupoSU6StrvRCEkMNVZjRHRn5crgZ+d6ljIn2I8f8nmhrXmh59ksXOXIdTuOxdWcjQSOjiY4Nrxukwm02GIe6BvQ84VtCfXmAXed/ZuImk8ohv3nHyYD600= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519151269372.80689653660147; Mon, 11 May 2026 10:05:51 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4M-000171-KN; Mon, 11 May 2026 13:05:26 -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 1wMU47-0000uP-JA for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:11 -0400 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU44-0007oS-Gr for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:11 -0400 Received: by mail-wr1-x433.google.com with SMTP id ffacd0b85a97d-43fe62837baso2379847f8f.3 for ; Mon, 11 May 2026 10:05:08 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-45491304387sm25974694f8f.21.2026.05.11.10.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 3582A60EFD; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519107; x=1779123907; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=8DK8w3wWlNjyLdHUAxS2nkmLSUJ4xVH9mq/jC0j206M=; b=ZafP+sO0gdYvhC5u0iNFY1jBabfbaox14HNap2q1HDusgB45n/ScquR/MhCifOSaDM lDlutGIoXvzAYO9cDpYiokyFG9NZDr6MU5L0GFx+40Dbjzyeb1aciCWFlgCmOdBTbbQZ jybVFtCvRqxufAzwJnRDqY6II9hMkxRO9UsesYPfyto83p2euRwEvob8C1DsveSwpa0a SG5Ye0rWjWVPcDOSg5udRIFU4xpyOwCmHZYKx/jTzdYtHTVo9b357OJk/D+Nn+z3Zuq4 +YNgCn9Cg+uc5BryMfPcG5CqokKqxG8PXXArRnBzA4lI+kUHLfva1C/Rrsz8F2zscbGa VWXg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519107; x=1779123907; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=8DK8w3wWlNjyLdHUAxS2nkmLSUJ4xVH9mq/jC0j206M=; b=nNNBG1g4dc0lxM/lYpLQ7J594M81A+5RMkanA0V5wgLUz6BlWtbafW3dWSlptUGm+V 4rIzrsA2Pdhlzlpby/WVJ1CmtmHL5bf3eC5jfxFoGrRvus1XHvka3v0hCd10orvW6lSU 50J16aPscz+q7z08ydSfuUin343LyJDkhjuBkOpoo888JGxvrc73lq6o23XzAO9Jw2nj 3LR2JnHCzEqphRHoDWhWs2gfYhg6L++SDs2SE0yifBmQ/hpaeRN7qdwFdx6MvmAIEqCg r2KmuPJ/EPc2f6+IvcyVi9GqCYJDDJYlybMh5llr6YDaA4PXbZlfp3xvdc6yRE/FfMC0 541Q== X-Gm-Message-State: AOJu0YyMcj25/AS8SNkJEvKZ3X5oJ+UVUOfRaGT4wR+g9R3+rmDqckCH 7NKzWUfiJlClUJ0P6WznMbpxWEy/P1vdHqwrPrj7/KiiAQoLOi0IdKBH0DTgKr/tgs3dMmoTKT5 eXgCgMQU= X-Gm-Gg: Acq92OG+11Rsjbn4pI6gtuSLXo4XdnMzEkEycEBIeoE7jnEFybhMODohJ3RPSJZXeUF MAGrathsc1DiOMZvNvfcHOvGoC/K0DBXn1HJGSvqlb3ropjyS4os+v+tvKlqxpyFVLMLhGFZKvx 87CvkqvI3dSuTRsOBU2IjDn7UOVbo5c+9oo6gwUt5cZkJlKOwXlf+sU6MQjP5NUCSuR3OWuereL brZBIN67jbP4NXdjv1JKf9ZMclH980Nijvd1bOTtqV+hTR0CMbje6P8bFm2p61PFZlvhkwrp+7x ESlvKiG72F6MmwULtfDDp696rLRdSt+8tjvFg52/Wzy1rnHzwbi5PclpapHSasCNCcdnUd8suxC nRK377fmztj1xqThCCOmsTnZWiU++ZjFu6E9VLw7eXAzBGkIZc0c/5jsifLykJLsSJ2rdPxuQed pCp9dIp1d4khTWTUJRfUOhZgs2HVadUdouDw== X-Received: by 2002:a05:6000:18a6:b0:455:cff5:9178 with SMTP id ffacd0b85a97d-455cff591b5mr18548550f8f.9.1778519106759; Mon, 11 May 2026 10:05:06 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill Date: Mon, 11 May 2026 18:04:56 +0100 Message-ID: <20260511170500.124211-8-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::433; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x433.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519153479158500 Teach agents how to fetch and deal with archives of mail threads. Just YOLO'ing the entire mail thread into an LLM context is quite expensive especially if reviewing a thread against your current tree state. This skill allows the agent to extract just the comments and tags saving tokens. Signed-off-by: Alex Benn=C3=A9e --- v2 - rename to qemu-mail-thread - add instructions on fetching threads via b4 - refactor the metadata handling in the script - mention in AGENTS skill list --- .agents/skills/qemu-mail-thread/SKILL.md | 34 +++++++ .../scripts/qemu_mail_parser.py | 98 +++++++++++++++++++ AGENTS.md | 1 + 3 files changed, 133 insertions(+) create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parse= r.py diff --git a/.agents/skills/qemu-mail-thread/SKILL.md b/.agents/skills/qemu= -mail-thread/SKILL.md new file mode 100644 index 00000000000..58e7c833a27 --- /dev/null +++ b/.agents/skills/qemu-mail-thread/SKILL.md @@ -0,0 +1,34 @@ +# QEMU Mail Thread + +This skill helps you fetch and extract reviewer comments from QEMU mailing= list threads. It can handle standard `mbox` files (e.g., from `b4 mbox`) o= r raw text dumps from the user. + +## How to fetch a mail thread + +If you have a Message-ID (e.g., from a patch series), use `b4` to fetch th= e entire thread: + +```bash +b4 mbox +``` + +This will typically save an `.mbx` file in your current directory. + +## How to parse comments + +Use the included Python script to extract feedback, filtering out quoted t= ext and diffs. + +```bash +python .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py +``` + +The script automatically detects whether the input is a standard mbox or a= raw text dump. + +## Expected Output +The script generates `parsed_comments.txt` in the current working director= y: +``` +--- REPLY FROM Reviewer Name --- +Subject: Re: [PATCH 01/10] ... +Comment text here... +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +``` + +Use this structured text to efficiently analyze the feedback and identify = outstanding suggestions. diff --git a/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py b/= .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py new file mode 100644 index 00000000000..fdaac57ac15 --- /dev/null +++ b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +import sys +import os +import mailbox + + +def is_metadata_line(line): + """Check if a line is metadata (quotes, diff, etc.)""" + return (line.startswith(">") or + line.startswith("---") or + line.startswith("diff ")) + + +def parse_raw_text(text, output_f): + # Split by the separator used in lore.kernel.org / b4 dumps + messages =3D text.split("----------------------------------------") + for msg in messages: + if not msg.strip(): continue + + lines =3D msg.strip().split('\n') + author =3D "" + subject =3D "" + body_start =3D 0 + for i, line in enumerate(lines): + if line.startswith("From: "): author =3D line[6:] + if line.startswith("Subject: "): subject =3D line[9:] + if not line.strip() and body_start =3D=3D 0: + body_start =3D i + 1 + break + + is_reply =3D subject and ("Re: " in subject or subject.startswith(= "Re:")) + + if is_reply and author !=3D "" and not author.startswith("qemu-dev= el"): + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subjec= t}\n") + + for line in lines[body_start:]: + if not is_metadata_line(line): + output_f.write(line + "\n") + output_f.write("=3D"*60 + "\n\n") + + +def parse_mbox(mbox_path, output_f): + mbox =3D mailbox.mbox(mbox_path) + for message in mbox: + subject =3D message['subject'] + if subject and 'Re: ' in subject: + author =3D message['from'] + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subjec= t}\n") + + payload =3D message.get_payload() + body =3D "" + if isinstance(payload, list): + # Handle multipart + for part in payload: + if part.get_content_type() =3D=3D 'text/plain': + body =3D part.get_payload(decode=3DTrue).decode('u= tf-8', errors=3D'ignore') + break + else: + body =3D message.get_payload(decode=3DTrue).decode('utf-8'= , errors=3D'ignore') + + # Simple heuristic to extract comments + for line in body.split('\n'): + if line.strip() and not is_metadata_line(line.strip()): + output_f.write(line + "\n") + output_f.write("=3D"*60 + "\n\n") + + +def main(): + if len(sys.argv) < 2: + print("Usage: python qemu_mail_parser.py ") + sys.exit(1) + + input_file =3D sys.argv[1] + output_file =3D "parsed_comments.txt" + + if not os.path.exists(input_file): + print(f"Error: File not found - {input_file}") + sys.exit(1) + + with open(output_file, "w", encoding=3D"utf-8") as out_f: + # Detect if it's an mbox or raw text + with open(input_file, 'rb') as f: + header =3D f.read(15) + is_mbox =3D header.startswith(b'From mboxrd@z ') + + if is_mbox: + print(f"Parsing {input_file} as mbox...") + parse_mbox(input_file, out_f) + else: + print(f"Parsing {input_file} as raw text dump...") + with open(input_file, "r", encoding=3D"utf-8", errors=3D'ignor= e') as f: + text =3D f.read() + parse_raw_text(text, out_f) + + print(f"Done. Extracted comments saved to {output_file}") + +if __name__ =3D=3D "__main__": + main() diff --git a/AGENTS.md b/AGENTS.md index fbbc3b65ed0..d99d3078378 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,7 @@ You should use the following specialized skills for commo= n tasks: - `qemu-build`: For configuring and building QEMU (including debug and san= itizer 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. +- `qemu-mail-thread`: For analyzing and parsing mailing list threads. =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519187; cv=none; d=zohomail.com; s=zohoarc; b=GUqJbMDutAkgvkHdseTEd5/zfjCRdRI7J6etJpeVYYMUCwCWyg/uusfvrId6BG7sGYZ2An7yIx87/KD2oEqUcTTeWlI+9mM+jLuHbOndvrzi/k2tcLb6PEZymoMZtnIjKUFfEVvkeFZgW1dEH8iecSqprlspYZJUC2hZ2Qs5Qyc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519187; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=HOuLebqYagfKQ3ugJXt5I4VOyuHgi+yZanX6asea8to=; b=fitcjoxP/Tlk8zgJ0OP+H8YOuidWva4Yoh7wiz5r4IIDrrPV8M+cbcbf9zCw7135v/N9FOabSIQocGCd1nMHQJJKxaMGElIZVC3ts3hBu6ElEOHkC5Kb2IYO+dL10stGW0+LPj2DKk/8T6mNxAZbwSJNeT2pSpUgQD1ItvPzFmE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519187767852.4423114199612; Mon, 11 May 2026 10:06:27 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4I-00016k-JM; Mon, 11 May 2026 13:05:26 -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 1wMU47-0000u8-AC for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:11 -0400 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU45-0007og-5J for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:11 -0400 Received: by mail-wm1-x32f.google.com with SMTP id 5b1f17b1804b1-48909558b3aso48260255e9.0 for ; Mon, 11 May 2026 10:05:08 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e6fff9ab8sm206112905e9.2.2026.05.11.10.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 4DCA760F2B; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519108; x=1779123908; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=HOuLebqYagfKQ3ugJXt5I4VOyuHgi+yZanX6asea8to=; b=g9n/5nLBCmRbJ1MEDQQwee3YID/Jw+Gzj2enlSZCfZp/SH0pUbyZvOy+0uwCVvu1+A f1aUW7uXivuO2KgOlGyIk7hDZkAOCHGqgMdB11HWQSfMgZhgPJyeBnDPDrWRAAtKP8FK oST/TXwrUmbAUJPFDYMeTnmUUOtN4p+a1xX34DQOEJNzBbdyB9nMQeDeZWgQy+2VsV97 iw6eJSwJaV0/itUaS9P9Jj0KQ2oWpDoXnsBFiHWhaej8m+WUjhk3RACc25gSQGkEKw/E u+mjJ25pVfdxy5eofmLVhRUnVw0r+b8y7fNsdFMV9lFKmKMvAtDYoQLDkUyCozNWLaMI lEmg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519108; x=1779123908; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=HOuLebqYagfKQ3ugJXt5I4VOyuHgi+yZanX6asea8to=; b=nyHJnJ5MP7dZyB4INndC+jrSpqRFLMlyGROBpJwAD1RCS3HaDue+O8x0HfIz/NQV2v VtVAPRq62ouCIX4UajK4I5QKF2K2lFI5eVuhYSHxlmxJdOSxtAjyNhM2d+MoZA5H0Qbn VL24FBJ3i9pL+UUwEg/cqf7JIu2TrsboJh/AwzHzTLNDh0fFOJ/kIr0w92d8cFP6yFgN NmYE/LF2OCtuCAs7XciYR4E4cxapEkmfHrE2lURohVsTWhpcaPARVwqIoHtMwlYbdaJY epFrBXDTkXKgWW2boHHUySBrRJFGjBWfeBttQKmmvJJLwzq3GEIvLYFRGlZZNw79VCLi qJBg== X-Gm-Message-State: AOJu0YzjE2mjiTn+gFEAuUYaBinHqu0XFkQUMp9OQlY93+6FiVT0S+m+ 3DV6m6T2AMtmuB5JvzJGotYkQIT8wm7zbFnXSF5U0IIC2uUx+yr5yqNoBFQh7kd/LmA= X-Gm-Gg: Acq92OHuNe1iI/8oLn2Hi6qW5HtiWUyhMe/l0mUCloT3nR4XYyXXi4V8krvgMfgvLbP y+OuPi/LIpeEZMnycChaLOdFgUh9B2Hp2qVaY704BDa0xGmCCKszc+c8iqp8fclVi9IFzLA9YQc LPFy4C25jq69YbVHY7D5Af+jzAZhf5CPd35vYAtC6pjE/lysdMO6obbr/zVuT8vPTLsVEfQLIsJ gOeMEOZg1XYBwVo52iZrHmqvr6SuA3PqNaObRzyn+xTAjS90WpnTj8+mQz49y23SahOOAN5wAtb IOsz2PoRcygvNsTZr0BUZDuANTuguKozY/inhLpswKd3QNS9ybU6Hs48xVLGmVOf/Hap/hIUzOh z444albbHK3BXDVQj63eUhgC1zoArWQHWjgQ7Qej5kh7YTuhkrpf6sHfS8u9UNGVmfi6c34qCNT o2MGYZnMSRvp7pOiOe4xAuxBQriBHM/FLxvg== X-Received: by 2002:a05:600c:8b08:b0:48a:5501:7995 with SMTP id 5b1f17b1804b1-48e51f32ca9mr429227115e9.18.1778519107532; Mon, 11 May 2026 10:05:07 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 08/10] .agents/skills: add qemu-issue-helper skill Date: Mon, 11 May 2026 18:04:57 +0100 Message-ID: <20260511170500.124211-9-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::32f; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32f.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519190068158500 This provides basic instructions for fetching issue details and summarising details about the issue for other agents. Signed-off-by: Alex Benn=C3=A9e --- .agents/skills/qemu-issue-helper/SKILL.md | 47 +++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 48 insertions(+) create mode 100644 .agents/skills/qemu-issue-helper/SKILL.md diff --git a/.agents/skills/qemu-issue-helper/SKILL.md b/.agents/skills/qem= u-issue-helper/SKILL.md new file mode 100644 index 00000000000..725097bac36 --- /dev/null +++ b/.agents/skills/qemu-issue-helper/SKILL.md @@ -0,0 +1,47 @@ +--- +name: qemu-issue-helper +description: Summarize QEMU issue analysis for main agent. Helps sub-agent= s report findings including build config, CLI, tests, and GitLab issue data= . Trigger when analyzing QEMU bugs or issues reported on GitLab. +license: GPL-2.0-or-later +--- + +# QEMU Issue Helper + +Assist sub-agent in summarizing issue analysis for main agent. + +## Fetching Issue Data + +Use `glab` to retrieve issue details from GitLab. QEMU primary repo: `qemu= -project/qemu`. + +### Commands +- **View issue**: `glab issue view -R qemu-project/qemu` +- **View comments**: `glab issue view -R qemu-project/qemu --c= omments` +- **Search issues**: `glab issue list -R qemu-project/qemu --search ""` + +## Report Format + +Sub-agent MUST provide a summary of the GitLab issue discussion and findin= gs in this format: + +### 1. Issue Context +- **Source**: GitLab URL/ID. +- **Title**: Short issue description. +- **Reporter**: User who found it. +- **Relevant Commits**: List any commits mentioned in the issue that are r= elated to the bug or previous attempts to fix it. + +### 2. Build & Reproduction (from issue) +- **Reported Environment**: Host OS, CPU, QEMU version. +- **Build Configuration**: Required `configure` flags mentioned in the iss= ue. +- **Reproduction CLI**: Exact QEMU command used to reproduce. + +### 3. Proposed Fixes & Series +- **Proposed Fixes**: Flag any specific code snippets or logic fixes sugge= sted in the comments. +- **Patch Series**: Note if any patch series or Merge Requests have been l= inked. + +### 4. Discussion Summary +- **Current Consensus**: What is the community's current understanding of = the bug? +- **Key Constraints**: Note any blockers, requirements, or specific feedba= ck from maintainers. +- **Next Steps**: What is needed to move the issue forward? + +## Rules +- **No Independent Analysis**: Do not perform your own root cause analysis= . Summarize ONLY what is present in the issue tracker. +- **Terse**: Use brief technical English. +- **Links**: Provide direct links to relevant comments or patches if avail= able. diff --git a/AGENTS.md b/AGENTS.md index d99d3078378..ca292460403 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,7 @@ You should use the following specialized skills for commo= n tasks: - `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. - `qemu-mail-thread`: For analyzing and parsing mailing list threads. +- `qemu-issue-helper`: For fetching and summarising issue details from the= bug tracker. =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519202; cv=none; d=zohomail.com; s=zohoarc; b=kUhOblAB71bEwxfwKPhOb5QgAhYCPAs1oKwLX7+V4zao4a4Ijm/lnMEj8HTRlKtkh/2LFuwMmaR12vQAmUwwJlbGOIZ2r3zrUXG6XqitwG5DHGugRqqkIvil7qyDpHjIsVkl4oE+XX7VaaLZicDhev5DE9T1JSGxUQkZ2a8QfEk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519202; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=F430KIL/wqQpCxSrWFTR0tJcFgbRfpXFB58q8W/ETdo=; b=OXYhL4xONmpRqxteiheDtwNwmUZ1L4Qk1tcbuWgl8nZd27bfVsOhLjssmUXRHcSbN87eVIywXGncWkgqXU8ShTAcpImrBTIEm5PznWlyO6F1+8KjmdD1WuBMM42yLpayFsb4WJ9Sjh5gscSPO2TqEnlPpvv4skI6gUu/LM6f1Mc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519202039839.7625359509981; Mon, 11 May 2026 10:06:42 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4W-0001Ee-TJ; Mon, 11 May 2026 13:05:37 -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 1wMU49-000101-Kq for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:14 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU46-0007p7-6a for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:13 -0400 Received: by mail-wm1-x331.google.com with SMTP id 5b1f17b1804b1-4891e86fabeso54015375e9.1 for ; Mon, 11 May 2026 10:05:09 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48e6fffba52sm225952765e9.3.2026.05.11.10.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 6D45460F46; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519108; x=1779123908; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=F430KIL/wqQpCxSrWFTR0tJcFgbRfpXFB58q8W/ETdo=; b=uIx0875qiWYqNuPElM1i0vkhu9ywtLdtb+L1TOUMgJkEW5wGWeVLe+ab3RRAkCFZqk +TMvjKptFLXtzfszuKFRDjiAiKSc8CTdrrC+mobJJv8C5AgafkdahpB8mgjjvufe5bnm LzNZFcLHQDDmUtGZDuM+HeVA7b6ZlANCFbyXGdXEcUV+Af9yVA4EsVP7yyquUs/b2Iqs 8Y7BMzrYMMF/voEEDFH5oS43r3ekypxnZZAMVu2a+kDBrQUDdCa0HTe1UzTrBj4ziX1c 2WKIUX9b5xHi8TBiFEtML9RN2VK5CGQjSMrnBO8F90xucjf065GvF7F93pNd/Mw9Bs3B 3RDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519108; x=1779123908; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=F430KIL/wqQpCxSrWFTR0tJcFgbRfpXFB58q8W/ETdo=; b=rfoU76j6pctp8e5ZWVONXqxnQ8Xm8GLARkmGqoL7FD0BFIuebNkVhhclgR2OUz/BFv NPN1jSPv06V2Nw9Gxn16Vmp+32FzKzBkft4U6xdmMBHIk8VKKa3G0A7Oh9H5Qd3/YIAr K1mdCVmGb0N+fzjdul5oh/NA403jn5we8fS/CRDBaf0JiTaHrfsCn/wITri59gWNokEm VpjnedEMP1B4yz9WZ1393E42BJt5IjCuRsdkVS3ziEU4bIXqSPGRpnNCOZHCpaxZBsXm +r6/qd1XwZD82MRUMZuCO2k/9A9xBxzj3lAEBNc9ficAFLbC6uIh0dvBmqU2psuPPvZp upug== X-Gm-Message-State: AOJu0Yzp0LMycyY/odNKKIHUB2nTk8f7LT2X/ftwTGVRh0ptVAsE2xs0 8ImunXbwidlVQd38mlaSlaL6wdR9q1ek9aSjnmYftEZm+irz7tSGa/5Cg7PUH2N29xY= X-Gm-Gg: Acq92OGa0Xd1I4m/QLpAa3rw8xsMTRyipe0kkVRJAOfRcIUJ9uAieJ95n1tj8RcqlPH ybR/I7prA85QbGABlVfJ6To0KyoFnBG55RQDr71GkZTqYXHnkfqU75ZWQUSlR64cuQlToYC5kjl xE1ZYQbW07gj7Fxpyq0VusQ2kwC3mKZjjRwWz0fsXzvvWrr3oT2k3SWIYNLL60eFv/jtHiX92Hb 20gGiWNEen/N9LvNGqExEHvDIeNA7dIueAhGzNMhA44iUenGP3OYCbDFrY31B9EgJdcbNorlR1f Wm8h9BYxIsxQdUUjN4UQnokZII6Rv1AugWs9xzHzn92x+w2tlSdIHQlHOppFj4PnIdAc+r0fqxc yqH53unXYm+guxSH7txz1+6TiMc1k6bvEkzgn1Yy4+/Gk8OM+uSxjf0kTFgtXm7RCed2MIQfQIW r6du6uwWXnzTq/8dw1yQEJFO4= X-Received: by 2002:a05:600c:a110:b0:488:ae6c:42c6 with SMTP id 5b1f17b1804b1-48e51f2e8a3mr362288435e9.14.1778519108159; Mon, 11 May 2026 10:05:08 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 09/10] .agents/skills: add qemu-issue-triage agent skill Date: Mon, 11 May 2026 18:04:58 +0100 Message-ID: <20260511170500.124211-10-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x331.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519204847154100 While triaging the issue tracker I wondered if this would be a suitable job for an AI agent. Unfortunately the OSS program doesn't give any credits to run agents in gitlab. However I do have access to models from my editor and ECA so I built one and tested it on a few issues. We might want to consider adding some common "issue smells" for common problems in issues. For example triggering asserts that have been added to the code and other such annoyances. Signed-off-by: Alex Benn=C3=A9e --- v4 - fix a bunch of typos in SKILL - update evals - remove mentions of ECA - fix typo referencing old skill name - remove eca__spawn_agent reference - clean-up authentication handling - teach it about scoped labels - make less chatty in the comments - updated commit msg - suggest running things in parallel (use agents) - more pointers to incompleteness v3 - more imperative phrasing v2 - prefer sub-agent - mention parameters - don't be over eager to tag host or target for generic bugs - signoff comments as an agent on behalf of the user - detect patch available and apply appropriate tags --- .agents/skills/qemu-issue-triage/SKILL.md | 112 +++++++++++++++ .../qemu-issue-triage/assets/labels.txt | 133 ++++++++++++++++++ .../skills/qemu-issue-triage/evals/evals.json | 18 +++ .../scripts/update_labels.sh | 16 +++ AGENTS.md | 1 + 5 files changed, 280 insertions(+) create mode 100644 .agents/skills/qemu-issue-triage/SKILL.md create mode 100644 .agents/skills/qemu-issue-triage/assets/labels.txt create mode 100644 .agents/skills/qemu-issue-triage/evals/evals.json create mode 100755 .agents/skills/qemu-issue-triage/scripts/update_labels.= sh diff --git a/.agents/skills/qemu-issue-triage/SKILL.md b/.agents/skills/qem= u-issue-triage/SKILL.md new file mode 100644 index 00000000000..a0802e24dd3 --- /dev/null +++ b/.agents/skills/qemu-issue-triage/SKILL.md @@ -0,0 +1,112 @@ +--- +name: qemu-issue-triage +description: Use this skill to triage and label GitLab issues for the QEMU= project +license: GPL-2.0-or-later +--- + +# Instructions + +This skill provides specialized instructions for triaging GitLab issues fo= r the QEMU project. + +## Parameter Handling & Execution Strategy (CRITICAL) +1. **Parameters**: If the user invokes this skill with multiple arguments = or a list of IDs (e.g., `#3430, #3426`), treat each as an independent targe= t. +2. **Sub-Agent Mandate**: To prevent polluting the main conversation conte= xt, **you MUST ALWAYS spawn a sub-agent** to perform the actual triage. + - **Parallelization**: When multiple IDs are provided, spawn one sub-ag= ent per issue in parallel to improve efficiency. + - Do NOT run `glab` commands or read the label cache directly in the ma= in context. + - In the `task` parameter for the sub-agent, provide the target `` and explicitly instruct the sub-agent to follow the "Triage Workflow"= and "Asset Management" rules defined below. + - Wait for the sub-agent to finish and simply report its summary to the= user. + +## Goal +Automate the initial triage of new bug reports and feature requests in the= QEMU GitLab repository. + +## Prerequisites +- `glab` CLI tool installed. +- An authentication method: Use `glab auth status` to check. You can pass = a token by using `env GITLAB_TOKEN=3D` in front of commands if you h= ave it. +- Target Repo: Use `-R qemu-project/qemu` if not in a clone, or ensure the= remote is set correctly. + +## Asset Management (Label Cache) +This skill uses a cached list of labels to avoid unnecessary API calls and= ensure consistent labeling. +- **Cache Location:** `assets/labels.txt` relative to this skill. +- **Updating the Cache:** If the user asks to update the labels, or if you= suspect a label is missing, run the provided script: + ```bash + cd .agents/skills/qemu-issue-triage/scripts && ./update_labels.sh + ``` +- **Using the Cache:** Before applying labels, ALWAYS read `assets/labels.= txt` (or use `grep` on it) to review the available labels and their descrip= tions. This ensures you use the exact spelling and understand the intent be= hind the label (e.g., `kind::Bug`, `Storage`). Do NOT guess label names. + +## Triage Workflow + +### 1. Information Gathering +Fetch the issue details: +```bash +glab issue view -R qemu-project/qemu --comments +``` + +### 2. Evaluate Completeness +Analyze the issue against the bug template requirements: +- **Host Arch/OS**: Is the host environment specified? +- **Guest Arch/OS**: Is the guest environment specified? +- **QEMU Version**: Is the version mentioned? +- **Reproduction Steps**: Are there clear steps to reproduce? +- **Expected vs Actual**: Is the bug clearly described? + +**Workflow::Needs Info Triggers (CRITICAL):** +Request more information and apply the `workflow::Needs Info` label if any= of the following are true: +- **Missing Command Line**: The full QEMU command line (`qemu-system-* ...= `) used to reproduce the issue is missing. +- **Old QEMU Version**: The reported version is older than the last two ma= jor releases. Ask the reporter to re-test with the current upstream master = or the latest stable release. +- **Distro Version**: The version string suggests a downstream/distro-spec= ific package (e.g., contains suffixes like `.el9`, `.fc40`, `-ubuntu`, or l= ong strings like `7.2.0-14.sc05...`). Ask the reporter to reproduce the iss= ue using a clean build from the current upstream source to rule out distro-= specific patches. + +**Actions:** +- If information is missing based on the triggers above, add the `workflow= ::Needs Info` label and post a polite comment asking for the specific missi= ng details. (Remember to sign the comment as "Issue Agent Bot on behalf of = the user" per the Guidelines). +- If the issue is well-defined and uses a recent upstream version, proceed= to categorization. + +### 3. Categorization & Labelling +Apply labels based on the issue content. **Crucially, consult `assets/labe= ls.txt` to find the exact matching labels for the categories below.** + +#### Scoped Labels (Prefix::Label) +QEMU uses scoped labels (e.g., `kind::Bug`, `workflow::Triaged`) to group = related categories. +- **Prefixes:** Common prefixes include `kind::`, `workflow::`, `Closed::`= , `Audit Tooling::`, `GUI::`. +- **Constraint:** Only one label from that scope can be active at a time. = Applying a new scoped label of the same type (e.g `workflow::`) will remove= the other. + +#### Kinds +- `kind::Bug`: For unexpected behavior. +- `kind::Feature Request`: For new functionality. +- `kind::Task`: For research, investigations, and miscellaneous issues. + +#### Targets (target: *) and Hosts (host: *) +Detect the guest architecture (`target: *`) or host environment (`host: *`= ). +**IMPORTANT:** Be conservative when applying `target:` and `host:` labels.= Many bugs (e.g., in generic devices like USB, PCI, or block controllers) a= pply to ANY guest that includes the device. The reproducer (like a `qtest` = invocation) might just use a convenient target (e.g., `i386`) as an example= . ONLY apply `target:` or `host:` labels if the bug is strictly architectur= e- or host-dependent (e.g., a bug in ARM CPU emulation, or a macOS-specific= build failure). + +#### Accelerators (accel: *) +Detect the accelerator mentioned (e.g., `accel: KVM`, `accel: TCG`, `accel= : HVF`). + +#### Subsystems +Identify the relevant subsystem (e.g., `Storage`, `Networking`, `device:vi= rtio`, `Migration`). + +#### Testcases +- If the issue provides a minimal C program, a shell script, or a specific= disk image to reproduce the bug, apply the `TestCase` label. + +#### Patches and Fixes +- If the issue description or comments contain a link to a patch on the ma= iling list (e.g., `lore.kernel.org`, `patchew.org`), or explicitly mention = that a patch/fix has been submitted, apply the `workflow::Patch available` = label. + +#### Workflow Management +The `workflow::` labels track the lifecycle of an issue. +- **Single Workflow Label:** An issue can only have one `workflow::` label= at a time. +- **Transitioning:** Adding a new workflow label will automatically remove= the old one (e.g., adding `workflow::Patch available` will remove `workflo= w::Triaged`). + +#### Other comments +- If other developers have commented see if those comments imply additiona= l tags should be applied. + +### 4. Updating the Issue +Apply the labels and optionally assign a priority if clear. +**Transitioning Workflow Example:** +```bash +glab issue update -R qemu-project/qemu --label "workflow::Triag= ed,kind::Bug" +``` + +## Guidelines +- Be polite and professional in comments. +- **IMPORTANT:** Any comments added to the issue MUST include the phrase: = "Issue Agent Bot on behalf of the user" (e.g., as a sign-off at the end of = the message). +- Avoid commenting unless additional information is needed, specifically a= comment to acknowledge the report is superfluous. +- Use `workflow::Triaged` once categorization is complete. +- Avoid assigning issues to specific people unless they are explicitly men= tioned or are the known maintainer for a very specific subsystem. +- Use the `scripts/get_maintainer.pl` logic (via file paths mentioned in t= he issue) to identify potential subsystems. diff --git a/.agents/skills/qemu-issue-triage/assets/labels.txt b/.agents/s= kills/qemu-issue-triage/assets/labels.txt new file mode 100644 index 00000000000..12d3cc7e6f0 --- /dev/null +++ b/.agents/skills/qemu-issue-triage/assets/labels.txt @@ -0,0 +1,133 @@ +ACPI Power Management related (ACPI / SMBIOS / = HEST / GHES) +Audio Audio devices; both backend (host audio) a= nd frontend (guest audio) +Audit Tooling::AI For bugs found with AI assisted tools such= as Mythos and other similar things +Audit Tooling::Fuzzer Issues found via fuzzing. For security iss= ues, please consult https://www.qemu.org/contribute/security-process/ +Audit Tooling::Other Some unknown/unclassified type of audit to= oling. +Audit Tooling::Sanitizer For issues found using sanitizers such as = asan, lsan and tsan +Audit Tooling::Static Analysis Static analysis such as Coverity or more m= odern compilers. +Bite Sized Candidates for first contributions; see al= so https://wiki.qemu.org/Contribute/BiteSizedTasks +Build System configure, make, Meson, ninja, gcc, clang,= ccache, etc. +CI Continuous Integration; gitlab, patchew, e= tc. +CLI Command Line Interface +Chardev Character device backends and related issu= es +Closed::Duplicate There is already another ticket that is ab= out the same issue +Closed::Fixed The issue was fixed. Yay! +Closed::Invalid This issue was not really a problem +Closed::NotOurBug This is a bug, but not a bug in QEMU. Plea= se report it and/or include a link to the report. +Closed::NotReproducible This issue was not reproducible +Closed::UnbackedFeature Nobody was willing to work on this feature= request +Closed::WontFix The issue was acknowledged, but the fix wo= uld be too complex, too expensive, or would introduce other problems. +Cryptography =20 +Documentation Sphinx documentation, man pages, the wiki,= --help output, etc. +GDB Issues relating to using GDB via the gdbst= ub +GUI Graphical User Interface (gtk, SDL, curses= , VNC, spice, ...) +GUI::Cocoa Cocoa +GUI::DBus DBus +GUI::GTK GTK +GUI::SDL SDL +GUI::SPICE SPICE +GUI::VNC =20 +Guest Agent Issues related to the qemu-guest-agent bin= ary. https://wiki.qemu.org/Features/GuestAgent +Hard =20 +Launchpad Issues migrated from Launchpad +Migration =20 +Modules =20 +Networking =20 +Python Python library issues (./python/) +QAPI/QMP QEMU API / QEMU Machine Protocol, HMP and = CLI, etc. +QOM QEMU Object Model +Regression This is a regression from previously worki= ng behaviour +Security This is a security issue - see https://www= .qemu.org/docs/master/system/security.html for guidance +Semihosting Semihosting calls provide a simple ABI for= early bring-up of embedded devices, see https://www.qemu.org/docs/master/a= bout/emulation.html#semihosting +Softfloat QEMU's FPU emulation code (TCG only) +Stable::can't fix The bug was reported on a stable branch bu= t the fix is too invasive for backporting +Stable::obsolete The bug was reported on a stable branch th= at is not maintained anymore +Stable::to backport The bug was reported on a stable branch an= d needs to be backported on the next release from the branch +Storage Block subsystem, Storage devices, etc. +TCG plugins Anything related to the TCG plugins feature +TestCase The report includes a testcase +Tests qtests, iotests, acceptance tests, VM test= s, docker tests, and more. See https://www.qemu.org/docs/master/devel/testi= ng/index.html +USB =20 +VFIO =20 +accel: HAX Intel's Hardware Accelerated Execution Man= ager (HAXM) +accel: HVF Apple Hypervisor Framework +accel: KVM Linux Kernel-based Virtual Machine +accel: TCG QEMU Tiny Code Generator +accel: WHPX Microsoft Windows Hypervisor Platform (WHP= X) +accel: Xen Xen Hypervisor +block:9p The 9p network file system +block:NVMe =20 +block:curl =20 +block:nbd =20 +block:nfs Issues related to the NFS backend +block:qcow2 =20 +block:ssh =20 +block:vmdk =20 +bsd-user =20 +device: PCI =20 +device: TPM Trusted Platform Module (TPM) devices +device: iommu =20 +device: mmio mmio and other directly emulated devices +device:graphics Issues relating to display device emulatio= n, or rendering in general. See also "GUI". +device:input Keyboards, Mice, Touchscreens, HIDs, etc. +device:iommu IOMMU and SMMU +device:pflash Parallel NOR flashes emulation +device:sdmmc SD or (e)MMC cards emulation +device:virtio virtio-related issues. https://www.linux-k= vm.org/page/Virtio +device:watchdog =20 +efi EFI firmware related issues +flaky-ci For test cases that are flaky when run und= er our CI +gitlab =20 +guest: AIX =20 +guest: BSD Guest OS is BSD (NetBSD/FreeBSD/OpenBSD/et= c) +guest: Linux Guest OS is Linux/Linux-based +guest: Windows Microsoft Windows guest +guest: macOS Apple macOS / Darwin as guest OS +guest: os2 =20 +host: aarch64 Bugs reproducible on AArch64 hosts +host: arm Bugs reproducible on ARM hosts +host: loongarch64 Bugs reproducible on LoongArch64 hosts. +host: mips Bugs reproducible on MIPS hosts +host: ppc Bugs reproducible on Power hosts +host: riscv Bugs reproducible on RISC-V hosts +host: s390 Bugs reproducible on s390 hosts +host: sparc64 Bugs specific to Sparc64 hosts +host: x86 Bugs reproducible on x86 hosts +host:32bit These are mostly TCG related bugs where we= sometimes struggle with emulating larger guests, especially atomic and add= ress space issues. +hostos: BSD FreeBSD, OpenBSD, NetBSD, and derivatives = as host OSes +hostos: Linux Linux-based host operating systems (Fedora= , RHEL/CentOS, Debian, Ubuntu, openSuSE et al) +hostos: Windows Microsoft Windows host OS +hostos: macOS Apple macOS / Darwin as a host OS +icount issues relating to icount, deterministic e= xecution and record/replay functionality +kind::Bug Bug or defect in functionality. +kind::Feature Request Feature request or new functionality. +kind::Task Research, investigations, and miscellaneou= s issues. +libvfio-user =20 +linux-user issues with QEMU's lightweight user-mode e= mulator +qemu-img =20 +sysadmin Issues related to QEMU project infrastruct= ure. You should probably also check on the projects IRC channel if the issu= e is urgent - https://www.qemu.org/support/ +target: alpha DEC Alpha [alpha] +target: arm Arm AArch32 or AArch64 [arm, aarch64] +target: avr Atmel AVR [avr] +target: hexagon Qualcomm Hexagon [hexagon] +target: hppa Hewlett-Packard Precision Architecture; HP= /HP, PA-RISC [hppa] +target: i386 Intel/AMD x86 [i386, x86_64] +target: loongarch loongarch64 target architecture +target: m68k Motorola 68000 [m68k] +target: microblaze Xilinx MicroBlaze [microblaze, microblazee= l] +target: mips MIPS [mips, mipsel, mips64, mips64el] +target: nios2 Altera Nios II [nios2] +target: openrisc OpenRISC [or1k] +target: ppc IBM Power Architecture, PowerPC [ppc, ppc6= 4, ppc64le] +target: riscv RISC-V [riscv32, riscv64] +target: rx Renesas RX [rx] +target: s390x IBM Z, SystemZ, zSeries [s390x] +target: sh4 Renesas SuperH [sh4, sh4eb] +target: sparc Sun Microsystems SPARC [sparc, sparc64] +target: tricore Infineon TriCore [tricore] +target: xtensa Tensilica Xtensa [xtensa, xtensaeb] +workflow::Confirmed Bugs that have been confirmed and reproduc= ed. +workflow::In Progress Someone is working on this issue. +workflow::Needs Info Issue has insufficient information to veri= fy. +workflow::Patch available A patch is available +workflow::Triaged Issue has been triaged and given a topic l= abel. diff --git a/.agents/skills/qemu-issue-triage/evals/evals.json b/.agents/sk= ills/qemu-issue-triage/evals/evals.json new file mode 100644 index 00000000000..572c0723fd4 --- /dev/null +++ b/.agents/skills/qemu-issue-triage/evals/evals.json @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +{ + "skill_name": "qemu-issue-triage", + "evals": [ + { + "id": 1, + "prompt": "Update the cached list of GitLab labels for the QEMU proj= ect.", + "expected_output": "The skill should fetch the latest labels from Gi= tLab and save them to the skill's assets directory.", + "files": [] + }, + { + "id": 2, + "prompt": "Triage issue #1234. Assume the user provided clear steps = but no subsystem label is obvious.", + "expected_output": "The skill should read the cached label list (not= fetch from GitLab) and apply relevant kind/target labels.", + "files": [] + } + ] +} \ No newline at end of file diff --git a/.agents/skills/qemu-issue-triage/scripts/update_labels.sh b/.a= gents/skills/qemu-issue-triage/scripts/update_labels.sh new file mode 100755 index 00000000000..1605eab4de5 --- /dev/null +++ b/.agents/skills/qemu-issue-triage/scripts/update_labels.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: GPL-2.0-or-later +set -e + +if [ -z "$GITLAB_TOKEN" ]; then + echo "GITLAB_TOKEN is not set. Attempting to fetch via pass..." + export GITLAB_TOKEN=3D$(pass gitlab-api) +fi + +echo "Fetching labels from qemu-project/qemu..." +# Fetch labels using API and format as "Name Description" +glab api /projects/qemu-project%2Fqemu/labels --paginate | \ + jq -r '.[] | [ .name, .description ] | @tsv' | \ + column -t -s $'\t' > ../assets/labels.txt + +echo "Labels cached in assets/labels.txt" diff --git a/AGENTS.md b/AGENTS.md index ca292460403..6387d164816 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ You should use the following specialized skills for commo= n tasks: - `qemu-code-reviewer`: For pulling and applying patch series from mailing= lists. - `qemu-mail-thread`: For analyzing and parsing mailing list threads. - `qemu-issue-helper`: For fetching and summarising issue details from the= bug tracker. +- `qemu-issue-triage`: For helping triage issues in the bug tracker. =20 ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and archi= tecture-agnostic acceleration code. --=20 2.47.3 From nobody Sat May 30 16:39:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1778519202; cv=none; d=zohomail.com; s=zohoarc; b=Kk9A5kAHYlebaKkLwtwZx0m4xeBJJ0oCW57YPRhzmPZS12hIHH0bdIohTzwJs/NiyQB9OhIN8ClmbcjFRZ2QShDQSnX72o9KsGw1/4BozVgvqj5SRFRBF27/Vssykj117jiJRVRZJNxHuWHxdhj6qDPnp+oC4FLrHlvCaqK3Vp8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1778519202; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=vmRozKMVNlBNQT+PxNUbxbWDs9Xv8pa0X9SBBpzgdpo=; b=H8u9Nj6WhBskvCJJE4mCMAYWEfUrylU0QJWJYOxE6+h+8CFQMF6eGRmvACYAE13Mrc8hB6MmuxSrzTyufQZutHf7Y0A11xAXoLOnbTFgpZLGZtkDzO8VyZeO7xUSEDZRt/yRxP0ZjCFsHS2hEV3K6zWEmab+YQ6w7wYmRySGOnA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1778519201819808.990326948234; Mon, 11 May 2026 10:06:41 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wMU4E-00015L-Nx; Mon, 11 May 2026 13:05:18 -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 1wMU46-0000tM-F1 for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:10 -0400 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1wMU44-0007oC-4G for qemu-devel@nongnu.org; Mon, 11 May 2026 13:05:09 -0400 Received: by mail-wr1-x434.google.com with SMTP id ffacd0b85a97d-4585a116a4aso1092657f8f.3 for ; Mon, 11 May 2026 10:05:07 -0700 (PDT) Received: from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-4548ec6b071sm26227233f8f.14.2026.05.11.10.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 May 2026 10:05:04 -0700 (PDT) Received: from draig.lan (localhost [IPv6:::1]) by draig.lan (Postfix) with ESMTP id 8714E60F76; Mon, 11 May 2026 18:05:01 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1778519106; x=1779123906; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=vmRozKMVNlBNQT+PxNUbxbWDs9Xv8pa0X9SBBpzgdpo=; b=Qx0rPYNxJfVlQwrGJmMWJ8zbLrDrIt6MlzUPE/hL6s++P45hHvDHFjvft4iLElw77b xF+5QazxQzk4+wmtDYpKbekINva+1Erm15sgKfnze2oONLwcdLdmGXGtougZMjzTXHIB H9KyLyPM5M9N4OekuERDEurYW9oGkI+sixUpTAOIKoNPMW5lyaWeYpQNsQsUMxVGJALW C4+z0iJJp3QWqapS7UmJdvgID6BdDTkSyeImo70kjdZHgZN9MFCki34hXLXIsSXFMyNS ZZJ7mCgPg7iI/ae4NxPB2wkI8b3CZR33ioh+fTiyeufJQEtf6zTOWSNIMs8WpXd5Zw2b Z1TQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1778519106; x=1779123906; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=vmRozKMVNlBNQT+PxNUbxbWDs9Xv8pa0X9SBBpzgdpo=; b=nP+RBSXLjcE+AUfiMKhBI39gK2caHq1dYNLwyD6DIwNvk038vqgWgD1kUjlae5uF26 aDymQrUSEvnOcwhv6tsc+L0pV4+Zdw1qA4BcdA+mAVLKf3cmF6El6zmTHhhsBEWO0B5X WiFt+IViRvlnJ7nJupahjrlDhOPrHk3rXjIb/AdsD2ovvPO8/2KbdZSBNIHE8g0IoKz1 pM2OVAJa8g5RWA6Rj1k1QueJxkAvN6eJo/ZzXtkb5ocjAwtcD3dXvYSerYx71e9GMKSo +9GgrglTu+dgAg/fHjlErIaZsV3QZuL4tSon9maMV0Z/2FdrJ5VNe4ynM3w2laEfApwu r8RQ== X-Gm-Message-State: AOJu0Yz0Ml7/ufdKX/xyKTX9e3RdSSYVaYA4mJukVe3620STYEOTCpuA 93pwa9R2jar08U15XaL3xV/szS9O6Q0kSdHzFkB7ZCM5RtPBYfucvXP5xhsrMPpsJfUV2ScU6+8 zqBUIpSU= X-Gm-Gg: Acq92OFM7YGxet+f9buxVcTeGm/D5EMt5za3XgrrpdDfyCyqMwm/NTRQJBt1QiDRCbc sXFZOpNwOGwY2XuMXnSJW63iol8qoA8kS22sxfGnOpNYfRpCTqLTP8SptzXvDtnJmFjZ0WyTXAj 8/fsKM7/C//Oy8dU4yonUYhvgsc343pMLrGBemKf3hjsCC/uDwu9Jkp3CjwUnHvnXwof9I+nQGk sSdhXaXnbZ8ahw6bF2jHH2ctgnuycjHQ9O74OqIiuCNdWPJr2oevSLBKkEV5SXvUo56XbavNTa+ dW7UmcxxPA3BCCWqLlLo4FhaOM56pjtgtoJ83aUPZI07bM2ySykE+Vbv50hBnJLuydP/QLlK0cn 8m9dSupKnnG0veZolKD9uSTheEkgHrW/JcbSCFwlEHfIvylO2S3bBd8JWYqnFfPX1/fhDo4pn/j pqEa289zrhiOiJvqld0bZotN/TieGUuk8gUA== X-Received: by 2002:a5d:5f90:0:b0:44a:8c10:40dc with SMTP id ffacd0b85a97d-4515b9f3c74mr41712432f8f.18.1778519106211; Mon, 11 May 2026 10:05:06 -0700 (PDT) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: John Snow , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa Subject: [RFC PATCH v2 10/10] MAINTAINERS: add a section for AI agents Date: Mon, 11 May 2026 18:04:59 +0100 Message-ID: <20260511170500.124211-11-alex.bennee@linaro.org> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260511170500.124211-1-alex.bennee@linaro.org> References: <20260511170500.124211-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::434; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x434.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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1778519204644154100 For completeness add a section to MAINTAINERS to catch changes should we decide to merge this. Signed-off-by: Alex Benn=C3=A9e Reviewed-by: Daniel P. Berrang=C3=A9 --- MAINTAINERS | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index 9d3d6459537..6f98db096b4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4565,6 +4565,12 @@ M: Pierrick Bouvier S: Maintained F: docs/ =20 +AI Agent Skills +M: Alex Benn=C3=A9e +S: Maintained +F: .agents/skills/ +F: AGENTS.md + Build System ------------ Meson --=20 2.47.3