This provides a skill detailing how to deal with some of QEMU's more idiosyncratic coding conventions. Originally I had given instructions on using tags and git grep but once I'd installed the semcode MCP (https://github.com/facebookexperimental/semcode) it was able to handle most code navigation pretty efficiently. So now this skill just focuses on the things that are tricky for indexers to handle, namely generated code and fancy macros.
Signed-off-by: Alex Bennée <[email protected]> --- caveman - caveman reduction v3 - rewrote with a focus on generated code and macros for when code search MCPs run into trouble. 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 | 84 +++++++++++++++++++ .../qemu-code-explorer/evals/evals.json | 26 ++++++ AGENTS.md | 1 + 3 files changed, 111 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..fa8df2b0f94 --- /dev/null +++ b/.agents/skills/qemu-code-explorer/SKILL.md @@ -0,0 +1,84 @@ +--- +name: qemu-code-explorer +description: Advanced QEMU code search (generated code, complex macros, QOM) when standard search fails. Fallback for build artifacts and hidden symbols. +license: GPL-2.0-or-later +--- + +# QEMU Advanced Code Explorer + +If standard search fails, symbol is likely generated at build time or hidden by macros. Use these strategies. + +## 1. Search Generated Code +Generated files exist in build dir, not source tree. + +### QAPI (QEMU Interface) +- **Source**: `qapi/*.json` +- **Generated**: `build/qapi/` (headers, C files) +- **Patterns**: + - `qmp_marshal_...`: Command marshallers. + - `qapi_free_...`: Type cleanup functions. + - `visit_type_...`: Visitor functions. +- **Action**: Search `build/` text. + +### Tracing +- **Source**: `trace-events` files. +- **Generated**: `build/trace/` (e.g., `trace/trace-hw_block.h`) +- **Patterns**: `trace_...` functions. +- **Action**: Search build dir/generated headers. + +### Decodetree (Instruction Decoding) +- **Source**: `target/.../*.decode` +- **Generated**: Included as `.c.inc` in build tree. +- **Patterns**: `trans_...` handwritten, decoder calling them generated. + +### Configuration +- `build/config-host.h`: Global host config. +- `build/config-target.h`: Target-specific config (e.g., `TARGET_X86_64`). + +## 2. Expand Complex Macros +QEMU uses deep macro nesting (TCG, softfloat). + +### `scripts/expand-macro.py` +Get C code after preprocessing for specific line range. + +- **Usage**: + ```bash + python3 ./scripts/expand-macro.py FILE --context CONTEXT_FILE --range START_LINE-END_LINE + ``` +- **Example** (TCG helpers, softfloat): + ```bash + python3 ./scripts/expand-macro.py fpu/softfloat-parts.c.inc --context fpu/softfloat.c --range 191-264 + ``` + +## 3. QEMU Symbol Patterns +Hidden by boilerplate-reducing macros. + +### QOM (QEMU Object Model) +`OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to multiple functions/casts. +- `MY_DEVICE(obj)` likely defined via `OBJECT_DECLARE_TYPE(...)`. +- Search type name string (e.g., `"my-device"`) to find `TypeInfo` structure. + +### TCG Helpers +- **Pattern**: `HELPER(foo)` +- Defined in `helper.h`, implemented as `helper_foo`. +- Search `HELPER(foo)` pattern if `helper_foo` not found. + +### Error Handling +- `ERRP_GUARD()`: Starts functions for `error_propagate`. +- `error_setg(errp, ...)`: Reports errors. + +## Decision Matrix + +| Scenario | Strategy | +|------|--------| +| Standard function/struct | Use standard search tools. | +| Symbol not found in source | Search `build/` for generated code. | +| Macro expansion opaque | Use `scripts/expand-macro.py`. | +| QOM cast macro (`TYPE_...`) | Search `TypeInfo` or `OBJECT_DECLARE_...` usage. | +| TCG helper missing | Search `HELPER(name)`. | +| Instruction decoding | Search `.decode` and `trans_...` functions. | + +## Workflow Tips +1. **Find Build Dir**: Check `build/` or other build subdirs. +2. **Combine Tools**: Try standard search first, then search build dir. +3. **Check Context**: For `.c.inc` files, find the parent `.c` file that includes it. 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 8ceffde4ebb..c751652babf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,7 @@ If unsure read the linked `security.rst` document for further guidance. ## 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
