86 lines
4.6 KiB
Markdown
86 lines
4.6 KiB
Markdown
|
# Phase 21.8 — Numeric Core Integration & Builder Support
|
|||
|
|
|
|||
|
|
Status: proposal (to hand off to Claude Code)
|
|||
|
|
|
|||
|
|
## Goal
|
|||
|
|
|
|||
|
|
Integrate the new numeric core boxes (IntArrayCore + MatI64) into the Hakorune selfhost chain so that:
|
|||
|
|
|
|||
|
|
- Stage‑B → MirBuilder → ny‑llvmc(crate) can emit MIR(JSON) and EXE for code that uses:
|
|||
|
|
- `using nyash.core.numeric.intarray as IntArrayCore`
|
|||
|
|
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
|||
|
|
- The `matmul_core` microbench (MatI64 + IntArrayCore) runs end‑to‑end in EXE mode and can be compared fairly against a matching C implementation.
|
|||
|
|
|
|||
|
|
21.6 provides the core boxes; 21.8 focuses on wiring them into the builder/runtime chain without changing default behaviour for other code.
|
|||
|
|
|
|||
|
|
## Scope (21.8, this host)
|
|||
|
|
|
|||
|
|
- Stage‑B / MirBuilder:
|
|||
|
|
- Ensure `MatI64` and `IntArrayCore` are recognized as valid boxes when referenced via:
|
|||
|
|
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
|||
|
|
- `using nyash.core.numeric.intarray as IntArrayCore`
|
|||
|
|
- Fix the current provider‑emit failure:
|
|||
|
|
- Error today: `[mirbuilder/parse/error] undefined variable: MatI64` during `env.mirbuilder.emit`.
|
|||
|
|
- Diagnose and adjust Stage‑B / MirBuilder so that static box references (`MatI64.new`, `A.mul_naive`) compile in the same way as other boxes.
|
|||
|
|
|
|||
|
|
- AotPrep / emit pipeline:
|
|||
|
|
- Keep AotPrep unchanged for now; the goal is to make `tools/hakorune_emit_mir.sh` succeed on `matmul_core` sources without special‑casing.
|
|||
|
|
- Ensure `tools/hakorune_emit_mir.sh` with:
|
|||
|
|
- `HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1`
|
|||
|
|
- can emit valid MIR(JSON) for MatI64/IntArrayCore code.
|
|||
|
|
|
|||
|
|
- Microbench integration:
|
|||
|
|
- Finish wiring `matmul_core` in `tools/perf/microbench.sh`:
|
|||
|
|
- Hako side: MatI64/IntArrayCore based O(n³) matmul (`MatI64.mul_naive`).
|
|||
|
|
- C side: `MatI64Core { int64_t *ptr; rows; cols; stride; }` with identical algorithm.
|
|||
|
|
- Accept that performance may still be far from the 80% target; 21.8 focuses on **structural integration and parity**, not tuning.
|
|||
|
|
|
|||
|
|
Out of scope:
|
|||
|
|
|
|||
|
|
- New optimizations inside AotPrep / CollectionsHot.
|
|||
|
|
- SIMD/blocked matmul kernels (to be handled in a later optimization phase).
|
|||
|
|
- f64/complex matrix variants.
|
|||
|
|
|
|||
|
|
## Tasks for implementation (Claude Code)
|
|||
|
|
|
|||
|
|
1) **Fix MatI64 visibility in Stage‑B / MirBuilder**
|
|||
|
|
- Reproduce the current failure:
|
|||
|
|
- Use a small `.hako` like:
|
|||
|
|
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
|||
|
|
- `static box Main { method main(args) { local n = 4; local A = MatI64.new(n,n); return A.at(0,0); } }`
|
|||
|
|
- Confirm `env.mirbuilder.emit` reports `undefined variable: MatI64`.
|
|||
|
|
- Investigate how modules from `nyash.toml` (`"nyash.core.numeric.matrix_i64" = "lang/src/runtime/numeric/mat_i64_box.hako"`) are made visible to Stage‑B and MirBuilder.
|
|||
|
|
- Adjust the resolver / module prelude so that `MatI64` (and `IntArrayCore`) are treated like other core boxes:
|
|||
|
|
- Either via explicit prelude inclusion,
|
|||
|
|
- Or via module registry entries consumed by the builder.
|
|||
|
|
|
|||
|
|
2) **Ensure `tools/hakorune_emit_mir.sh` can emit MIR(JSON) for matmul_core**
|
|||
|
|
- Once MatI64 is visible, run:
|
|||
|
|
- `HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1 NYASH_JSON_ONLY=1 tools/hakorune_emit_mir.sh <matmul_core.hako> tmp/matmul_core.json`
|
|||
|
|
- Acceptance:
|
|||
|
|
- No `undefined variable: MatI64` / `IntArrayCore` errors.
|
|||
|
|
- `tmp/matmul_core.json` is valid MIR(JSON) (same schema as existing matmul case).
|
|||
|
|
|
|||
|
|
3) **Finish `matmul_core` microbench**
|
|||
|
|
- Use the existing skeleton in `tools/perf/microbench.sh` (`case matmul_core`):
|
|||
|
|
- Confirm Hako side compiles and runs under `--backend vm`.
|
|||
|
|
- Confirm EXE path works:
|
|||
|
|
- `NYASH_SKIP_TOML_ENV=1 NYASH_LLVM_SKIP_BUILD=1 tools/perf/microbench.sh --case matmul_core --backend llvm --exe --runs 1 --n 64`
|
|||
|
|
- Update `benchmarks/README.md`:
|
|||
|
|
- Add `matmul_core` row with a short description:
|
|||
|
|
- “MatI64/IntArrayCore vs MatI64Core C struct (ptr+rows+cols+stride)”
|
|||
|
|
- Record initial ratios (even if far from 80%).
|
|||
|
|
|
|||
|
|
4) **Keep existing behaviour stable**
|
|||
|
|
- No changes to default user behaviour, env toggles, or existing benches beyond adding `matmul_core`.
|
|||
|
|
- Ensure quick/profile smokes (where applicable) remain green with numeric core present.
|
|||
|
|
|
|||
|
|
## Notes
|
|||
|
|
|
|||
|
|
- 21.6 already introduced:
|
|||
|
|
- NyRT `IntArrayCore` (Vec<i64> + RwLock) and handle‑based externs (`nyash.intarray.*`).
|
|||
|
|
- Hako wrappers `IntArrayCore` and `MatI64` in `lang/src/runtime/numeric/`.
|
|||
|
|
- `nyash.toml` module aliases for `nyash.core.numeric.intarray` and `nyash.core.numeric.matrix_i64`.
|
|||
|
|
- 21.8 is about wiring these into the builder/emit chain so that Hakorune can compile and benchmark numeric core code end‑to‑end.
|
|||
|
|
|