refactorone

README.md

@@ -145,6 +145,46 @@ validate.py \
     --crossbar-size 2048 --crossbar-count 256 --core-count 1000
 ```
 
+Each validation run writes debugging artifacts into the benchmark's workspace
+directory (for example `validation/operations/gemm/small/`):
+- `inputs/` — generated input CSVs used for the run.
+- `outputs/` — reference outputs dumped by the native ONNX runner.
+- `raptor/` — compiler artifacts:
+  `*.onnx.mlir`, `dialects/spatial0.mlir`, `dialects/spatial1_dcp_merged.mlir`,
+  `dialects/pim0.mlir`, `dialects/pim1_buff.mlir`, `dialects/pim2_coalesced.mlir`,
+  `dialects/pim3_folded.mlir`, `dialects/pim4_materialized.mlir`,
+  `pim/config.json`, `pim/core_*.pim`, `pim/memory.bin`, and reports under
+  `raptor/reports/` such as `dcp_merge_report.txt`,
+  `memory_report.txt`, and `static_memory_coalescing_report.txt`.
+- `runner/` — generated reference runner source, build tree, and shared library.
+- `simulation/out.bin` — raw simulator output dump used for output comparison.
+
+That means you usually do not need to rerun standalone `--EmitSpatial` or
+`--EmitPim` commands while debugging validation failures: the per-pass dialect
+dumps are already available under `raptor/dialects/`.
+
+The validator does not currently expose a simulator tracing flag, but once a
+validation has produced `raptor/pim/` you can rerun the simulator manually with
+tracing enabled:
+
+```bash
+cd backend-simulators/pim/pim-simulator
+cargo run --no-default-features --features tracing --release \
+  --package pim-simulator --bin pim-simulator -- \
+  -f /path/to/workspace/raptor/pim \
+  -o /path/to/workspace/simulation/out.bin \
+  -d <addr0>,<size0>,<addr1>,<size1>,...
+```
+
+With `--features tracing`, the simulator writes per-core traces as
+`simulation/TraceCore0`, `simulation/TraceCore1`, ... next to `simulation/out.bin`.
+The validator normally computes the `-d` dump ranges from `raptor/pim/config.json`
+and the model output shapes. If you need a clean slate before rerunning, use:
+
+```bash
+validate.py --clean
+```
+
 Available networks under `validation/networks/`: `vgg16`, `yolo11n`.
 Available operations under `validation/operations/`: `add`, `conv`, `div`,
 `gather`, `gemm`, `gemv`, `mul`, `pool`, `reduce_mean`, `relu`, `resize`,