Files
pplus-web/docs/asm-coverage.md
T
2026-10-05 03:03:38 +00:00

50 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.