docs: correct opcode documentation against emulator implementation
authorSvjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Sun, 11 Oct 2026 07:27:31 +0000 (10:27 +0300)
committerSvjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Sun, 11 Oct 2026 07:27:31 +0000 (10:27 +0300)
commit2ed8c23a0069b47cae9b476f1b3a9358bc4ec395
tree044d036a1f4e5bbb59b1ce8c378d16a8477477c6
parentea3bb30c8aba8eccf8c9ed276e8b773f3b2af825
docs: correct opcode documentation against emulator implementation

Full audit of all 48 opcode entries against emulator/*.asm; every doc
claim now matches the silicon. Highlights:

- opcodes_20_29.org: fix c@/c! cross-references (opcodes 12/13, not
  16/17), fix inverted ">" bytecode example result, drop wrong swap in
  division pattern, replace broken <=/<> formulas with verified ones
  (> not; 2dup < rot rot > or), add 2dup to underflowing sort
  patterns, note idiv quotient-overflow crash.
- opcodes_40_49.org: vidmap copies 16 KB per granule (4096 dwords),
  not 4 KB; mouse@ returns int33h motion deltas, not absolute
  coordinates; cmove overlap direction was inverted and its example
  pushed args in wrong order; image structure offset 8 is inline
  pixels, not a data pointer; charput example had x/y swapped; title
  range corrected to 40-47; dangling TODO removed.
- opcodes_10_19.org: disk@/disk! parameter bullets swapped which
  argument is TOS; disk file is disk.raw; past-EOF reads return stale
  data, not zeros.
- opcodes_30_39.org: fix i2/i3 example results (2 and 3, not 1), fix
  false shr-by-31 corner case, remove stray unclosed #+begin_example,
  correct or/xor TOS labels, note cprt@ port width and zero-extension.
- opcodes_00_09.org: kbd@ writes only the low byte of the pushed cell;
  document host DOS keyboard-buffer drain side effect.
- virtual machine.org: mouse@ row shows deltas; precise opcode count
  (48 slots, 16 unused).
- emulator comments: fix the wrong comments the docs had copied
  (opcode numbers, backwards ">" examples, broken <> formula, kbd@
  "zero-extended" claim, misleading IMUL edx note).

HTML re-exports clean for all 6 changed pages (incremental exporter).
Documentation/opcodes_00_09.org
Documentation/opcodes_10_19.org
Documentation/opcodes_20_29.org
Documentation/opcodes_30_39.org
Documentation/opcodes_40_49.org
Documentation/virtual machine.org
emulator/opcodes_00_09.asm
emulator/opcodes_20_29.asm