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ée <[email protected]> --- 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/qemu-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 search generated code in build directories. You MUST use this skill when exploring 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 symbol 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 defined or used. +- **Commands**: + - 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 content, 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 source 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., `optarg`). + - 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_..._header`). + - Checking configuration fragments (`config-*.h`). +- **Tools**: Use a normal `grep` (or similar search tool) limited to the build directory. +- **Crucial Note**: QEMU developers often have multiple build directories (e.g., `build/`, `builds/debug/`, `builds/asan/`). Always verify which build 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/object.h`) +- Most devices are QOM objects. +- Key concepts: `TypeInfo`, `ClassInit`, `InstanceInit`, `InstanceFinalize`. +- `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to boilerplate. +- 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` files. + - `build/trace/`: Generated trace points. + - `trace_my_event_name(arg1, arg2);` calls the `my_event_name` trace point. + +### 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 propagation. +- **Bitwise**: `BIT(n)`, `MAKE_64BIT_MASK(shift, len)` for clear bit manipulation. +- **Structs**: `container_of(ptr, type, member)` to get parent struct pointer. +- **Memory**: `g_autofree` and `g_autoptr(Type)` for automatic cleanup (GLib). +- **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 context, 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 START_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 fpu/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 literals. | +| Find QAPI-generated code | `grep` in `build/` | Not in source tree. | +| Search in a specific subsystem | `git grep <path>` | Efficiently scoped. | +| Understand complex macro expansion | `scripts/expand-macro.py` | Shows exact generated C code. | + +## Workflow Tips +1. **Scope your search**: If you know you are looking for a networking issue, search `hw/net/` or `net/` first. +2. **Beware of Macros**: QEMU uses many macros (especially in QOM). If `gtags` fails, `git grep` might find where the macro is used to define the symbol. +3. **Verify the Build**: Before searching generated code, ensure a build has been performed in the target directory. diff --git a/.agents/skills/qemu-code-explorer/evals/evals.json b/.agents/skills/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/qemu-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 some docs but I can't find it in the source tree. Can you find where it is defined?", + "expected_output": "The agent should identify this as QAPI generated code and look in the build directory (e.g., build/qapi/qapi-commands-control.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 the 'hw/' directory.", + "expected_output": "The agent should use git grep scoped to hw/ to find 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: ## 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. ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code. -- 2.47.3
