* [PATCH v2] agents: Add a skill for finding your way around QEMU
@ 2026-09-04 7:43 Paolo Bonzini
2026-09-04 10:29 ` Philippe Mathieu-Daudé
2026-09-04 10:46 ` Daniel P. Berrangé
0 siblings, 2 replies; 5+ messages in thread
From: Paolo Bonzini @ 2026-09-04 7:43 UTC (permalink / raw)
To: qemu-devel; +Cc: berrange, Alex Bennée
As a side effect, establish scaffolding for the .agents/.claude/.gemini
directories, as a base for future patches to build on.
Some parts of this skill are based on
https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
v1->v2: add .claude/.gitignore. Suggest using get_maintainer.pl and ./run.
Fix thinko around build/source directory
.agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
.claude/.gitignore | 2 +
.claude/skills | 1 +
.gemini/skills | 1 +
4 files changed, 104 insertions(+)
create mode 100644 .agents/skills/qemu-codebase/SKILL.md
create mode 100644 .claude/.gitignore
create mode 120000 .claude/skills
create mode 120000 .gemini/skills
diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
new file mode 100644
index 00000000000..17fb55b5289
--- /dev/null
+++ b/.agents/skills/qemu-codebase/SKILL.md
@@ -0,0 +1,100 @@
+---
+name: qemu-codebase
+description: Orientation for QEMU — tree structure, build system, documentation pointers
+---
+
+# Useful reminders for working on QEMU
+
+## Finding things
+
+`MAINTAINERS` is the authoritative list of subsystems. You can
+use it and `scripts/get_maintainer.pl --nogit` to query it, for example
+
+```
+$ scripts/get_maintainer.pl --nogit -f block/
+```
+
+`docs/devel/codebase.rst` is a guided tour of every top-level directory.
+Here are some important ones:
+
+- **target/** holds CPU models and the TCG frontends
+- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
+ `docs/devel/tcg-ops.rst`.
+- **hw/** is devices and boards, categorized by type.
+- **linux-user/** and **bsd-user/** are almost entirely separate, and only
+ have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
+ in common with system emulation
+
+Other directories include the back-end subsystems, for example **`block/`**
+for the block layer.
+
+The `include/` tree mostly mirrors the top-level tree.
+
+## Build layout
+
+Build is always out-of-tree; the build directory is created by
+`configure` and a checkout can have several. Determine it from context
+(`ls */meson-info`) rather than assuming.
+
+The `run` script in the root of the build dir wraps `meson devenv` and
+should be used to execute commands in the build directory. It activates
+the build tree's venv `pyvenv/`, adds various Python modules from
+the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
+variable for general use.
+
+`make` at the top level forwards to `ninja` in the configured build
+directory, and any `build.ninja` target can be invoked that way.
+
+## Build & Test
+- **Build**: `ninja` or `make -jN` from build directory
+- **Test All**: `make check`
+- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
+- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
+- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
+
+## Code Style
+- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
+- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
+- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
+- **C Comments**: Use `/* ... */` only. No `//` comments.
+- **Naming**: `snake_case` for variables and functions; `CamelCase` for types and enums.
+- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
+- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
+- **Lints**: Run `./scripts/checkpatch.pl`. On top, `make clippy` and `make rustfmt` for Rust.
+
+# Documentation pointers
+
+Developer docs live in `docs/devel`. A `kernel-doc::` directive includes
+documentation comments from source files when Sphinx builds the documentation.
+These comments be consulted just as easily in the source tree without going
+through e.g. `make html`.
+
+Here are some useful pointers.
+
+## Core abstractions
+
+- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
+ everything. It includes class and interface hierarchies, properties, and
+ the object composition tree. See `docs/devel/qom.rst`.
+- **qdev** builds devices on top of QOM, adding for example buses, the
+ realize/unrealize lifecycle (including hot-plug/unplug), and reset. See
+ `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
+- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
+ guest address-space model: regions, aliases, address spaces, dirty tracking,
+ load/store and map/unmap operations, etc. See `docs/devel/memory.rst`.
+
+## Concurrency
+
+Getting the threading model wrong is a common source of subtle bugs here.
+
+- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
+ hold it when exiting to emulation. See `include/qemu/main-loop.h`.
+ Memory regions can (carefully) opt out of the BQL.
+- **AioContext**/iothreads: block devices and their virtio front-ends can run
+ outside the BQL. See `docs/devel/multiple-iothreads.rst`.
+- The **block layer** is coroutine-based. `co_` prefixes and `coroutine_fn`
+ annotations are advisory but relevant for reviewers. Coroutines have their
+ own locking primitives.
+- **RCU** is used for hot, rarely-modified structures such as memory maps.
+ Because of the BQL, RCU is mostly used with `call_rcu()` rather than
+ `synchronize_rcu()`. See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
diff --git a/.claude/.gitignore b/.claude/.gitignore
new file mode 100644
index 00000000000..b0a57a19c01
--- /dev/null
+++ b/.claude/.gitignore
@@ -0,0 +1,2 @@
+# reserved for the user to add their own per-project rules
+/CLAUDE.md
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 00000000000..a7540c24423
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+.agents/skills/
\ No newline at end of file
diff --git a/.gemini/skills b/.gemini/skills
new file mode 120000
index 00000000000..a7540c24423
--- /dev/null
+++ b/.gemini/skills
@@ -0,0 +1 @@
+.agents/skills/
\ No newline at end of file
--
2.55.0
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH v2] agents: Add a skill for finding your way around QEMU
2026-09-04 7:43 [PATCH v2] agents: Add a skill for finding your way around QEMU Paolo Bonzini
@ 2026-09-04 10:29 ` Philippe Mathieu-Daudé
2026-09-04 10:46 ` Daniel P. Berrangé
1 sibling, 0 replies; 5+ messages in thread
From: Philippe Mathieu-Daudé @ 2026-09-04 10:29 UTC (permalink / raw)
To: Paolo Bonzini, qemu-devel; +Cc: berrange, Alex Bennée
On 4/9/26 09:43, Paolo Bonzini wrote:
> As a side effect, establish scaffolding for the .agents/.claude/.gemini
> directories, as a base for future patches to build on.
>
> Some parts of this skill are based on
> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>
> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
> v1->v2: add .claude/.gitignore. Suggest using get_maintainer.pl and ./run.
> Fix thinko around build/source directory
>
>
> .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
> .claude/.gitignore | 2 +
> .claude/skills | 1 +
> .gemini/skills | 1 +
> 4 files changed, 104 insertions(+)
> create mode 100644 .agents/skills/qemu-codebase/SKILL.md
> create mode 100644 .claude/.gitignore
> create mode 120000 .claude/skills
> create mode 120000 .gemini/skills
> +- **target/** holds CPU models and the TCG frontends
> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
> + `docs/devel/tcg-ops.rst`.
> +- **hw/** is devices and boards, categorized by type.
> +- **linux-user/** and **bsd-user/** are almost entirely separate,
common-user/ is where we are moving their common code.
> and only
> + have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
> + in common with system emulation
> +
> +Other directories include the back-end subsystems, for example **`block/`**
> +for the block layer.
> +
> +The `include/` tree mostly mirrors the top-level tree.
> +
> +## Build layout
> +
> +Build is always out-of-tree; the build directory is created by
> +`configure` and a checkout can have several. Determine it from context
> +(`ls */meson-info`) rather than assuming.
> +
> +The `run` script in the root of the build dir wraps `meson devenv` and
> +should be used to execute commands in the build directory. It activates
> +the build tree's venv `pyvenv/`, adds various Python modules from
> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
> +variable for general use.
> +
> +`make` at the top level forwards to `ninja` in the configured build
> +directory, and any `build.ninja` target can be invoked that way.
> +
> +## Build & Test
> +- **Build**: `ninja` or `make -jN` from build directory
> +- **Test All**: `make check`
> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
> +
> +## Code Style
Ref to docs/devel/style.rst?
> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
> +- **C Comments**: Use `/* ... */` only. No `//` comments.
> +- **Naming**: `snake_case` for variables and functions; `CamelCase` for types and enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl`. On top, `make clippy` and `make rustfmt` for Rust.
> +
> +# Documentation pointers
> +
> +Developer docs live in `docs/devel`. A `kernel-doc::` directive includes
> +documentation comments from source files when Sphinx builds the documentation.
> +These comments be consulted just as easily in the source tree without going
> +through e.g. `make html`.
> +
> +Here are some useful pointers.
> +
> +## Core abstractions
> +
> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
> + everything. It includes class and interface hierarchies, properties, and
> + the object composition tree. See `docs/devel/qom.rst`.
> +- **qdev** builds devices on top of QOM, adding for example buses,
GPIOs / IRQs,
> the
> + realize/unrealize lifecycle (including hot-plug/unplug), and reset. See
> + `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
> + guest address-space model: regions, aliases, address spaces, dirty tracking,
> + load/store and map/unmap operations, etc. See `docs/devel/memory.rst`.
> +
> +## Concurrency
> +
> +Getting the threading model wrong is a common source of subtle bugs here.
> +
> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
> + hold it when exiting to emulation. See `include/qemu/main-loop.h`.
> + Memory regions can (carefully) opt out of the BQL.
(I'd move the RCU entry here)
> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
> + outside the BQL. See `docs/devel/multiple-iothreads.rst`.
> +- The **block layer** is coroutine-based. `co_` prefixes and `coroutine_fn`
> + annotations are advisory but relevant for reviewers. Coroutines have their
> + own locking primitives.
> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
> + Because of the BQL, RCU is mostly used with `call_rcu()` rather than
> + `synchronize_rcu()`. See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
(move earlier)
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] agents: Add a skill for finding your way around QEMU
2026-09-04 7:43 [PATCH v2] agents: Add a skill for finding your way around QEMU Paolo Bonzini
2026-09-04 10:29 ` Philippe Mathieu-Daudé
@ 2026-09-04 10:46 ` Daniel P. Berrangé
2026-09-07 21:50 ` Paolo Bonzini
2026-09-08 6:52 ` Alex Bennée
1 sibling, 2 replies; 5+ messages in thread
From: Daniel P. Berrangé @ 2026-09-04 10:46 UTC (permalink / raw)
To: Paolo Bonzini; +Cc: qemu-devel, Alex Bennée
On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
> As a side effect, establish scaffolding for the .agents/.claude/.gemini
> directories, as a base for future patches to build on.
FWIW, While researching the AGENTS.md stuff I came across this
https://arxiv.org/pdf/2602.11988
which suggests that providing code tree overviews may not be as
helpful as people suspect, while causing the agents to consume
more tokens in their work.
It is pretty hard to benchmark / evaluate this, but it does
suggest the "Finding things" / "Core abstractions" sections
might be overkill/counterproductive. Aspects that are less
discoverable or describing QEMU specific policies/practices
ought to remain valuable.
>
> Some parts of this skill are based on
> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>
> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
> v1->v2: add .claude/.gitignore. Suggest using get_maintainer.pl and ./run.
> Fix thinko around build/source directory
>
>
> .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
> .claude/.gitignore | 2 +
> .claude/skills | 1 +
> .gemini/skills | 1 +
> 4 files changed, 104 insertions(+)
> create mode 100644 .agents/skills/qemu-codebase/SKILL.md
> create mode 100644 .claude/.gitignore
> create mode 120000 .claude/skills
> create mode 120000 .gemini/skills
>
> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
> new file mode 100644
> index 00000000000..17fb55b5289
> --- /dev/null
> +++ b/.agents/skills/qemu-codebase/SKILL.md
> @@ -0,0 +1,100 @@
> +---
> +name: qemu-codebase
> +description: Orientation for QEMU — tree structure, build system, documentation pointers
> +---
> +
> +# Useful reminders for working on QEMU
> +
> +## Finding things
> +
> +`MAINTAINERS` is the authoritative list of subsystems. You can
> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
> +
> +```
> +$ scripts/get_maintainer.pl --nogit -f block/
> +```
> +
> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
> +Here are some important ones:
> +
> +- **target/** holds CPU models and the TCG frontends
> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
> + `docs/devel/tcg-ops.rst`.
> +- **hw/** is devices and boards, categorized by type.
> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
> + have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
> + in common with system emulation
> +
> +Other directories include the back-end subsystems, for example **`block/`**
> +for the block layer.
> +
> +The `include/` tree mostly mirrors the top-level tree.
> +
> +## Build layout
> +
> +Build is always out-of-tree; the build directory is created by
> +`configure` and a checkout can have several. Determine it from context
> +(`ls */meson-info`) rather than assuming.
> +
> +The `run` script in the root of the build dir wraps `meson devenv` and
> +should be used to execute commands in the build directory. It activates
> +the build tree's venv `pyvenv/`, adds various Python modules from
> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
> +variable for general use.
> +
> +`make` at the top level forwards to `ninja` in the configured build
> +directory, and any `build.ninja` target can be invoked that way.
> +
> +## Build & Test
> +- **Build**: `ninja` or `make -jN` from build directory
> +- **Test All**: `make check`
> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
> +
> +## Code Style
> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
> +- **C Comments**: Use `/* ... */` only. No `//` comments.
> +- **Naming**: `snake_case` for variables and functions; `CamelCase` for types and enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl`. On top, `make clippy` and `make rustfmt` for Rust.
> +
> +# Documentation pointers
> +
> +Developer docs live in `docs/devel`. A `kernel-doc::` directive includes
> +documentation comments from source files when Sphinx builds the documentation.
> +These comments be consulted just as easily in the source tree without going
> +through e.g. `make html`.
> +
> +Here are some useful pointers.
> +
> +## Core abstractions
> +
> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
> + everything. It includes class and interface hierarchies, properties, and
> + the object composition tree. See `docs/devel/qom.rst`.
> +- **qdev** builds devices on top of QOM, adding for example buses, the
> + realize/unrealize lifecycle (including hot-plug/unplug), and reset. See
> + `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
> + guest address-space model: regions, aliases, address spaces, dirty tracking,
> + load/store and map/unmap operations, etc. See `docs/devel/memory.rst`.
> +
> +## Concurrency
> +
> +Getting the threading model wrong is a common source of subtle bugs here.
> +
> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
> + hold it when exiting to emulation. See `include/qemu/main-loop.h`.
> + Memory regions can (carefully) opt out of the BQL.
> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
> + outside the BQL. See `docs/devel/multiple-iothreads.rst`.
> +- The **block layer** is coroutine-based. `co_` prefixes and `coroutine_fn`
> + annotations are advisory but relevant for reviewers. Coroutines have their
> + own locking primitives.
> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
> + Because of the BQL, RCU is mostly used with `call_rcu()` rather than
> + `synchronize_rcu()`. See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
> diff --git a/.claude/.gitignore b/.claude/.gitignore
> new file mode 100644
> index 00000000000..b0a57a19c01
> --- /dev/null
> +++ b/.claude/.gitignore
> @@ -0,0 +1,2 @@
> +# reserved for the user to add their own per-project rules
> +/CLAUDE.md
> diff --git a/.claude/skills b/.claude/skills
> new file mode 120000
> index 00000000000..a7540c24423
> --- /dev/null
> +++ b/.claude/skills
> @@ -0,0 +1 @@
> +.agents/skills/
> \ No newline at end of file
> diff --git a/.gemini/skills b/.gemini/skills
> new file mode 120000
> index 00000000000..a7540c24423
> --- /dev/null
> +++ b/.gemini/skills
> @@ -0,0 +1 @@
> +.agents/skills/
> \ No newline at end of file
> --
> 2.55.0
>
With regards,
Daniel
--
|: https://berrange.com ~~ https://hachyderm.io/@berrange :|
|: https://libvirt.org ~~ https://entangle-photo.org :|
|: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] agents: Add a skill for finding your way around QEMU
2026-09-04 10:46 ` Daniel P. Berrangé
@ 2026-09-07 21:50 ` Paolo Bonzini
2026-09-08 6:52 ` Alex Bennée
1 sibling, 0 replies; 5+ messages in thread
From: Paolo Bonzini @ 2026-09-07 21:50 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: qemu-devel, Alex Bennée
On 9/4/26 12:46, Daniel P. Berrangé wrote:
> On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
>> As a side effect, establish scaffolding for the .agents/.claude/.gemini
>> directories, as a base for future patches to build on.
>
> FWIW, While researching the AGENTS.md stuff I came across this
>
> https://arxiv.org/pdf/2602.11988
>
> which suggests that providing code tree overviews may not be as
> helpful as people suspect, while causing the agents to consume
> more tokens in their work.
I found the... skill creator skill, which suggests: "assume the agent
can navigate code, keep discovery cheap, and load documentation only
when it changes a decision." It does seem like it should be possible to
shorten this.
Thanks!
Paolo
> It is pretty hard to benchmark / evaluate this, but it does
> suggest the "Finding things" / "Core abstractions" sections
> might be overkill/counterproductive. Aspects that are less
> discoverable or describing QEMU specific policies/practices
> ought to remain valuable.
>
>>
>> Some parts of this skill are based on
>> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>>
>> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
>> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
>> ---
>> v1->v2: add .claude/.gitignore. Suggest using get_maintainer.pl and ./run.
>> Fix thinko around build/source directory
>>
>>
>> .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>> .claude/.gitignore | 2 +
>> .claude/skills | 1 +
>> .gemini/skills | 1 +
>> 4 files changed, 104 insertions(+)
>> create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>> create mode 100644 .claude/.gitignore
>> create mode 120000 .claude/skills
>> create mode 120000 .gemini/skills
>>
>> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
>> new file mode 100644
>> index 00000000000..17fb55b5289
>> --- /dev/null
>> +++ b/.agents/skills/qemu-codebase/SKILL.md
>> @@ -0,0 +1,100 @@
>> +---
>> +name: qemu-codebase
>> +description: Orientation for QEMU — tree structure, build system, documentation pointers
>> +---
>> +
>> +# Useful reminders for working on QEMU
>> +
>> +## Finding things
>> +
>> +`MAINTAINERS` is the authoritative list of subsystems. You can
>> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
>> +
>> +```
>> +$ scripts/get_maintainer.pl --nogit -f block/
>> +```
>> +
>> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
>> +Here are some important ones:
>> +
>> +- **target/** holds CPU models and the TCG frontends
>> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
>> + `docs/devel/tcg-ops.rst`.
>> +- **hw/** is devices and boards, categorized by type.
>> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
>> + have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
>> + in common with system emulation
>> +
>> +Other directories include the back-end subsystems, for example **`block/`**
>> +for the block layer.
>> +
>> +The `include/` tree mostly mirrors the top-level tree.
>> +
>> +## Build layout
>> +
>> +Build is always out-of-tree; the build directory is created by
>> +`configure` and a checkout can have several. Determine it from context
>> +(`ls */meson-info`) rather than assuming.
>> +
>> +The `run` script in the root of the build dir wraps `meson devenv` and
>> +should be used to execute commands in the build directory. It activates
>> +the build tree's venv `pyvenv/`, adds various Python modules from
>> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
>> +variable for general use.
>> +
>> +`make` at the top level forwards to `ninja` in the configured build
>> +directory, and any `build.ninja` target can be invoked that way.
>> +
>> +## Build & Test
>> +- **Build**: `ninja` or `make -jN` from build directory
>> +- **Test All**: `make check`
>> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
>> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
>> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
>> +
>> +## Code Style
>> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
>> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
>> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
>> +- **C Comments**: Use `/* ... */` only. No `//` comments.
>> +- **Naming**: `snake_case` for variables and functions; `CamelCase` for types and enums.
>> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
>> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
>> +- **Lints**: Run `./scripts/checkpatch.pl`. On top, `make clippy` and `make rustfmt` for Rust.
>> +
>> +# Documentation pointers
>> +
>> +Developer docs live in `docs/devel`. A `kernel-doc::` directive includes
>> +documentation comments from source files when Sphinx builds the documentation.
>> +These comments be consulted just as easily in the source tree without going
>> +through e.g. `make html`.
>> +
>> +Here are some useful pointers.
>> +
>> +## Core abstractions
>> +
>> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
>> + everything. It includes class and interface hierarchies, properties, and
>> + the object composition tree. See `docs/devel/qom.rst`.
>> +- **qdev** builds devices on top of QOM, adding for example buses, the
>> + realize/unrealize lifecycle (including hot-plug/unplug), and reset. See
>> + `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
>> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
>> + guest address-space model: regions, aliases, address spaces, dirty tracking,
>> + load/store and map/unmap operations, etc. See `docs/devel/memory.rst`.
>> +
>> +## Concurrency
>> +
>> +Getting the threading model wrong is a common source of subtle bugs here.
>> +
>> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
>> + hold it when exiting to emulation. See `include/qemu/main-loop.h`.
>> + Memory regions can (carefully) opt out of the BQL.
>> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
>> + outside the BQL. See `docs/devel/multiple-iothreads.rst`.
>> +- The **block layer** is coroutine-based. `co_` prefixes and `coroutine_fn`
>> + annotations are advisory but relevant for reviewers. Coroutines have their
>> + own locking primitives.
>> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
>> + Because of the BQL, RCU is mostly used with `call_rcu()` rather than
>> + `synchronize_rcu()`. See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
>> diff --git a/.claude/.gitignore b/.claude/.gitignore
>> new file mode 100644
>> index 00000000000..b0a57a19c01
>> --- /dev/null
>> +++ b/.claude/.gitignore
>> @@ -0,0 +1,2 @@
>> +# reserved for the user to add their own per-project rules
>> +/CLAUDE.md
>> diff --git a/.claude/skills b/.claude/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.claude/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> diff --git a/.gemini/skills b/.gemini/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.gemini/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> --
>> 2.55.0
>>
>
> With regards,
> Daniel
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] agents: Add a skill for finding your way around QEMU
2026-09-04 10:46 ` Daniel P. Berrangé
2026-09-07 21:50 ` Paolo Bonzini
@ 2026-09-08 6:52 ` Alex Bennée
1 sibling, 0 replies; 5+ messages in thread
From: Alex Bennée @ 2026-09-08 6:52 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: Paolo Bonzini, qemu-devel
Daniel P. Berrangé <berrange@redhat.com> writes:
> On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
>> As a side effect, establish scaffolding for the .agents/.claude/.gemini
>> directories, as a base for future patches to build on.
>
> FWIW, While researching the AGENTS.md stuff I came across this
>
> https://arxiv.org/pdf/2602.11988
>
> which suggests that providing code tree overviews may not be as
> helpful as people suspect, while causing the agents to consume
> more tokens in their work.
>
> It is pretty hard to benchmark / evaluate this, but it does
> suggest the "Finding things" / "Core abstractions" sections
> might be overkill/counterproductive.
I've been using local rules to try and force using semcode which allows
for a more tied together browsing of the code as well as interrogating
lore instead of lots of shell grepping. But yes it seems the tree
overview doesn't help as much as it could. We could just point to
docs/devel/codebase.rst and let the agent read that if it needs to.
> Aspects that are less
> discoverable or describing QEMU specific policies/practices
> ought to remain valuable.
>
>>
>> Some parts of this skill are based on
>> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>>
>> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
>> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
>> ---
>> v1->v2: add .claude/.gitignore. Suggest using get_maintainer.pl and ./run.
>> Fix thinko around build/source directory
>>
>>
>> .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>> .claude/.gitignore | 2 +
>> .claude/skills | 1 +
>> .gemini/skills | 1 +
>> 4 files changed, 104 insertions(+)
>> create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>> create mode 100644 .claude/.gitignore
>> create mode 120000 .claude/skills
>> create mode 120000 .gemini/skills
>>
>> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
>> new file mode 100644
>> index 00000000000..17fb55b5289
>> --- /dev/null
>> +++ b/.agents/skills/qemu-codebase/SKILL.md
>> @@ -0,0 +1,100 @@
>> +---
>> +name: qemu-codebase
>> +description: Orientation for QEMU — tree structure, build system, documentation pointers
>> +---
>> +
>> +# Useful reminders for working on QEMU
>> +
>> +## Finding things
>> +
>> +`MAINTAINERS` is the authoritative list of subsystems. You can
>> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
>> +
>> +```
>> +$ scripts/get_maintainer.pl --nogit -f block/
>> +```
>> +
>> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
>> +Here are some important ones:
>> +
>> +- **target/** holds CPU models and the TCG frontends
>> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
>> + `docs/devel/tcg-ops.rst`.
>> +- **hw/** is devices and boards, categorized by type.
>> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
>> + have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
>> + in common with system emulation
>> +
>> +Other directories include the back-end subsystems, for example **`block/`**
>> +for the block layer.
>> +
>> +The `include/` tree mostly mirrors the top-level tree.
>> +
>> +## Build layout
>> +
>> +Build is always out-of-tree; the build directory is created by
>> +`configure` and a checkout can have several. Determine it from context
>> +(`ls */meson-info`) rather than assuming.
>> +
>> +The `run` script in the root of the build dir wraps `meson devenv` and
>> +should be used to execute commands in the build directory. It activates
>> +the build tree's venv `pyvenv/`, adds various Python modules from
>> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
>> +variable for general use.
>> +
>> +`make` at the top level forwards to `ninja` in the configured build
>> +directory, and any `build.ninja` target can be invoked that way.
>> +
>> +## Build & Test
>> +- **Build**: `ninja` or `make -jN` from build directory
>> +- **Test All**: `make check`
>> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
>> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
>> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
>> +
>> +## Code Style
>> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
>> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
>> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
>> +- **C Comments**: Use `/* ... */` only. No `//` comments.
>> +- **Naming**: `snake_case` for variables and functions; `CamelCase` for types and enums.
>> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
>> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
>> +- **Lints**: Run `./scripts/checkpatch.pl`. On top, `make clippy` and `make rustfmt` for Rust.
>> +
>> +# Documentation pointers
>> +
>> +Developer docs live in `docs/devel`. A `kernel-doc::` directive includes
>> +documentation comments from source files when Sphinx builds the documentation.
>> +These comments be consulted just as easily in the source tree without going
>> +through e.g. `make html`.
>> +
>> +Here are some useful pointers.
>> +
>> +## Core abstractions
>> +
>> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
>> + everything. It includes class and interface hierarchies, properties, and
>> + the object composition tree. See `docs/devel/qom.rst`.
>> +- **qdev** builds devices on top of QOM, adding for example buses, the
>> + realize/unrealize lifecycle (including hot-plug/unplug), and reset. See
>> + `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
>> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
>> + guest address-space model: regions, aliases, address spaces, dirty tracking,
>> + load/store and map/unmap operations, etc. See `docs/devel/memory.rst`.
>> +
>> +## Concurrency
>> +
>> +Getting the threading model wrong is a common source of subtle bugs here.
>> +
>> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
>> + hold it when exiting to emulation. See `include/qemu/main-loop.h`.
>> + Memory regions can (carefully) opt out of the BQL.
>> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
>> + outside the BQL. See `docs/devel/multiple-iothreads.rst`.
>> +- The **block layer** is coroutine-based. `co_` prefixes and `coroutine_fn`
>> + annotations are advisory but relevant for reviewers. Coroutines have their
>> + own locking primitives.
>> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
>> + Because of the BQL, RCU is mostly used with `call_rcu()` rather than
>> + `synchronize_rcu()`. See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
>> diff --git a/.claude/.gitignore b/.claude/.gitignore
>> new file mode 100644
>> index 00000000000..b0a57a19c01
>> --- /dev/null
>> +++ b/.claude/.gitignore
>> @@ -0,0 +1,2 @@
>> +# reserved for the user to add their own per-project rules
>> +/CLAUDE.md
>> diff --git a/.claude/skills b/.claude/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.claude/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> diff --git a/.gemini/skills b/.gemini/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.gemini/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> --
>> 2.55.0
>>
>
> With regards,
> Daniel
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-09-08 6:53 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-09-04 7:43 [PATCH v2] agents: Add a skill for finding your way around QEMU Paolo Bonzini
2026-09-04 10:29 ` Philippe Mathieu-Daudé
2026-09-04 10:46 ` Daniel P. Berrangé
2026-09-07 21:50 ` Paolo Bonzini
2026-09-08 6:52 ` Alex Bennée
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.