blazingly fasterer

README.md

@@ -67,20 +67,22 @@ ONNX-MLIR -> Spatial -> Pim (tensor) -> Pim (bufferized) -> PIM artifacts
    Converts tensor-semantics PIM IR into memref-semantics PIM IR using MLIR's
    bufferization interfaces.
 
-5. **Static memory coalescing**
-   (`src/PIM/Dialect/Pim/Transforms/StaticMemoryCoalescing`).
-   Reuses compatible local memref allocations inside PIM cores before codegen.
-
-6. **PIM code generation** (`src/PIM/Pass/PimCodegen` and
+5. **Safe IR memory coalescing**
+   (`src/PIM/Dialect/Pim/Transforms/MemoryCoalescing`).
+   Normalizes compatible block-local allocations before final planning.
+6. **PIM local-memory planning**
+   (`src/PIM/Dialect/Pim/Transforms/LocalMemoryPlanning`).
+   Computes whole-core lifetimes, coalesces non-overlapping allocations into
+   physical slots, assigns addresses, and records the explicit plan in PIM IR.
+7. **PIM verification and code generation** (`src/PIM/Pass/PimCodegen` and
    `src/PIM/Compiler`).
-   Folds host constants, materializes remaining host constants, verifies PIM IR,
-   emits `.pim` core files, writes weights, and writes `memory.bin` /
-   `config.json`.
+   Verifies the memory plan and other PIM invariants, then emits `.pim` core
+   files, weights, and `memory.bin` / `config.json` without rerunning liveness.
 
 Supporting pieces:
 - `src/PIM/Common` - shared IR, filesystem, diagnostics, reports, and utility
   helpers.
-- `src/PIM/Compiler` - PIM compiler options, memory/address planning, binary
+- `src/PIM/Compiler` - PIM compiler options, planned-address materialization, binary
   instruction format, artifact writing, weight emission, and codegen entry
   points.
 - `src/PIM/Conversion/SpatialToGraphviz` - optional Spatial graphviz conversion
@@ -97,8 +99,8 @@ Pass these to `onnx-mlir` when compiling for PIM:
   `--EmitPimCodegen` - stop the PIM pipeline at the requested stage. The PIM
   default is `--EmitPimCodegen`.
 - `--core-count=<N>` - required positive core count for PIM compilation.
-- `--crossbar-size=<N>` - crossbar width/height. Default in code is `2`.
-- `--crossbar-count=<N>` - crossbars per core. Default in code is `256`.
+- `--crossbar-size=<N>` - crossbar width/height. Default in code is `128`.
+- `--crossbar-count=<N>` - crossbars per core. Default in code is `64`.
 - `--pim-only-codegen` - assume input is already bufferized PIM IR and only run
   the codegen tail.
 - `--pim-emit-json` - also emit `core_*.json` instruction files alongside
@@ -109,12 +111,28 @@ Pass these to `onnx-mlir` when compiling for PIM:
 - `--use-experimental-conv-impl` - use the alternate convolution lowering.
 - `--ignore-concat-error` - soft-fail a ConcatOp corner case.
 
+## Standard PIM hardware profile
+
+Raptor's standard development and YOLO validation profile is:
+
+| Parameter | Value |
+| --- | ---: |
+| Cores | 144 |
+| Crossbars per core | 64 |
+| Crossbar size | 128 × 128 |
+
+Canonical compiler flags:
+
+`--crossbar-count=64 --crossbar-size=128 --core-count=144`
+
+`--core-count` remains mandatory and must be passed explicitly to the compiler.
+
 Example:
 
 ```bash
 ./build_release/Release/bin/onnx-mlir model.onnx -o /tmp/raptor/model \
   --maccel=PIM --EmitPimCodegen \
-  --crossbar-size=2048 --crossbar-count=256 --core-count=1000
+  --crossbar-count=64 --crossbar-size=128 --core-count=144
 ```
 
 This writes PIM artifacts under `/tmp/raptor/pim/`.
@@ -131,21 +149,33 @@ Python dependencies used by the validation scripts are `numpy`, `onnx`, and
 Per-operation validation from the repository root:
 
 ```bash
-python3 validation/validate.py \
+python validation/validate.py \
   --raptor-path build_release/Release/bin/onnx-mlir \
   --onnx-include-dir onnx-mlir/include \
-  --core-count 1000
+  --operations-dir validation/operations \
+  --crossbar-count 64 \
+  --crossbar-size 128 \
+  --core-count 144 \
+  --verbose \
+  --raptor-extra-arg=--pim-detect-communication-deadlock \
+  --raptor-extra-arg=--pim-export-spatial-dataflow=none
 ```
 
 Validate one network or a subset by pointing `--operations-dir` at any directory
 containing `.onnx` files:
 
 ```bash
-python3 validation/validate.py \
+python validation/validate.py \
   --raptor-path build_release/Release/bin/onnx-mlir \
   --onnx-include-dir onnx-mlir/include \
   --operations-dir validation/networks/yolo11n/depth_04 \
-  --crossbar-size 2048 --crossbar-count 256 --core-count 1000
+  --crossbar-count 64 \
+  --crossbar-size 128 \
+  --core-count 144 \
+  --verbose \
+  --raptor-extra-arg=--pim-memory-report=summary \
+  --raptor-extra-arg=--pim-detect-communication-deadlock \
+  --raptor-extra-arg=--pim-export-spatial-dataflow=none
 ```
 
 Useful validation options:
@@ -170,7 +200,7 @@ Each validation run writes artifacts in the model workspace, for example under
 The compiler currently dumps dialect snapshots such as `spatial0.mlir`,
 `spatial1_graph.mlir`, `spatial2_trivial_merged.mlir`,
 `spatial3_scheduled_no_comm.mlir`, `spatial4_scheduled.mlir`, `pim0.mlir`, `pim1_buff.mlir`,
-`pim2_folded.mlir`, and `pim3_coalesced.mlir` when an output directory is
+`pim2_folded.mlir`, `pim3_coalesced.mlir`, and `pim4_memory_planned.mlir` when an output directory is
 available.
 
 To rerun the simulator manually with tracing after validation has produced a