Fifth - virtual machine opcodes 0 – 9

Terminates the emulator process cleanly. This is the only proper way 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

• Terminating the program cleanly and exiting the Fifth environment
• Implementing a "quit" or "bye" command in REPL
• Shutting down after fatal errors

01              ; halt - exit emulator immediately

In Fifth source code, this is typically invoked via the bye word, which compiles to the halt opcode.

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.

The keyboard hardware generates scan codes for every key event:

• Make code: Generated when a key is pressed (values 1-127)
• Break code: Generated when a key is released (make code + 128)

For example:

• Pressing 'A' produces scan code 1E
• Releasing 'A' produces scan code 9E (1E + 80 hex)

• Building interactive programs (games, text editors)
• Reading raw keyboard input without translation to characters
• Detecting key press/release events separately
• Implementing custom keyboard drivers or input handlers

Basic key reading:

02              ; kbd@ - read scancode
                ; data stack now contains: scancode (or 0 if no key)

• Returns 0 if no key is available in the buffer
• Returns scancode (1-255) when a key event is pending
• Each call consumes one scancode from the buffer

• This returns raw scan codes, not ASCII characters
• 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

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.

• Loading constant values for calculations
• Pushing memory addresses onto the stack
• Setting up parameters for function calls
• Initializing counters, pointers, and loop variables

Push the value 0x12345678:

03              ; num opcode
78 56 34 12     ; 32-bit value 0x12345678 (little-endian)
                ; stack now contains: 0x12345678

In Fifth source code, simply write a number:

12345678        ; Compiles to: 03 78 56 34 12
FF              ; Compiles to: 03 FF 00 00 00
1000            ; Compiles to: 03 00 10 00 00

• Numbers in Fifth source code are hexadecimal by default
• Use d. to display numbers in decimal for debugging
• All 32 bits are pushed; high bytes are zero-filled for small values
• The value is stored in little-endian byte order in bytecode

Transfers execution unconditionally to the specified address. The target address is embedded in the instruction stream immediately after the opcode. No return address is saved.

• Creating infinite loops (combined with conditional exits)
• Skipping over code blocks
• Implementing forward jumps in control structures
• Jump tables and dispatch mechanisms

Jump to address 0x1000:

04              ; jmp opcode
00 10 00 00     ; target address 0x1000 (little-endian)
                ; execution continues at 0x1000

Create an infinite loop:

; At address 0x100:
04 00 01 00 00  ; jmp 0x100 - infinite loop

Skip over code:

04 ...          ; jmp to skip_target
...             ; code to skip
; skip_target:

• The address is a virtual address in the VM's address space
• The emulator adds xms_addr to convert to a physical memory address
• No return address is saved; use call for subroutines

Calls a subroutine at the specified address. The return address (the address of the instruction immediately following this call) is saved on the return stack. Use ret (opcode 11) to return to the caller.

• Calling reusable code blocks (functions, procedures)
• Implementing Forth word definitions
• Building modular programs with separate subroutines
• Recursion (with proper stack management)

The return address is the virtual address immediately after the 4-byte argument (i.e., the address of the next instruction).

• The return stack is separate from the data stack
• The return stack is also used by push and pop opcodes
• Always balance call with ret to avoid return stack corruption
• Nesting depth is limited by return stack size

Adds 1 to the value on top of the data stack, modifying it in place. This is a highly efficient single-byte operation.

• Incrementing loop counters
• Advancing pointers through arrays or buffers
• Computing successor values
• Any situation where you need to add exactly 1

Use 1+ instead of 1 + for better code density.

• Modifies the value in place (no additional stack space needed)
• Works identically on signed and unsigned 32-bit values
• For adding larger values, use + (opcode 24)

Subtracts 1 from the value on top of the data stack, modifying it in place. This is a highly efficient single-byte operation.

• Decrementing loop counters
• Moving pointers backward through arrays or buffers
• Computing predecessor values
• Counting down to zero

• Modifies the value in place (no additional stack space needed)
• Works identically on signed and unsigned 32-bit values
• For subtracting larger values, use - (opcode 25)

Duplicates the value on top of the data stack, pushing a copy. The original value remains, and an identical copy is placed on top.

• Preserving a value before consuming operations
• Using the same value multiple times in a calculation
• Displaying values without losing them
• Setting up parameters for operations that consume values

• Increases stack depth by 1
• Often paired with drop to test values without consuming them
• For duplicating the second stack item, use over (opcode 22)

Removes and discards the value from the top of the data stack. The value is completely lost.

• Cleaning up the stack after calculations
• Discarding values that are no longer needed
• Consuming function results you don't need
• Balancing stack operations

• Reduces stack depth by 1
• The value is completely lost; 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)