1 files changed, 21 insertions, 0 deletions
diff --git a/docs/history/28-bytes/notes.md b/docs/history/28-bytes/notes.md
new file mode 100644
index 0000000..24a67fa
--- /dev/null
+++ b/docs/history/28-bytes/notes.md
@@ -0,0 +1,21 @@
+# 28 — byte addressing
+
+memory stays an array of 64-bit words. a byte address is a second numbering of that same image: word `w` occupies bytes `w << 3` through `(w << 3) + 7`, and byte 0 of a word is its low 8 bits. `baddr` and `waddr` convert. the odd/even tag is only for code words (a literal is an odd word, an opcode is even), so a byte address is a plain integer and can be odd. `u`, `m` and `d` stay on the word pointer of a heap object. a byte address into a payload is not itself a tracked owner.
+
+the opcodes sit above the floats, so the enhancement slots do not move:
+
+```
+612 ld8   613 st8   614 ld16   615 st16   616 ld32   617 st32
+```
+
+16- and 32-bit accesses are little-endian and may cross a word boundary. an access that does not lie entirely inside memory loads 0 and stores nothing. the runtime names are `ld8`, `st8`, `ld16`, `st16`, `ld32`, `st32`. `bops.h` is the one implementation. the interpreter, the microcore and the llvm backend call it. the arm64 jit calls the same functions, so a spanning store is one path on every target. a byte store of a word some translation covers goes through the same hook as opcode 2, and the block is dropped. it does not run a syscall. the gate is still a word store at `SYSGATE`.
+
+`tests/bytes.zc` checks a spanning 16-bit store, a 32-bit store, the two words those stores build, an address off the end of memory, a 1000-byte checksum (30768), and a rewrite of the literal in `f` from `A` to `B` to `C` by storing one byte of that code word. on the jit that store drops the translation twice. the line is the same on the interpreter, the microcore, the arm64 jit, llvm with `ZYHOT=1`, the small compiler, the run-only image, and both virt boards.
+
+`tests/bench_bytes.zc` is a run-only image, so the timing does not include the resident compiler. it walks 4000 bytes of a 512-byte buffer, repeated, and the slope between one repetition and many is the loop. the checksum of one repetition is 123504.
+
+the run-only hole was 10240 words. the byte runtime plus `tests/bytes.zc` is 10365, so the reservation is 11264 and that machine is still 32768 words. the frame, return and mark stacks moved up by 1024 and the data stack gave up those words. hello on that map is 9742 words. the fixpoint image grew from 93712 words to 94083.
+
+`test.sh` after this stage: 327 passed, 0 failed. the twelve new checks are the byte line on the interpreter, the microcore, the arm64 jit and the llvm backend, the small microcore and `core.c` at that size, the run-only image, both virt boards running the program and compiling it, and one llvm run with `ZYHOT=1`.
+
+`bench_bytes.sh` times a run-only image, 4000 byte loads per repetition, slope of 1 repetition against 40. checksum 123504. on this host: interpreter 1.24 ms, microcore 1.20 ms, arm64 jit under qemu-user 0.53 ms, llvm 0.50 ms. the llvm slope includes compiling the loop once, because one repetition stays under the default hot threshold and forty do not.