Skip to content

fpga(wasm_module): load a whole .wasm image: LEB128 pairs, section walk, function table, exports, data segments (Closes #12201) - #12278

Merged
github-actions[bot] merged 7 commits into
masterfrom
lane/wasm-loader-12201
Oct 25, 2026
Merged

github-actions[bot] merged 7 commits into
masterfrom
lane/wasm-loader-12201

Conversation

@gHashTag

Copy link
Copy Markdown
Collaborator

Closes #12201. Refs #9367 (WASM-on-AX7203 tracker). Epic: see Trinity-S-AI-DNA/trinity-fpga#917.

What

DOOM ships as one .wasm image; before this PR specs/fpga/wasm_module.t27 could read a LEB128 pair, check the 8-byte header and step to the next section, and nothing else. This PR adds the loader: load(src, src_len) walks a whole module held in a [SRC_MAX]u8 array and returns a ModuleDesc with

  • per-function code ranges and locals vectors (sec_function, sec_code, func_lookup),
  • the import function count and the memory and table limits (sec_import, sec_limits, limits_read),
  • exports as (name offset, length, kind, index) and export_find by name (sec_export),
  • data segments as (destination, source offset, length) triples (sec_data),
  • the start function and the global and element payload ranges (sec_start, sec_counted),
  • named failure codes ERR_BAD_MAGIC, ERR_BAD_VERSION, ERR_TRUNCATED, ERR_TOO_MANY, ERR_MALFORMED, ERR_UNSUPPORTED.

The array readers leb_u32, leb_s32, leb_s33 return a (value, n) struct under the 5-byte limit and never index past src_len. No new function takes a slice; the existing uleb_read and sleb32_read stay. One spec file changes, nothing else: no baseline edit, no seal, no gen/.

15 new tests (21 in the spec): the spec appendix LEB vectors, four hand-encoded modules with every offset counted by hand (minimal module with one function and main exported as 0, body at 0x41 of length 4; a data segment module; an import module where function 0 is the import; limits plus a start function), and the four error codes.

Measured (commands as run, 2026-10-25, master-built t27c)

check result
t27c test-report specs/fpga/wasm_module.t27 21 of 21, 0 vacuous
t27c gen-verilog specs/fpga/wasm_module.t27 clean, 79416 bytes, empty stderr
iverilog -g2012 -DSIMULATION -o /dev/null wasm_module.v exactly 6 error lines, all Unable to bind ... src_len in uleb_read, sleb32_read, header_ok, next_section; this is the class the baseline row wasm_module 6 already records, so the row is unchanged
yosys -q -p "read_verilog -sv -DSIMULATION wasm_module.v; hierarchy -top fpga_wasm_module" exit 0
python3 tools/dupe_scan.py ok: no new duplicate body, none of the known groups grew
git diff --stat origin/master one path, specs/fpga/wasm_module.t27, +861 -3

Not measured: nothing was synthesised or flashed. The module is loaded from an array in simulation; the UART or flash path that fills that array on the AX7203 is the next step, not this one. Until a bitstream is loaded with openFPGALoader -c digilent_hs2 and the UART answers, every run is a simulation.

Disclosure

The first shape of this spec declared its struct locals with untyped const x = call(...) inside while and if bodies and elaborated with 82 error lines. Declaring the same 20 locals once at the top of each function as a typed var with a zero struct literal, and assigning inside the block, brought it to the 6 above with no change to the tests. That is a gen-verilog gap, not a property of the loader; it is filed as #12277 with the before/after counts, and the spec header says why the locals sit where they do.

Next on this path: wasm_board_ax7203 takes the ModuleDesc (code ranges, exports, data segments into linear memory from #12202) and the UART loader fills src.

🤖 Generated with Claude Code

gHashTag and others added 6 commits October 24, 2026 23:45
…aw tables that landed without rows (Closes #12051)

Both reached master without rows (#11864, #11867), so the ratchet read them as NEW and the fpga-conformance step has been red on master since (run 40109127962: 431 against 276; 276 + 6 + 149 = 431, no other module moved). The note under the notes mark records the measured shape of each count: one ROWS line with 149 unsized zeros, and src_len unbound in 4 fns plus the 2 condition lines derived from them. No bless, no spec change, no gate change.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…7os, so fpga-lint and the elab ratchet pass (Refs #12171, Refs #12051)

fpga-lint has been red on master since #10949 landed hdmi_grab (2026-10-22):
gen-verilog copies a t27 char literal verbatim, Verilog reads '0 as an unsized
literal, and yosys stopped at line 88 of hdmi_grab.v. Behind that line the same
file carried its libc host part (getenv, fork, execve, fopen, main), which
cannot be Verilog either, so a compiler fix alone would have moved the error,
not removed it. #12171 keeps the compiler side open; this is the spec side.

- specs/fpga/hdmi_grab.t27: the ten characters the checker compares bytes
  against are consts (CH_0 .. CH_SP), one home each; no char literal is left.
  The host tail (HG_BUF/HG_LIST/HG_CMD/HG_PATH, hg_cat, hg_env, hg_sh,
  hg_slurp, hg_path, main) left the file. test-report: 14 tests, 14 pass,
  0 vacuous.
- specs/t27os/hdmi_grab_main.t27 (new, module T27osHdmiGrabMain): that host
  tail, verbatim, importing hg_* / V_PASS / CH_0 from fpga::hdmi_grab by use,
  the way plist_main.t27 imports install/release. t27c gen splices the
  imports into one .zig (use_resolve.rs); zig build-exe -lc builds it (1.9 MB
  binary, no diagnostics). Two tests on the two helpers it adds (frame path,
  byte copy): 2 pass, 0 vacuous.
- tools/elab_baseline.txt: hdmi_grab 57 -> 5 (431 -> 379), note dated
  2026-10-25. The 5: 4 x pixel_at taken by use from vga_text_core (gen-verilog
  binds no imports) and 1 x nd_len, an unsized array param (#2410).

Measured on the regenerated hdmi_grab.v with a master-equivalent t27c:
yosys -p "read_verilog -sv -DSIMULATION hdmi_grab.v; hierarchy -top
fpga_hdmi_grab" exits 0; grep -c "\$signed('" = 0; iverilog -g2012
-DSIMULATION: 5 error lines without the summary line, as the ratchet counts.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…lk, function table, exports, data segments (Closes #12201)

The loader walks one module held in a [SRC_MAX]u8 array plus an explicit
src_len and returns a ModuleDesc: per-function code ranges and locals
vectors, the import function count, exports (name offset, length, kind,
index), data segments as (destination, source offset, length) triples,
memory and table limits, the start function, and the global and element
payload ranges. Failures are named codes: ERR_BAD_MAGIC, ERR_BAD_VERSION,
ERR_TRUNCATED, ERR_TOO_MANY, ERR_MALFORMED, ERR_UNSUPPORTED. Never
indexes past the array.

LEB128 u32, s32 and s33 readers return a (value, n) struct under the
5-byte limit. No new function takes a slice; the existing uleb_read and
sleb32_read stay. Struct locals born in loops and branches are declared
once at the top of the function body and assigned inside, because
gen-verilog hoists only top-level locals.

15 new tests (21 in the spec): the spec appendix LEB vectors, four
hand-encoded modules with offsets counted by hand, and the four error
codes.

Refs #9367; see Trinity-S-AI-DNA/trinity-fpga#917

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

PR Dashboard

Generated at: 2026-10-25 05:07:23 UTC

Summary

Status Count
Total Open PRs 46
PRs with Failing Checks 41
PRs with All Checks Green 5
READY 3
FAILING 41
PENDING 0
NO CHECKS YET 0

These columns do not partition: 3 + 41 + 0 + 0 = 44, and there are 46 open PRs. A PR is being counted twice or not at all.

Seal Status

  • ⚠️ STALE -- sha256(compiler.rs)=55c0f1b1b32d != manifest seal=87e5cbd3ad94.
    The committed NMSE numbers were certified against an older compiler.rs.
    Run scripts/reseal-check.sh locally for the two-step reseal command (advisory; not a merge gate).

@tri-claw

tri-claw Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Summary by t27-bees

Checked by the t27 compiler

t27c parse, parse-complete and typecheck on each changed .t27 file at 3cb241a. Nothing was generated, built or run. A pass means the file is well formed, not that it is right.

  • specs/fpga/wasm_module.t27: parses and typechecks.

Read by the model

This PR adds a complete WebAssembly module loader (load) that walks a [SRC_MAX]u8 image and produces a ModuleDesc with function code ranges, locals, imports, exports, data segments, memory/table limits, and the start function. It includes LEB128 readers (leb_u32/leb_s32/leb_s33), section dispatch, and 15 new tests covering the spec appendix vectors plus four hand-encoded modules and error paths.

Worth a look

  • specs/fpga/wasm_module.t27:170 (section_at) — The truncation check r.value > len - payload relies on payload ≤ len, which holds only because leb_u32 fails when the size LEB128 crosses len. If a future change calls section_at with an arbitrary at/len where the size LEB128 is complete but payload > len, the unsigned subtraction wraps and the check passes incorrectly. Consider if (payload > len || r.value > len - payload).

  • specs/fpga/wasm_module.t27:310 (sec_import name skipping) — Same pattern: if (l.value > pend - p) after p += l.n. If p has already passed pend (e.g., from a prior malformed entry), pend - p wraps and the check misses the overflow. The subsequent if (p >= pend) catches it on the next loop iteration, but the window between the two checks reads past the section with leb_u32 (which clamps to pend and returns zeros), potentially parsing bogus lengths.

  • specs/fpga/wasm_module.t27:18 (SRC_MAX = 256) — The image capacity is 256 bytes. The comment notes "DOOM-class wasm has about 1000 functions" (FUNC_MAX=1024), but a real DOOM module far exceeds 256 bytes. The loader returns ERR_TOO_MANY for src_len > SRC_MAX. This is documented as NOT CLAIMED, but the disparity between SRC_MAX and FUNC_MAX suggests the constants may need coordination when the UART/flash loader lands.

  • specs/fpga/wasm_module.t27:560 (sec_data flag check) — Only flag 0 (active, memory 0, i32.const offset) is accepted; any other flag returns ERR_UNSUPPORTED. This excludes passive segments, multi-memory, and non-const offsets. Documented in NOT CLAIMED, but the error code ERR_UNSUPPORTED conflates "valid but unsupported" with "malformed".

  • specs/fpga/wasm_module.t27:620 (load final consistency check) — if (d.nfunc != d.ncode) catches function/code count mismatch, but there is no cross-check that func_type indices are within the type section count (the type section is skipped entirely). A module with a function section referencing a non-existent type index would load with OK.


Read: 1 files, +861 -3, the whole diff. Head 3cb241a. Model: openai-compatible/nvidia/nemotron-3-ultra-550b-a55b. Commands: @t27-bees review | summary | help | pause | resume. Free for every repository.

@github-actions

Copy link
Copy Markdown
Contributor

PR Dashboard

Generated at: 2026-10-25 06:48:04 UTC

Summary

Status Count
Total Open PRs 50
PRs with Failing Checks 28
PRs with All Checks Green 22
READY 5
FAILING 28
PENDING 0
NO CHECKS YET 0

These columns do not partition: 5 + 28 + 0 + 0 = 33, and there are 50 open PRs. A PR is being counted twice or not at all.

Seal Status

  • ⚠️ STALE -- sha256(compiler.rs)=55c0f1b1b32d != manifest seal=87e5cbd3ad94.
    The committed NMSE numbers were certified against an older compiler.rs.
    Run scripts/reseal-check.sh locally for the two-step reseal command (advisory; not a merge gate).

This was referenced Oct 25, 2026
@github-actions
github-actions Bot merged commit ae1d823 into master Oct 25, 2026
44 checks passed
@gHashTag
gHashTag deleted the lane/wasm-loader-12201 branch October 26, 2026 03:42
@gHashTag gHashTag added the doom-ax7203 DOOM on the AX7203: every issue of the WASM board route (epic #12387) label Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doom-ax7203 DOOM on the AX7203: every issue of the WASM board route (epic #12387)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fpga: wasm_module -- a loader for a real .wasm binary: LEB128, section walk, function table, exports, data segments

1 participant