a

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/history/21-micro/notes.md b/docs/history/21-micro/notes.md
new file mode 100644
index 0000000..77c8d8b
--- /dev/null
+++ b/docs/history/21-micro/notes.md
@@ -0,0 +1,23 @@
+# 21 — microcore
+
+a second interpreter, small enough to carry the genome to a new target. `core.c` is unchanged and still the jit, the llvm backend, o3 and the enhancement optimizer.
+
+## what it is
+
+`micro.c` (467 lines) is the base machine: 1m words, the two stacks, opcodes 0..21, call and return, and a copy of `genome.h` at `GORG`. it includes `stdint.h` and `genome.h` and nothing else. compiled with `-ffreestanding`, the only undefined symbols are the five hooks in `micro_port.h`: read a byte, write a byte, end of input, the syscall gate, and a diagnostic line. bss must be cleared before `micro_run`. the image is still 8 mb. on a cpu without a 64-bit divider the compiler's division helpers get linked as well; the object built here does not reference them.
+
+`port_linux.c` is the hosted port the suite runs (stdin, stdout, the six syscalls, stderr for the overflow lines). `port_stub.c` is the bare-metal sketch: a uart transmit register, input already finished, and every syscall returning -1.
+
+## enhancements
+
+`/` `%` `<<` are not base opcodes. the genome installs `idiv`, `imod`, `ishl`, `lfa` and `outside` through opcode 21 at boot, and user programs install more. a built-in for only the first three would miss `lfa` and `outside`, which o3 code emits as ordinary opcodes, and would miss `enhance` in the tests. pointing the operators at `zdiv` in `rt.zc` would make a different genome from the one `core.c` runs. so the microcore lowers a recipe, or a straight-line `vm` body, to a flat micro-op list and runs it. no constant folding, no multiply-high division. `x / 7` is a divide; the quotient matches. a `vm` body with i/o or a branch fails install with -4, so an `else` fallback still runs. install kind 2 (an o3 region) returns 0 and is ignored. the bytecode of that region still runs, which is why the o3 tests print the same numbers.
+
+the caps: 128 ops and 256 values in one enhancement, 4096 ops in the pool. reinstalling the most recent slot reuses its pool space; other reinstalls leak until the pool is full, and then install returns -5. an enhancement's stores do not enter the syscall gate, same as `core.c`.
+
+## left out
+
+no jit, no llvm, no o3 register interpreter, no coverage map, no threads. speed is the plain interpreter, slower still where `core.c` rewrote a constant divide. still not a C ABI. a character is still one word. the compiler's source buffer still packs four characters into a word.
+
+## check
+
+`test.sh` runs the interpreter suite and then the same examples and feature tests on `micro.c` linked with `port_linux.c`. output matches, including the self-compile against the interpreter's image. `micro.c` and `port_stub.c` compile with `-ffreestanding`.