From: Svjatoslav Agejenko Date: Sun, 11 Oct 2026 07:11:05 +0000 (+0300) Subject: docs: fix opcode table errors, kbd@ byte-store semantics, drop TODOs X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=ea3bb30c8aba8eccf8c9ed276e8b773f3b2af825;p=fifth.git docs: fix opcode table errors, kbd@ byte-store semantics, drop TODOs - virtual machine.org: correct divide stack effect (n1 n2 -- n1/n2, was inverted as n2/n1), fix subtract wording (subtract top item from second), document comparison truth convention (-1 = true, 0 = false, signed) — clears all 4 dangling TODO markers from the opcode table. - opcodes_00_09.org: document that kbd@ writes only the low byte of the pushed cell (upper bytes are stale stack memory), note the host DOS/BIOS keyboard-buffer drain side effect, clarify num advances IP 5 bytes total, state that drop leaves the value in memory, and add the XMS unlock/free step to the halt cleanup list. --- diff --git a/Documentation/opcodes_00_09.org b/Documentation/opcodes_00_09.org index ddc530e..7610959 100644 --- a/Documentation/opcodes_00_09.org +++ b/Documentation/opcodes_00_09.org @@ -105,7 +105,8 @@ to exit the Fifth environment. When executed, the emulator: 1. Restores text video mode (mode 3) 2. Closes the virtual disk file handle 3. Restores the original keyboard interrupt handler -4. Returns control to DOS +4. Unlocks and frees the XMS extended-memory block +5. Returns control to DOS ** When to Use @@ -142,6 +143,11 @@ Reads a keyboard scancode from the internal ring buffer and pushes it onto the data stack. This is a non-blocking operation: if no key is pending, it pushes 0 immediately. +Only the low byte of the pushed stack cell is written; the upper three +bytes keep whatever the stack memory previously held. Read the result +with =c@=-style byte semantics (e.g. mask with =FF and=) before +comparing as a full 32-bit value. + ** Scan Code Behavior The keyboard hardware generates scan codes for every key event: @@ -187,8 +193,10 @@ Basic key reading: ** Return Values -- Returns =0= if no key is available in the buffer -- Returns scancode (1-255) when a key event is pending +- The low byte of the result is =0= if no key is available in the + buffer, or the scancode (1-255) when a key event is pending +- The upper three bytes of the stack cell are undefined (leftover stack + memory) - Each call consumes one scancode from the buffer ** Important Notes @@ -197,6 +205,9 @@ Basic key reading: - Use a keyboard layout file (like =5TH_KBD_US=) to translate scan codes to FSCII characters - The buffer holds 128 scan codes; older codes are overwritten if full +- After reading, one key is also drained from the host DOS/BIOS + keyboard buffer, so keys pressed during emulation do not bleed into + the DOS prompt after exit * 3: num (Push Literal Number) :PROPERTIES: @@ -216,7 +227,8 @@ Basic key reading: Pushes a 32-bit literal value onto the data stack. The value is encoded directly in the instruction stream immediately after the opcode byte. -After execution, the instruction pointer advances by 4 bytes. +After execution, the instruction pointer has advanced 4 bytes past the +literal (5 bytes total including the opcode byte). ** Bytecode Format @@ -576,8 +588,9 @@ drop ; now consume it ** Description -Removes and discards the value from the top of the data stack. The -value is completely lost. +Removes and discards the value from the top of the data stack. Only the +stack pointer moves — the value remains in memory above the new stack +top but is no longer reachable as a stack item. ** When to Use @@ -623,6 +636,7 @@ then ** Important Notes - Reduces stack depth by 1 -- The value is completely lost; ensure you don't need it +- The dropped value stays in memory above the new stack top but is + unreachable; ensure you don't need it - Often paired with =dup= for testing values without consuming them - For discarding two values, use =2drop= (defined in high-level Fifth) diff --git a/Documentation/virtual machine.org b/Documentation/virtual machine.org index 4078fc4..fddabf3 100644 --- a/Documentation/virtual machine.org +++ b/Documentation/virtual machine.org @@ -137,11 +137,11 @@ in FIFTH programming language): | 22 | [[file:opcodes_20_29.org::#opcode-over][over]] | n1 n2 -- n1 n2 n1 | Duplicate second item on data stack | | | 23 | [[file:opcodes_20_29.org::#opcode-swap][swap]] | n1 n2 -- n2 n1 | Swap top two items on data stack | | | 24 | [[file:opcodes_20_29.org::#opcode-add][+]] | n1 n2 -- n1+n2 | Add top two items on data stack | | -| 25 | [[file:opcodes_20_29.org::#opcode-sub][-]] | n1 n2 -- n1-n2 | Subtract second item from top item on data stack | TODO: verify argument order | +| 25 | [[file:opcodes_20_29.org::#opcode-sub][-]] | n1 n2 -- n1-n2 | Subtract top item from second item on data stack | | | 26 | [[file:opcodes_20_29.org::#opcode-mul][*]] | n1 n2 -- n1*n2 | Multiply top two items on data stack | | -| 27 | [[file:opcodes_20_29.org::#opcode-div][/]] | n1 n2 -- n2/n1 | Divide top item by second item on data stack | TODO: verify argument order | -| 28 | [[file:opcodes_20_29.org::#opcode-gt][>]] | n1 n2 -- result | Compare n1 > n2 (returns true, false otherwise) | TODO: document, what true and false means | -| 29 | [[file:opcodes_20_29.org::#opcode-lt][<]] | n1 n2 -- result | Compare n1 < n2 (returns true, false otherwise) | TODO: document, what true and false means | +| 27 | [[file:opcodes_20_29.org::#opcode-div][/]] | n1 n2 -- n1/n2 | Divide second item by top item on data stack | | +| 28 | [[file:opcodes_20_29.org::#opcode-gt][>]] | n1 n2 -- flag | Signed compare n1 > n2; -1 = true, 0 = false | | +| 29 | [[file:opcodes_20_29.org::#opcode-lt][<]] | n1 n2 -- flag | Signed compare n1 < n2; -1 = true, 0 = false | | | 30 | [[file:opcodes_30_39.org::#opcode-not][not]] | n -- ~n | Bitwise NOT on top of data stack | | | 31 | [[file:opcodes_30_39.org::#opcode-i][i]] | -- n | Push top of return stack to data stack | | | 32 | [[file:opcodes_30_39.org::#opcode-cprt-read][cprt@]] | port -- byte | Read byte from hardware I/O port | |