admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(v4): the ROMs' shared entries, and the mesh ROM as built

Browse Source 
DATASHEET-F18.md lists all 19 entries of the host ROM, the six shared ones
with the registers they use.  MACHINE.md 2.2: built; 277 words, not the
estimated 150-200; the system's words are address, push and ;.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-15 20:32:23 -04:00
co-authored by Claude Opus 5.5
parent d2df3679ac
commit 924c48cece
2 changed files with 47 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/v4.0.0/DATASHEET-F18.md
+35 -9
View File
@@ -96,14 +96,40 @@ registers (§10.3).
- **I/O addresses** (§10) sit inside the address space. A fetch from or store to one goes to
the device, not to RAM. The exceptions are NODE-ERROR, which writes RAM and then traps, and
the console receive addresses, where a store goes to RAM.
- **ROM.** Built (2026-10-15; `MACHINE.md` §2): 2049 words of F18 code, `capsules/v4/rom`,
assembled by `v4/tools/mkrom.c`. The machine starts at its entry 12 and assembles the
system's source (`capsules/v4/sys`) from the console. It is a read-only range at
- **ROM.** Built (2026-10-15; `MACHINE.md` §2): 2372 words of F18 code, `capsules/v4/rom`,
assembled by `v4/tools/mkrom.c`. The machine starts at its entry 18 and assembles the
system's source (`capsules/v4/sys`) from the console. A mesh node's ROM (`MACHINE.md` §2.2)
is 277 words: entries 0–5, the shared math, and nothing else. It is a read-only range at
`V4_NODE_WORDS` and above. It can be fetched and executed. A store there is an address fault.
In the model it is attached by the owner, as every device is, and a reset detaches it.
- Its routines are shared code, GA144-style (`MACHINE.md` 2.1). Payloads call them through
the entry table at the ROM's base. Their state lives in a reserved RAM area. This sheet will
list each entry's stack effect and the registers it uses once the ROM is built.
the entry table at the ROM's base. Their state lives in a reserved RAM area. The entries:
| Entry | Routine | Stack | Uses | In |
|---|---|---|---|---|
| 0 | `UM*` | ( u1 u2 -- ulo uhi ) | A | both ROMs |
| 1 | `UM/MOD` | ( ulo uhi ud -- urem uquot ), exact for uhi < ud | A | both ROMs |
| 2 | `D+` | ( d1 d2 -- d3 ) | — | both ROMs |
| 3 | `DNEGATE` | ( d -- -d ) | — | both ROMs |
| 4 | `Q.*` | ( a b -- c ), Q48.16 | A | both ROMs |
| 5 | `Q./` | ( a b -- q ), Q48.16; by zero: D-11's result and error 11 | A, B; `(Q/)`'s 5 cells | both ROMs |
| 6 | `(KEY)` | ( -- c ) | | host ROM |
| 7 | `(TOKEN)` | ( -- len ) | | host ROM |
| 8 | `(NUMBER)` | ( -- n flag ) | | host ROM |
| 9 | `(FIND)` | ( -- rec \| 0 ) | | host ROM |
| 10 | `(DEFINE)` | ( value kind -- ) | | host ROM |
| 11 | `(OPCODE)` | ( -- op \| -1 ) | | host ROM |
| 12 | `(OP)` | ( op -- ) | | host ROM |
| 13 | `(LIT)` | ( v -- ) | | host ROM |
| 14 | `(BRANCH)` | ( op target -- ) | | host ROM |
| 15 | `(BRANCH>)` | ( op -- ref ) | | host ROM |
| 16 | `(RESOLVE)` | ( ref target -- ) | | host ROM |
| 17 | `(LABEL)` | ( -- addr ) | | host ROM |
| 18 | `(ROM)`: where the host machine starts | | | host ROM |
The list is `v4/include/v4/rom_entries.h` for entries 0–5 and `capsules/v4/rom/main.f18`
for the rest. The assembler's routines (6–17) use A and B freely and keep their state in
the ROM's area of the memory map; their registers are not yet listed one by one.
## 6. Instruction word
@@ -309,10 +335,10 @@ These are reported, not hidden:
and it is not to be extended.
2. **Device addresses are attached by the owner, not fixed.** D-4 (the memory map) is deferred.
The FPGA needs fixed addresses.
3. **The ROM** is built and the host node boots from it (2026-10-15). The ROM is the full
assembler, about 2000 words, so it is the host node's. A mesh node's small loader ROM
(the agreed correction, `JUSTIFICATION.md` §9) is not built yet. Until it is, a node that
is born is sent the host's assembled system through its port.
3. **The ROM** is built and the host node boots from it (2026-10-15). A mesh node's ROM is
built too (`MACHINE.md` §2.2): entries 0–5, the shared math, and nothing else. In the test
host a node Hera births carries it. The products have no births yet, so they do not link
it. A node that is born is still sent the host's assembled system through its port.
4. **`stack.h`'s opening comment** still says there is no overflow detection "and there never
will be". D-16 revised that, and the header carries a revision note above it. The code
counts and guards (§4). The comment's first paragraph is out of date.