Baseline: tree as shared

This commit is contained in:
alexm committed 2026-10-05 03:03:38 +00:00
commit 31f2fb8a5a
1679 files changed
+1024562

No files matched your search

+77
View File
@@ -0,0 +1,77 @@
---
title: "The machine"
subtitle: "x86-64 on a model machine, every step drawn with the page"
---
These shortcodes show what the Hardware area's board shows: the registers, memory, the caches, the pipeline and the core, running an x86-64 file beside the page. While Quarto renders, the extension runs the program on the model machine and draws each view at every step of the run. The page carries those drawings, compressed, and the stepper moves through them. Nothing runs in the reader's browser, and the page opens on the step you choose, so it prints too.
The program is `programs/two-pointers.asm`: it counts the values two sorted lists have in common. Its registers and memory are set by `programs/two-pointers.setup`:
```
rdi = 0x1000 rsi = 6 rdx = 0x2000 rcx = 7
memory 0x1000 bytes 1 0 0 0 0 0 0 0 4 0 ...
```
## The board
`pplus-hw` puts the listing beside a set of cards. With no options, it uses the board's first arrangement: registers, flags, address arithmetic, memory and the stack.
```markdown
{{{< pplus-hw asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" >}}}
```
{{< pplus-hw asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" >}}
`preset=` picks one of the board's other arrangements: `caches`, `pipeline` or `chip`. `views=` names the cards yourself, in order, and `t=` is the step the page opens on:
```markdown
{{{< pplus-hw asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" preset="caches" t="12" >}}}
{{{< pplus-hw asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" views="explain,registers,encoding" >}}}
```
{{< pplus-hw asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" preset="caches" t="12" title="The caches, at step 12" >}}
## One view at a time
Each card of the board is also a shortcode of its own, `pplus-hw-<view>`:
| shortcode | shows |
|---|---|
| `pplus-hw-code` | the machine code: each instruction with its address and bytes |
| `pplus-hw-explain` | the last instruction in words: what it read, computed and wrote |
| `pplus-hw-registers`, `pplus-hw-flags` | the registers the program touches, and ZF, SF, CF, OF, PF |
| `pplus-hw-address` | base + index × scale + displacement, part by part |
| `pplus-hw-memory`, `pplus-hw-stack` | memory byte by byte, and the stack's slots |
| `pplus-hw-dataflow`, `pplus-hw-alu` | where the last instruction's values came from, and the ALU at bit level |
| `pplus-hw-branches`, `pplus-hw-vectors` | each branch and the predictor's guess, and the xmm registers lane by lane |
| `pplus-hw-lines`, `pplus-hw-cache`, `pplus-hw-hierarchy` | the cache line each access touched, the L1 data cache, and the path through L1, L2, L3 and memory |
| `pplus-hw-paging` | the page walk and the TLB (it switches virtual memory on) |
| `pplus-hw-pipeline`, `pplus-hw-uops`, `pplus-hw-timeline`, `pplus-hw-bottleneck` | the five-stage pipeline, micro-ops and ports, the out-of-order timeline, and what limits the speed |
| `pplus-hw-counters` | the run as totals, in the style of `perf stat` |
| `pplus-hw-chip`, `pplus-hw-core`, `pplus-hw-encoding` | the whole core lit up, inside the out-of-order core, and the instruction's bytes field by field |
```markdown
{{{< pplus-hw-pipeline asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" listing="0" max="40" >}}}
```
{{< pplus-hw-pipeline asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" listing="0" max="40" >}}
The whole core, with the parts the last instruction used lit up:
{{< pplus-hw-chip asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" t="9" >}}
Virtual memory: the page walk and the TLB. `pplus-hw-paging` turns virtual memory on for the run.
{{< pplus-hw-paging asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" t="10" >}}
`stepper="0"` draws one step and nothing else, which suits a figure in a printed handout:
{{< pplus-hw-encoding asm="programs/two-pointers.asm" setup="programs/two-pointers.setup" t="9" stepper="0" listing="0" caption="Step 9, mov r11, qword ptr [rdx + r9*8], byte by byte." >}}
## From Mojo to the machine
`pixi run quarto-export demo <folder>` writes a Mojo program's x86-64, from the real compiler's listing, beside a page, along with a setup for its arguments. Here it is the `cell` function of the demo's Smith-Waterman alignment (`programs/cell.asm`): the best of three scores, with three branch-free `cmovg`s. Each instruction's comment names the Mojo line it came from.
{{< pplus-hw asm="programs/cell.asm" setup="programs/cell.setup" views="explain,registers,flags" >}}
{{< pplus-hw-counters asm="programs/cell.asm" setup="programs/cell.setup" listing="0" stepper="0" >}}