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]> --- .agents/skills/qemu-code-explorer/SKILL.md | 66 +++++++++++++++++++ .../qemu-code-explorer/evals/evals.json | 25 +++++++ AGENTS.md | 1 + 3 files changed, 92 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..d41b21179c1 --- /dev/null +++ b/.agents/skills/qemu-code-explorer/SKILL.md @@ -0,0 +1,66 @@ +--- +name: qemu-code-explorer +description: Comprehensive guide for exploring the QEMU codebase using tagging systems (gtags, ctags, cscope), git grep, and build-directory grep for generated files. Use this skill when the user asks to find where something is defined, how it's used, or wants to understand a specific subsystem. +--- + +# 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. +- **Tools**: Use `gtag_find_symbol_definition` and `gtag_find_symbol_references`. +- **Note**: This is significantly faster and more accurate than `grep` for symbols. It handles static variables and functions correctly. + +### 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 or trace-events) 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/trace/`: Generated trace points. + - `build/config-host.h`: Host-specific configuration. + +## 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. | + +## 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..dff7afa52fa --- /dev/null +++ b/.agents/skills/qemu-code-explorer/evals/evals.json @@ -0,0 +1,25 @@ +{ + "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 or eca__grep scoped to hw/ to find the string literals." + } + ] +} diff --git a/AGENTS.md b/AGENTS.md index 401c48da810..e4b65b06067 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ of AI-generated content. - **Multiple Builds**: Developers might create a `builds` directory with different 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 included in commits. Use them to track complex multi-step tasks. +- **Agent Skills**: These can be found in `.agents/skills` ## Agent Skills (see `.agents/skills`) You should use the following specialized skills for common tasks: -- 2.47.3
