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]> --- 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 | 88 +++++++++++++++++++ .../qemu-code-explorer/evals/evals.json | 26 ++++++ AGENTS.md | 1 + 3 files changed, 115 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..7bca389b37d --- /dev/null +++ b/.agents/skills/qemu-code-explorer/SKILL.md @@ -0,0 +1,88 @@ +--- +name: qemu-code-explorer +description: Advanced QEMU code exploration for special cases (generated code, complex macros, QOM) that are not easily handled by standard code exploration tools. Use this as a fallback strategy for build-time artifacts or hidden symbols. +license: GPL-2.0-or-later +--- + +# QEMU Advanced Code Explorer + +When standard code navigation tools fail to find a symbol, it is often because the code is generated at build time or hidden behind complex macros. This skill covers how to find and understand those special cases. + +## 1. Searching Generated Code + +Generated source files do not reside in the source tree but in the build directory. If a primary symbol search fails, the symbol is likely generated. + +### QAPI (QEMU Interface) +- **Source**: `qapi/*.json` +- **Generated**: `build/qapi/` (headers and C files) +- **Patterns**: + - `qmp_marshal_...`: Command marshallers. + - `qapi_free_...`: Type cleanup functions. + - `visit_type_...`: Visitor functions. +- **Search**: Search the `build/` directory using standard text search tools. + +### Tracing +- **Source**: `trace-events` files throughout the tree. +- **Generated**: `build/trace/` (e.g., `trace/trace-hw_block.h`) +- **Patterns**: `trace_...` functions. +- **Search**: Check the build directory or the generated headers. + +### Decodetree (Instruction Decoding) +- **Source**: `target/.../*.decode` files. +- **Generated**: Usually included into source files as `.c.inc` artifacts in the build tree. +- **Patterns**: `trans_...` functions are handwritten, but the decoder that calls them is generated. + +### Configuration +- `build/config-host.h`: Global host configuration. +- `build/config-target.h`: Target-specific configuration (e.g., `TARGET_X86_64`). + +## 2. Expanding Complex Macros + +QEMU uses deep macro nesting (especially in TCG and softfloat) which can be opaque to static analysis. + +### `scripts/expand-macro.py` +Use this tool to see the exact C code after preprocessing for a specific range in a file. + +- **Usage**: + ```bash + python3 ./scripts/expand-macro.py FILE --context CONTEXT_FILE --range START_LINE-END_LINE + ``` +- **Example**: + To see how TCG helpers or softfloat parts expand: + ```bash + python3 ./scripts/expand-macro.py fpu/softfloat-parts.c.inc --context fpu/softfloat.c --range 191-264 + ``` + +## 3. QEMU-Specific Symbol Patterns + +Some symbols are "hidden" from simple search tools because of boilerplate-reducing macros. + +### QOM (QEMU Object Model) +Macros like `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to multiple function declarations and casting macros. +- If you see `MY_DEVICE(obj)`, it is likely defined via `OBJECT_DECLARE_TYPE(...)`. +- Search for the type name string (e.g., `"my-device"`) to find the `TypeInfo` structure, which links everything together. + +### TCG Helpers +- **Pattern**: `HELPER(foo)` +- Defined in `helper.h` or similar, implemented as `helper_foo`. +- If searching for `helper_foo` fails, search for the `HELPER(foo)` pattern in the source. + +### Error Handling +- `ERRP_GUARD()`: Used at the start of functions to handle `error_propagate`. +- `error_setg(errp, ...)`: Common pattern for reporting errors. + +## Decision Matrix + +| Scenario | Strategy | +|------|--------| +| Standard function/struct | Use primary code navigation tools. | +| Symbol not found in source | Search `build/` directory for generated code. | +| Macro expansion looks wrong | Use `scripts/expand-macro.py`. | +| QOM casting macro (`TYPE_...`) | Search for the `TypeInfo` or `OBJECT_DECLARE_...` usage. | +| TCG helper missing | Search for `HELPER(name)` pattern. | +| Instruction decoding | Check `.decode` files and corresponding `trans_...` functions. | + +## Workflow Tips +1. **Locate the Build Directory**: QEMU developers often use `build/` but it could be named differently. Always check. +2. **Combine Tools**: Use primary tools first. If they fail, search the `build/` directory. +3. **Check the Context**: If a `.c.inc` file is confusing, find the `.c` file that includes it to understand the macro context. 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 3fd56fe3309..a34a92244e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ If unsure read the linked document for 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
