Fifth - virtual machine opcodes 20 – 29

Reads a 32-bit value from the specified memory address and replaces the address with the fetched value on the data stack. This is the primary operation for reading data from memory.

The operation performs virtual address translation:

1. Takes virtual address from top of data stack
2. Converts to physical address by adding xms_addr
3. Reads 32-bit value from physical memory
4. Replaces address with value on stack

• Reading variables and data structures from memory
• Accessing array elements
• Loading values for computation
• Implementing high-level words that need memory access
• Reading hardware registers (when mapped to memory)

Read a value from address 0x1000:

03 00 10 00 00  ; num 0x1000 - push address 0x1000
14              ; @ - read 32-bit value from 0x1000
                ; stack now contains the value from address 0x1000

In Fifth source code:

0x1000 @        \ read 32-bit value from address 0x1000

• This is the 32-bit equivalent of c@ (opcode 16)
• Virtual address translation provides memory management
• Reads full 32-bit words, not bytes
• The address is consumed and replaced with the value
• No bounds checking is performed

Stores a 32-bit value to the specified memory address. Both the value and address are consumed from the data stack, leaving a clean stack.

The operation performs virtual address translation:

1. Takes address from top of stack
2. Takes value to store from second on stack
3. Converts virtual address to physical address
4. Stores 32-bit value to physical memory
5. Removes both arguments from stack

• Writing variables and data structures to memory
• Storing array elements
• Saving computation results
• Implementing high-level words that modify memory
• Writing to hardware registers (when mapped to memory)

Store value 0x12345678 to address 0x1000:

03 78 56 34 12  ; num 0x12345678 - push value to store
03 00 10 00 00  ; num 0x1000 - push destination address
15              ; ! - store value to address
                ; stack is now empty

In Fifth source code:

0x12345678 0x1000 !  \ store 0x12345678 at address 0x1000

• This is the 32-bit equivalent of c! (opcode 17)
• Virtual address translation provides memory protection
• Order is value then addr (Forth standard: value to address)
• Both arguments are consumed (stack cleaned up)
• No bounds checking is performed
• Overwrites existing data at the target address

Duplicates the second item on the data stack, placing a copy on top. This allows access to the second item without disturbing the top item.

The operation preserves the original order while adding a copy:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ n1 n2 n1 ]  (new n1 = TOS)

• Preserving values while using the top item
• Accessing the second item when you need to keep the top
• Setting up multiple uses of the same value
• Implementing arithmetic operations that need the original value
• Creating stack patterns for complex operations

Duplicate the second item:

03 01 00 00 00  ; num 1    - stack: [ 1 ]
03 02 00 00 00  ; num 2    - stack: [ 1 2 ]
16              ; over     - stack: [ 1 2 1 ]

In Fifth source code:

1 2 over        \ stack: 1 2 1

• Essential for preserving values while using the top item
• More efficient than dup+swap+drop combination
• Increases stack depth by 1
• Often paired with arithmetic operations
• Fundamental stack manipulation word

Exchanges the top two values on the data stack. This is essential for reordering arguments when the natural stack order doesn't match the required order for operations.

The operation reverses the order of the top two items:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ n2 n1 ]    (n1 = TOS, n2 = second)

• Reordering arguments for arithmetic operations
• Fixing stack order after computations
• Implementing algorithms that need specific operand order
• Exchanging values in sorting algorithms
• Correcting stack order for function calls

Exchange the top two values:

03 01 00 00 00  ; num 1    - stack: [ 1 ]
03 02 00 00 00  ; num 2    - stack: [ 1 2 ]
17              ; swap     - stack: [ 2 1 ]

In Fifth source code:

1 2 swap        \ stack: 2 1

• Fundamental stack manipulation operation
• Used extensively for argument reordering
• More efficient than multiple push/pop operations
• Stack depth remains unchanged
• Essential for correct operand order in arithmetic

Adds the top two values on the data stack, replacing them with the sum. This is a fundamental arithmetic operation for mathematical computations.

The operation performs unsigned 32-bit addition:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ sum ]      (sum = n1 + n2)

• Basic arithmetic calculations
• Computing sums and totals
• Pointer arithmetic
• Incrementing values by arbitrary amounts
• Mathematical expressions and formulas

Add two numbers:

03 05 00 00 00  ; num 5    - stack: [ 5 ]
03 03 00 00 00  ; num 3    - stack: [ 5 3 ]
18              ; +        - stack: [ 8 ]

In Fifth source code:

5 3 +           \ result: 8

• Performs unsigned 32-bit addition
• Overflow wraps around modulo 2^32
• Operates in place for efficiency (no extra stack slot needed)
• Reduces stack depth by 1
• Commutative operation (a + b = b + a)

• 0xFFFFFFFF + 1 = 0 (wrap around)
• Any number + 0 = same number
• Large additions may overflow

Subtracts the top value from the second value on the data stack. The result replaces both values. This operation is not commutative - order matters.

The operation performs unsigned 32-bit subtraction:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ diff ]     (diff = n1 - n2)

• Computing differences between values
• Decrementing by arbitrary amounts
• Distance calculations
• Mathematical expressions requiring subtraction
• Reverse arithmetic operations

Subtract two numbers:

03 0A 00 00 00  ; num 10   - stack: [ 10 ]
03 03 00 00 00  ; num 3    - stack: [ 10 3 ]
19              ; -        - stack: [ 7 ]

In Fifth source code:

10 3 -          \ result: 7 (10 - 3)

• Performs unsigned 32-bit subtraction
• Underflow wraps around modulo 2^32
• Operates in place for efficiency
• Reduces stack depth by 1
• NOT commutative (a - b ≠ b - a)
• Order: second item minus top item

• 0 - 1 = 0xFFFFFFFF (wrap around)
• Any number - 0 = same number
• n - n = 0 for any n

Multiplies the top two values on the data stack using signed 32-bit multiplication. The result is the low 32 bits of the product.

The operation performs signed 32-bit multiplication:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ product ]  (product = n1 * n2)

• Multiplication operations
• Area calculations
• Scaling values
• Mathematical formulas
• Computing products and multiples

Multiply two numbers:

03 05 00 00 00  ; num 5    - stack: [ 5 ]
03 03 00 00 00  ; num 3    - stack: [ 5 3 ]
1A              ; *        - stack: [ 15 ]

In Fifth source code:

5 3 *           \ result: 15

• Uses IMUL instruction (signed multiplication)
• Result is low 32 bits only (high bits in edx are discarded)
• Handles both positive and negative numbers correctly
• Overflow behavior: result wraps around modulo 2^32
• Reduces stack depth by 1
• Commutative operation (a * b = b * a)

• 0 * anything = 0
• 1 * anything = anything
• (-1) * (-1) = 1
• Large products may overflow (wrap around)

Divides the second value by the top value using signed 32-bit division. Returns the quotient only (remainder is discarded).

The operation performs signed 32-bit division:

Before: [ n1 n2 ]    (n2 = divisor = TOS, n1 = dividend = second)
After:  [ quotient ] (quotient = n1 / n2)

• Division operations
• Averaging calculations
• Ratio computations
• Mathematical formulas requiring division
• Splitting quantities into equal parts

Divide two numbers:

03 0F 00 00 00  ; num 15   - stack: [ 15 ]
03 03 00 00 00  ; num 3    - stack: [ 15 3 ]
1B              ; /        - stack: [ 5 ]

In Fifth source code:

15 3 /          \ result: 5 (15 / 3)

• Uses IDIV instruction (signed division)
• Returns quotient only (remainder discarded)
• Handles both positive and negative numbers correctly
• Division by zero causes CPU exception (not handled)
• Reduces stack depth by 1
• NOT commutative (a / b ≠ b / a)
• Order: second item divided by top item

• Division by zero: CPU exception (crash)
• Anything / 1 = anything
• 0 / anything = 0
• Negative division follows standard signed rules

Compares the second value (a) with the top value (b). Returns -1 (true) if a > b, otherwise returns 0 (false). This is a fundamental comparison operation for conditional logic.

The operation performs signed 32-bit comparison:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ flag ]     (flag = -1 if n1 > n2, 0 otherwise)

• -1 = true (all bits set, non-zero)
• 0 = false (zero)

• Conditional branching and logic
• Sorting algorithms
• Range checking
• Decision making in programs
• Implementing high-level comparison words

Compare two numbers:

03 05 00 00 00  ; num 5    - stack: [ 5 ]
03 03 00 00 00  ; num 3    - stack: [ 5 3 ]
1C              ; >        - stack: [ 0 ] (false, 5 is not > 3)

In Fifth source code:

3 5 >           \ result: 0 (false)
5 3 >           \ result: -1 (true)

• Returns -1 for true (all bits set), 0 for false
• Standard Forth truth value convention
• Signed comparison (works for negative numbers)
• Reduces stack depth by 1
• NOT commutative (a > b ≠ b > a)

• Equal values return 0 (false)
• Negative numbers compared correctly
• Works with full 32-bit signed range

Compares the second value (a) with the top value (b). Returns -1 (true) if a < b, otherwise returns 0 (false). This is the complement of the greater than operation and essential for conditional logic.

The operation performs signed 32-bit comparison:

Before: [ n1 n2 ]    (n2 = TOS, n1 = second)
After:  [ flag ]     (flag = -1 if n1 < n2, 0 otherwise)

• -1 = true (all bits set, non-zero)
• 0 = false (zero)

• Conditional branching and logic
• Sorting algorithms
• Range checking
• Decision making in programs
• Implementing high-level comparison words
• Complementary logic to greater than

Compare two numbers:

03 03 00 00 00  ; num 3    - stack: [ 3 ]
03 05 00 00 00  ; num 5    - stack: [ 3 5 ]
1D              ; <        - stack: [ -1 ] (true, 3 < 5)

In Fifth source code:

3 5 <           \ result: -1 (true)
5 3 <           \ result: 0 (false)

• Returns -1 for true (all bits set), 0 for false
• Standard Forth truth value convention
• Signed comparison (works for negative numbers)
• Reduces stack depth by 1
• NOT commutative (a < b ≠ b < a)
• Complementary to > (greater than) operation

• Equal values return 0 (false)
• Negative numbers compared correctly
• Works with full 32-bit signed range
• Relationship to other comparisons: a b < is equivalent to= b a > not

The less than operation is complementary to greater than:

• a b < is equivalent to b a >
• a b < (less than or equal) can be implemented as=: over over < > or
• a b <> (not equal) can be implemented as: over over <> = drop