46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
|
# C ABI Kernel — Minimal Shim for Phase 20.9
|
|||
|
|
|
|||
|
|
Responsibility
|
|||
|
|
- Provide a portable, minimal C ABI surface used by the LLVM line.
|
|||
|
|
- Read‑only GC externs first (`hako_gc_stats`, `hako_gc_roots_snapshot`), plus memory/console/time/local-env helpers.
|
|||
|
|
|
|||
|
|
Inputs/Outputs
|
|||
|
|
- In: Extern calls from Hakorune code compiled to LLVM (llvmlite harness / ny-llvmc).
|
|||
|
|
- Out: Simple values (i64) or newly allocated `char*` (caller frees with `hako_mem_free`).
|
|||
|
|
|
|||
|
|
Contracts
|
|||
|
|
- Ownership: `char*` returns are callee-owned; free via `hako_mem_free()`.
|
|||
|
|
- Alignment: pointers from `hako_mem_alloc/realloc` satisfy `max_align_t`.
|
|||
|
|
- Thread-safety: memory API and read-only helpers are thread-safe.
|
|||
|
|
- Diagnostics: use short, stable messages (NOT_FOUND/UNSUPPORTED/VALIDATION) via TLS `hako_last_error` when applicable.
|
|||
|
|
- Missing env key: `hako_env_local_get` returns NULL and sets `NOT_FOUND`.
|
|||
|
|
- LLVM lowering emits a short warn (stderr) on missing; return handle remains `0`.
|
|||
|
|
|
|||
|
|
Layout
|
|||
|
|
- `include/` — public headers (`hako_hostbridge.h` mirror or thin wrapper)
|
|||
|
|
- `shims/` — libc-backed reference implementation for canaries (`hako_kernel.c`)
|
|||
|
|
|
|||
|
|
Guards
|
|||
|
|
- No Rust modules or cargo manifests under `lang/`.
|
|||
|
|
- No parsing or codegen here; this is a plain ABI surface.
|
|||
|
|
|
|||
|
|
Build (example)
|
|||
|
|
```
|
|||
|
|
cc -I../../include -shared -fPIC -o libhako_kernel_shim.so shims/hako_kernel.c
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Link (LLVM canary)
|
|||
|
|
- Use rpath + `-L` to locate `libhako_kernel_shim.so` at runtime.
|
|||
|
|
- Example flags: `-L$ROOT/target/release -Wl,-rpath,$ROOT/target/release -lhako_kernel_shim`
|
|||
|
|
|
|||
|
|
APIs (Phase 20.9)
|
|||
|
|
- Memory: `hako_mem_alloc/realloc/free`
|
|||
|
|
- GC (read‑only): `hako_gc_stats`, `hako_gc_roots_snapshot`
|
|||
|
|
- Console: `hako_console_log/warn/error` (void side‑effect; returns 0)
|
|||
|
|
- Time: `hako_time_now_ms`
|
|||
|
|
- Local env: `hako_env_local_get` (caller frees via `hako_mem_free`)
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
- Future control hooks (`hako_gc_collect/start/stop`) are defined but gated; do not silently succeed.
|
|||
|
|
- Platform CRT note: Only `hako_mem_free()` may be used to free memory obtained from any `hako_*` API to avoid CRT boundary issues (Windows msvcrt/ucrt, macOS libc).
|