52 lines
2.8 KiB
Markdown
52 lines
2.8 KiB
Markdown
# Phase 20.9 Tasks & Rules — C ABI Kernel
|
||
|
||
Status: Active (Phase 20.9)
|
||
|
||
Objectives
|
||
- Stabilize LLVM→C ABI execution (EXE/JIT) with Fail‑Fast diagnostics.
|
||
- Migrate C ABI kernel to `lang/c-abi/` with clear ownership & contracts.
|
||
- Codify rules for extern mapping and diagnostics.
|
||
|
||
Rules (Box‑First / Fail‑Fast)
|
||
- Canonical Header:
|
||
- Use `lang/c-abi/include/hako_hostbridge.h` as the single source of truth.
|
||
- `include/hako_hostbridge.h` is a compatibility shim only.
|
||
- CI: run `tools/ci/check_header_canonical.sh` (WARN now; STRICT later).
|
||
- Extern Mapping:
|
||
- Avoid dotted C symbols in AOT (e.g., `env.console.log`). Map to direct C symbols (`hako_console_log`).
|
||
- Policy: script extern → unified name in C ABI (`hako_*`).
|
||
- GC/time/mem/console: hako_gc_stats/hako_gc_roots_snapshot/hako_mem_*/hako_console_log/hako_time_now_ms.
|
||
- Diagnostics (short, stable):
|
||
- Missing symbol (EXE): `SMOKES_ERR: symbol_missing[:<name>]`.
|
||
- MIR emit failure: `SMOKES_ERR: mir_emit_failed`.
|
||
- Compiler/link fail (other): `SMOKES_ERR: llvm_compile_failed`.
|
||
- VM invalid extern: normalized to `SMOKES_ERR: invalid_inst ...`.
|
||
|
||
Work Items
|
||
- [x] Canonicalize header path in docs/tools (bridge/ABI_v1/ABI_MAP) and provide compatibility shim.
|
||
- [x] Add CI header canonical check (WARN mode).
|
||
- [x] Normalize EXE linker diagnostics to short lines.
|
||
- [x] Map console/time to direct C ABI (`hako_console_log`, `hako_time_now_ms`).
|
||
- [x] Ensure GC externs use direct C ABI (`hako_gc_stats`, `hako_gc_roots_snapshot`).
|
||
- [ ] Expand policy doc for extern naming & migration examples (`env.*` → `hako_*`).
|
||
- [x] Expand policy doc for extern naming & migration examples (`env.*` → `hako_*`).
|
||
- [x] Plan STRICT mode for header canonical check (enable `CI_STRICT=1`) — docs/README に手順追記、集約: `tools/ci/run_local_checks.sh`。
|
||
- [x] Add a lint to flag dotted C symbol emission in AOT IR (future) — stub: `tools/ci/checks/aot_dotted_symbol_check.sh` (WARN; STRICT later).
|
||
|
||
Proposed C API Additions (pending)
|
||
- `hako_env_local_get(const char* key) -> char*` [landed]
|
||
- Returns a newly allocated UTF‑8 string of the environment value or NULL if not found.
|
||
- Ownership: caller must free via `hako_mem_free()`.
|
||
- Diagnostics: on NULL, set TLS `hako_last_error` to a short, stable reason (`NOT_FOUND` or `VALIDATION`). LLVM lowering emits warn `NOT_FOUND`.
|
||
- Thread‑safety: required.
|
||
- Notes: prefer NULL + short diagnostic over empty string. Avoid CRT mismatch.
|
||
|
||
References
|
||
- README.md, PLAN.md, CHECKLIST.md, SMOKES.md
|
||
- tools/ci/check_header_canonical.sh
|
||
- tools/smokes/v2/lib/llvm_exec.sh
|
||
|
||
Smokes/Parity (added in this phase)
|
||
- [x] Integration-core parity: env.local.get exists — tools/smokes/v2/profiles/integration-core/env_local_get_exists_core.sh
|
||
- [x] Failure diagnostics (EXE): mir_emit_failed — tools/smokes/v2/profiles/quick/llvm/diagnostics_mir_emit_failed_exe.sh
|