Document QEMU tracing profiler workflow

Document how to build and run the QEMU tracing profiler introduced for
the scheduler tracing work.

The guide explains the required environment variables, plugin build
steps, symbol lookup for debug_trace_event(), and the QEMU command line
used to reproduce profiling runs. It also describes how to combine the
plugin output with trace_sched diagnostics to derive normalized
per-event metrics.

Author: Synte-Peng

tools/qemu/README.md

@@ -0,0 +1,133 @@
+# QEMU Trace Profiling
+
+This directory contains a QEMU TCG plugin used to profile the Linmo tracing hot path without modifying kernel behavior.
+
+## Scope
+
+The current plugin targets `debug_trace_event()` and reports:
+
+- `insn_count`
+- `store_count`
+
+These numbers are intended for QEMU-based relative analysis only. They are not hardware-cycle measurements.
+
+## Files
+
+- `debug_trace_profiler.c`
+  - QEMU TCG plugin that counts guest instructions and stores within a target PC range
+- `Makefile`
+  - builds `debug_trace_profiler.so`
+
+## Prerequisites
+
+- QEMU system emulator with plugin support
+- `qemu-plugin.h`
+- `cc`
+- `pkg-config`
+- `glib-2.0` development headers visible to `pkg-config`
+
+In the current environment, the plugin header is provided through:
+
+```bash
+QEMU_PLUGIN_INC=/path/to/qemu/include
+```
+
+## Build
+
+From the Linmo repo root, export the environment first:
+
+```bash
+export CROSS_COMPILE=<your-riscv-tool-prefix>
+export QEMU_PLUGIN_INC=/path/to/qemu/include
+export QEMU_BIN=$(command -v qemu-system-riscv32)
+export TRACE_PLUGIN_SO="$(pwd)/tools/qemu/debug_trace_profiler.so"
+```
+
+Then build the plugin:
+
+```bash
+make -C tools/qemu clean
+make -C tools/qemu QEMU_PLUGIN_INC="$QEMU_PLUGIN_INC"
+```
+
+This produces:
+
+```text
+tools/qemu/debug_trace_profiler.so
+```
+
+## Reproduction
+
+### 1. Build the target workload
+
+For the bounded scheduler-tracing workload:
+
+```bash
+make trace_sched CROSS_COMPILE="$CROSS_COMPILE"
+```
+
+If your toolchain binaries are not already on `PATH`, export that before running the commands above.
+
+### 2. Resolve the `debug_trace_event()` address range
+
+```bash
+"${CROSS_COMPILE}nm" -S --defined-only build/image.elf | \
+    rg ' debug_trace_event$'
+```
+
+Example output:
+
+```text
+80004a54 000000f0 T debug_trace_event
+```
+
+Interpret that as:
+
+- `start = 0x80004a54`
+- `size = 0x000000f0`
+- `end = 0x80004b44`
+
+### 3. Run QEMU with `icount` and the plugin
+
+```bash
+"$QEMU_BIN" \
+    -machine virt -nographic -bios none \
+    -kernel build/image.elf \
+    -icount shift=0,align=off,sleep=off \
+    -plugin "$TRACE_PLUGIN_SO",start=0x80004a54,end=0x80004b44
+```
+
+Expected bounded workload output includes:
+
+```text
+Overall: PASS
+Trace totals: count=256 overwrites=1090 total_events=1346
+debug_trace_profiler: start=0x80004a54 end=0x80004b44 insn_count=62795 store_count=17511
+```
+
+## Interpreting the result
+
+The plugin itself reports only:
+
+- PC range
+- total instruction count within that range
+- total store count within that range
+
+To compute per-event values, use the workload diagnostics:
+
+```text
+total_events = debug_trace_count() + debug_trace_overwrites()
+```
+
+With the example above:
+
+- `total_events = 1346`
+- `instructions/event = 62795 / 1346 = 46.653`
+- `stores/event = 17511 / 1346 = 13.010`
+
+## Notes
+
+- `QEMU_BIN` should resolve to a QEMU binary with plugin support.
+- `TRACE_PLUGIN_SO` should remain an absolute path.
+- The plugin is intended for deterministic QEMU-based profiling with `-icount`.
+- This tooling characterizes the tracing hot path; it should not be used as proof of hardware-cycle timing.