Move the engine core into core/, a project of its own (pplus-core)
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
This commit is contained in:
1567 files changed
+3670
-981
No files matched your search
@@ -0,0 +1,49 @@
|
||||
# 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`/`pext` are named as not modelled)
|
||||
- the atomics behind reference counts: `xadd`, `cmpxchg`, and the `lock` prefix, 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 comisd` and their `v` forms: IEEE binary64, round to nearest even, default NaN `0xFFF8000000000000`, a NaN operand is quieted and the first operand wins. MXCSR exception flags are not modelled.
|
||||
- `ucomisd`/`comisd` set 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…` and `setp…` follow.
|
||||
- `shld`/`shrd` on 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-bit `xmm` registers and no `ymm` halves; the five instructions above exist only in that width. A `ymm` operand 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, `…@GOTPCREL` function pointers, a `.zero` constant. 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.
|
||||
Reference in new issue
Block a user