What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
5.9 KiB
The model machine against compiled Mojo
"Open in Hardware" puts a function from the real compiler's listing on the model machine (src/engines/asm86), translated from godbolt's AT&T syntax by src/mojo/att.ts. The machine implements a teaching subset of x86-64, so the question is how much of what the Mojo compiler actually emits it can take. This is the census: every function in every listing the corpus holds (mojo/golden/*.json answered with asm), sent exactly as the button sends it, and what the assembler said. node scripts/asm-census.mjs reruns it (add --ops for every mnemonic); tests/asm-coverage.test.mjs holds the numbers as a ratchet, so a new corpus item that brings a new instruction fails the build rather than a student's session.
Where it stands
| before | now | |
|---|---|---|
| distinct instructions in the listings | 97 | 97 |
| of which outside the model's set | 38 | 5 (all 256-bit AVX2: vextracti128, vinserti128, vpblendvb, vperm2i128, vpalignr) |
| the user's own functions that assemble | 3 of 7 (main never did) |
7 of 7 |
| standard-library and runtime functions that assemble | — | 438 of 467 |
main() now steps 25–29 instructions and stops at the call into print with "stopped: std_io_io_print: standard library, not on the model machine", which is the honest answer: the model has no standard library, and says exactly where the real program would enter it.
What was wrong, and what changed
The translator dropped size suffixes only for the mnemonics it knew. AT&T writes andnq, mulxq, shlxq, xaddq, cmpxchgq, btsq, bswapq; the Intel pane reads andn, mulx, … The BMI and atomic mnemonics were missing from the suffix table, so the machine was asked for an instruction called andnq, which exists nowhere. They are in the table now, and lock (a prefix) is passed through as a prefix rather than treated as a mnemonic with an operand called xaddq.
The machine lacked the instructions the optimiser likes. Added, each with a one-sentence gloss for the datapath view and the micro-op model told what it reads and writes:
- BMI1/BMI2:
andn,mulx,shlx,shrx,sarx,bzhi,blsr,blsi,blsmsk,rorx,bextr(pdep/pextare named as not modelled) - the atomics behind reference counts:
xadd,cmpxchg, and thelockprefix, accepted on the read-modify-writes the ISA allows it on - bit tests that write:
bts,btr,btc;bswap;cwd,cwde,cbw ud2: the trap the compiler plants on paths that must never run; reaching it stops the run with "the processor raised an invalid-opcode fault"- the 128-bit AVX spellings of what the subset had:
vmovdqu,vmovdqa,vmovups,vmovaps,vmovd,vmovq,vpxor,vxorps,vpor,vpand,vpandn,vpaddb,vpsubb,vpcmpeqb,vpmovmskb,vzeroupper; three-operand form (vop dst, a, b), sources untouched - lanes:
vpinsr{b,w,d,q},vpextr{b,w,d,q},vpshufb,vpshufd,vpbroadcast{b,d},vpmin/max{ub,ud},vpcmpeq{w,d,q},vpadd{w,d},vpsubd,vpsubusb,vpsll/vpsrl{w,d,q}
A call into the standard library refused the whole listing. The assembler resolves every label up front, so one call std::io::print meant the function could not be stepped at all, even to the instruction before the call. The translator now appends a stub for every such symbol (label: then ud2 ; …: standard library, not on the model machine), so the function assembles, steps up to the call, and the stop says what it called.
Read-only strings were unreachable. lea rax, [rip + static_string_…] named a label that was data, not code, and the machine has no data directives. The translator now finds the .asciz behind each such label, places the bytes in memory (memory 0x6000 "…", octal and hex escapes decoded, from 0x6000 up), writes the address in the instruction's place, and hands the lines to the setup block, where the student can see them.
Scalar doubles, parity, shld (added)
addsd subsd mulsd divsd sqrtsd movsd cvtsi2sd ucomisd comisdand theirvforms: IEEE binary64, round to nearest even, default NaN0xFFF8000000000000, a NaN operand is quieted and the first operand wins. MXCSR exception flags are not modelled.ucomisd/comisdset ZF/PF/CF as hardware does (unordered sets all three; OF, SF clear).- PF is a real flag now: set by logic, add/sub and shifts, cleared by
popcnt, untouched by rotates.jp jnp jpe jpo,cmovp…andsetp…follow. shld/shrdon 32- and 64-bit operands; count masked to 5/6 bits; count 0 changes nothing, flags included.- Latencies: add/mul 4, div 14, sqrt 18 (unpipelined on port 0), convert 5, compare 3.
What stays outside, and why
- 256-bit AVX2 (
ymm): the model keeps sixteen 128-bitxmmregisters and noymmhalves; the five instructions above exist only in that width. Aymmoperand is refused with that sentence. Modelling it means widening every vector register and every lane helper; worth doing only when a user function needs it, and none in the corpus does. - Symbols the listing addresses but does not define:
KGEN_…runtime globals,…@GOTPCRELfunction pointers, a.zeroconstant. The assembler names the symbol in its refusal. - Constant-pool blocks with a symbol in them (jump tables): not placed; the instruction that loads one is refused by name. Numeric
.LCPI…blocks (.quad,.long,.double,.zero, …) are placed, 16-byte aligned from 0x6000, when the code addresses them, and.LCPI0_0+8(%rip)works.
Keeping it honest
The census runs against whatever the corpus holds. Seven goldens carry listings today (the asm/both probes); pixi run mojo-verify with mode: asm probes adds more, and each addition either assembles or fails tests/asm-coverage.test.mjs with the instruction named. The ratchet numbers in that test are the ones in the table above; raise them when the machine learns more, never lower them.