tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
c04b0c059d22dc518afe82b0d1c31f1a99dc0544
hakorune/docs/LLVM_LAYER_OVERVIEW.md
Selfhosting Dev c04b0c059d feat(llvm): Major refactor - BuilderCursor全域化 & Resolver API導入 
Added:
- Resolver API (resolve_i64) for unified value resolution with per-block cache
- llvmlite harness (Python) for rapid PHI/SSA verification
- Comprehensive LLVM documentation suite:
  - LLVM_LAYER_OVERVIEW.md: Overall architecture and invariants
  - RESOLVER_API.md: Value resolution strategy
  - LLVM_HARNESS.md: Python verification harness

Updated:
- BuilderCursor applied to ALL lowering paths (externcall/newbox/arrays/maps/call)
- localize_to_i64 for dominance safety in strings/compare/flow
- NYASH_LLVM_DUMP_ON_FAIL=1 for debug IR output

Key insight: LoopForm didn't cause problems, it just exposed existing design flaws:
- Scattered value resolution (now unified via Resolver)
- Inconsistent type conversion placement
- Ambiguous PHI wiring responsibilities

Next: Wire Resolver throughout, achieve sealed=ON green for dep_tree_min_string
2025-09-12 20:06:48 +09:00

2.0 KiB
Raw Blame History

LLVM Layer Overview (Phase 15)

Scope

  • Practical guide to LLVM lowering architecture and invariants used in Phase 15.
  • Complements LOWERING_LLVM.md (rules), RESOLVER_API.md (value resolution), and LLVM_HARNESS.md (harness).

Module Layout

  • src/backend/llvm/compiler/codegen/
    • instructions/ split by concern: flow.rs, blocks.rs, arith.rs, arith_ops.rs, mem.rs, strings.rs, arrays.rs, maps.rs, boxcall/, externcall/, call.rs, loopform.rs, resolver.rs.
    • builder_cursor.rs: central insertion/terminator guard.

Core Invariants

  • Resolver-only reads: lowerers fetch MIR values through Resolver (no direct vmap access for cross-BB values).
  • Localize at block start: PHIs created at the beginning of the current BB (before non-PHI) to guarantee dominance.
  • Cast placement: perform ptr↔int and width casts outside PHIs, at BB start or just-before-pred-terminator via with_block.
  • Sealed SSA: successor PHIs wired by predecessor snapshots and seal_block; branch/jump do not push incoming directly.
  • Cursor discipline: only insert via BuilderCursor; post-terminator insertions are forbidden.

LoopForm (gated)

  • Shape: preheader → header → body → dispatch(phi) → {latch|exit} → header with PHIs centralized in dispatch.
  • State: model loop-carried values via a LoopState aggregate (tag + payloads).
  • Goals: move all PHIs to dispatch, ensure header uses are dominated by preheader/dispatch values.

Types and Bridges

  • Box handle is i64 across NyRT boundary; strings prefer i8* fast paths.
  • Convert rules: ensure_i64/ensure_i1/ensure_ptr style helpers (planned extraction) to centralize casting.

Harness (optional)

  • llvmlite harness exists for fast prototyping and structural checks.
  • Gate: NYASH_LLVM_USE_HARNESS=1 (planned wiring); target parity tested by Acceptance A5.

References

  • LOWERING_LLVM.md — lowering rules and runtime calls
  • RESOLVER_API.md — Resolver design and usage
  • LLVM_HARNESS.md — llvmlite harness interface and usage