Evolve 5.0 - KFORTH Instruction Reference

VOLVE 5.0

KFORTH INSTRUCTIONS

call
if
ifelse
?loop
?exit
pop
dup
swap
over
rot
?dup
-rot
2swap
2over
2dup
2pop
nip
tuck
1+
1-
2+
2-
2/
2*
abs
sqrt
+
-
*
/
mod
/mod
negate
2negate
<<
>>
=
<>
<
>
<=
>=
0=
or
and
not
invert
xor
min
max
CB
R0
R1
R2
R3
R4
R5
R6
R7
R8
R9
R0!
R1!
R2!
R3!
R4!
R5!
R6!
R7!
R8!
R9!
SIGN
PACK2
UNPACK2
MAX_INT
MIN_INT
HALT
NOP
R0++
--R0
R1++
--R1
R2++
--R2
R3++
--R3
R4++
--R4
R5++
--R5
R6++
--R6
R7++
--R7
R8++
--R8
R9++
--R9
PEEK
POKE
CBLEN
DSLEN
CSLEN
TRAP1
TRAP2
TRAP3
TRAP4
TRAP5
TRAP6
TRAP7
TRAP8
TRAP9
NUMBER
NUMBER!
?NUMBER!
OPCODE
OPCODE!
OPCODE'

KFORTH INSTRUCTION REFERENCE

Here are all the core KFORTH instructions. (the instructions that control organisms/cells are listed here).

The USAGE column uses forth notation to document these instructions. This notation attempts to show the data stack before and after the call to the instruction. For example,

(a b c -- n )

The stuff before -- is the state of the data stack before calling the instruction. And the stuff after -- is state of the data stack AFTER this instruction finishes.

In this example, the instruction takes three arguments a, b, and c. After the instruction executes those three arguments are replaced with a single value n (which is the result).

INSTRUCTION	USAGE	DESCRIPTION
call	( code-block -- )	Subroutine call to another code block. The code block number is given by 'code-block' on top of the data stack. If code block is invalid, the request is ignored. In disassembly row123 is code-block 123, and so on.
if	( expr code-block -- )	Removes two items from top of stack. If expr is non-zero then code-block is called. Otherwise, execution continues on the next instruction.
ifelse	( expr true-block false-block -- )	removes three items from top of stack. If expr is non-zero then call true-block, else call false-block.
?loop	( n -- )	Remove 1 item from the stack. If value is non-zero jump to the start of the current code block. Otherwise continue with the next instruction after '?loop'.
?exit	( n -- )	Remove 1 item from the stack. If non-zero then exit current code block.
pop	( n -- )	Remove item from stack and discard it.
dup	( a -- a a )	Duplicate item on top of the stack.
swap	( a b -- b a )	Swap top two elements on the stack.
over	( a b -- a b a )	Copy second item from the stack.
rot	( a b c -- b c a )	Rotate third item to top.
?dup	( n -- n n \| 0 )	Duplicate top element if non-zero.
-rot	( a b c -- c a b )	Rotate top to third position.
2swap	( a b c d -- c d a b )	Swap pairs.
2over	( a b c d -- a b c d a b)	Leapfrog pair.
2dup	( a b -- a b a b )	Dupicate pair.
2pop	( a b -- )	Remove pair.
nip	( a b -- b )	Remove 2nd item from stack.
tuck	( a b -- b a b)	Copy top item to third position.
1+	( n -- n+1 )	Add 1 to the item on top of the stack.
1-	( n -- n-1 )	Subtract 1 from item on top of the stack.
2+	( n -- n+2 )	Add 2 to item on top of the stack
2-	( n -- n-2 )	Subtract 2 from the item on top of the stack.
2/	( n -- n/2 )	Half value.
2*	( n -- n*2 )	Double value.
abs	( n -- abs(n) )	Absolute value of n.
sqrt	( n -- sqrt(n) )	Square root. n must be positive.
+	( a b -- a+b )	Addition top to elements on stack.
-	( a b -- a-b )	Subtraction first item on stack from 2nd.
*	( a b -- a*b )	Multiply.
/	( a b -- a/b )	Divide.
mod	( a b -- a%b )	Modulos.
/mod	( a b -- a%b a/b )	Divide and modulos.
negate	( n -- -n )	negate top item on stack.
2negate	( a b -- -a -b )	negate top two items on stack. (useful for computing a "flee" direction to evade something).
<<	( a b -- a << b )	Left shift a by b bits. Negative b will perform right shift.
>>	( a b -- a >> b )	Right shift a by b bits. Negative b will perform left shift.
=	( a b -- EQ(a,b) )	Equal to.
<>	( a b -- NE(a,b) )	Not equal to.
<	( a b -- LT(a,b) )	Less than.
>	( a b -- GT(a,b) )	Greater than.
<=	( a b -- LE(a,b) )	Less than or equal to.
>=	( a b -- GE(a,b) )	Greater than or equal to.
0=	( n -- EQ(n,0) )	Is element on top of the stack equal to 0?
or	( a b -- a\|b )	Bitwise OR. Can be used as a logical OR operator too, because KFORTH boolean operators return 1 and 0.
and	( a b -- a&b )	Bitwise AND. Can be used a a logical AND operator too, because KFORTH boolean operators return 1 and 0.
not	( n -- !n )	Logical NOT.
invert	( n -- ~n )	Invert bits (Bitwise NOT).
xor	( a b -- a^b )	XOR function.
min	( a b -- min(a,b) )	Minimum value.
max	( a b -- max(a,b) )	Remove 2 items from stack and replace with maximum value.
CB	( -- CB )	Pushes the current code block number on the data stack. Can be used to implement "relative" code block addressing.
R0	( -- R0 )	Pushes register R0 on the data stack
R1	( -- R1 )	Pushes register R1 on the data stack
R2	( -- R2 )	Pushes register R2 on the data stack
R3	( -- R3 )	Pushes register R3 on the data stack
R4	( -- R4 )	Pushes register R4 on the data stack
R5	( -- R5 )	Pushes register R5 on the data stack
R6	( -- R6 )	Pushes register R6 on the data stack
R7	( -- R7 )	Pushes register R7 on the data stack
R8	( -- R8 )	Pushes register R8 on the data stack
R9	( -- R9 )	Pushes register R9 on the data stack
R0!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R0
R1!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R1
R2!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R2
R3!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R3
R4!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R4
R5!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R5
R6!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R6
R7!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R7
R8!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R8
R9!	( val -- )	Removes 1 item 'val' from the data stack and stores 'val' into register R9
SIGN	( n -- SIGN(n) )	Compute sign of 'n'. If n is negative, SIGN will return -1. if n is greater than 0, SIGN will return 1. If n is 0, SIGN will return 0.
PACK2	( a b -- n )	Combine two 8-bit integers 'a' and 'b' into a single 16-bit value 'n'.
UNPACK2	( n -- a b )	Extract two 8-bit integers 'a' and 'b' from the 16-bit value 'n'.
MAX_INT	( -- max_int )	Push the maximum signed integer on the data stack. Which is 32767.
MIN_INT	( -- min_int )	Push the minimum signed integer on the data stack. Which is -32768.
HALT	( -- )	End the current program. This means the cell will be flagged as Dead (shows up red).
NOP	( -- )	No operation. Do nothing.
R0++	(-- R0++)	Post Increment the register R0. Returns the value of R0 before it has been incremented.
--R0	(-- --R0)	Decrements R0 by 1, and returns it.
R1++	(-- r1++)	Post Increment the register R1. Returns the value of R1 before it has been incremented.
--R1	(-- --r1)	Decrements R1 by 1, and returns it.
R2++	(-- r2++)	Post Increment the register R2. Returns the value of R2 before it has been incremented.
--R2	(-- --r2)	Decrements R2 by 1, and returns it.
R3++	(-- r3++)	Post Increment the register R3. Returns the value of R3 before it has been incremented.
--R3	(-- --r3)	Decrements R3 by 1, and returns it.
R4++	(-- r4++)	Post Increment the register R4. Returns the value of R4 before it has been incremented.
--R4	(-- --r4)	Decrements R4 by 1, and returns it.
R5++	(-- r5++)	Post Increment the register R5. Returns the value of R5 before it has been incremented.
--R5	(-- --r5)	Decrements R5 by 1, and returns it.
R6++	(-- r6++)	Post Increment the register R6. Returns the value of R6 before it has been incremented.
--R6	(-- --r6)	Decrements R6 by 1, and returns it.
R7++	(-- r7++)	Post Increment the register R7. Returns the value of R7 before it has been incremented.
--R7	(-- --r7)	Decrements R7 by 1, and returns it.
R8++	(-- r8++)	Post Increment the register R8. Returns the value of R8 before it has been incremented.
--R8	(-- --r8)	Decrements R8 by 1, and returns it.
R9++	(-- r9++)	Post Increment the register R9. Returns the value of R9 before it has been incremented.
--R9	(-- --r9)	Decrements R9 by 1, and returns it.
PEEK	(n -- value)	Get the n'th data stack item from bottom, or -n'th item from top. If 'n' is invalid (too big or too small), then return -1. If 'n' is valid and positive then return the n'th item from the bottom (0-based). If 'n' is valid and negative then return the n'th item from the top (-1-based). 'n' is relative to the state of the stack after 'n' has been removed by this instruction.
POKE	(value n --)	If 'n' is invalid (negative or too big), then don't set anything. If 'n' is valid and positive then set the n'th item from the bottom (0-based). If 'n' is valid and negative then set the n'th item from the top (-1-based). 'n' is relative to the state of the stack after 'n' and 'value' have been removed by this instruction.
CBLEN	(cb -- len)	Returns the length of a code block. The code block number to use is given by 'cb'.
DSLEN	( -- len)	This instruction returns how many data values are pushed onto the data stack (excludeding 'len').
CSLEN	( -- len)	Length of the call stack.
TRAP1	( -- )	Call code block 1. This allows un-protected code to call into protected code.
TRAP2	( -- )	Call code block 2. This allows un-protected code to call into protected code.
TRAP3	( -- )	Call code block 3. This allows un-protected code to call into protected code.
TRAP4	( -- )	Call code block 4. This allows un-protected code to call into protected code.
TRAP5	( -- )	Call code block 5. This allows un-protected code to call into protected code.
TRAP6	( -- )	Call code block 6. This allows un-protected code to call into protected code.
TRAP7	( -- )	Call code block 7. This allows un-protected code to call into protected code.
TRAP8	( -- )	Call code block 8. This allows un-protected code to call into protected code.
TRAP9	( -- )	Call code block 9. This allows un-protected code to call into protected code.
NUMBER	(cb pc -- value)	Fetch a number from program memory and push that value onto the data stack. This retrieves a value from the program memory. 'cb' is a code block number, 'pc' is the offset from the start of the code block. Note: KFORTH program literals are signed 15-bit integers.
NUMBER!	(value cb pc -- )	Write 'value' to program memory at location (cb, pc). 'cb' is the code block number, and 'pc' is the offset into the code block. KFORTH program literals are signed 15-bit integers, therefore 'value' will be reduced to 15-bits. The 15-bit value range is: -16384 and 16383.
?NUMBER!	(value cb pc -- value\|0)	Test (and then set) the KFORTH program memory location given by (cb, pc). If it is zero then update it to contain 'value' and return value. Else return 0 and leave location (cb,pc) unchanged. 'cb' is the code block number, and 'pc' is the offset into the code block. KFORTH program literals are signed 15-bit integers. 'value' will be reduced to 15-bits. The 15-bit value range is: -16384 and 16383.
OPCODE	(cb pc -- opcode)	Fetch an opcode from program memory and push its numeric code onto the data stack. This retrieves the opcode from the program memory, 'cb' is a code block number, 'pc' is the offset from the start of the code block. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.
OPCODE!	(opcode cb pc -- )	Write an opcode to program memory. This instruction writes code. it writes 'opcode' to program memory, 'cb' is a code block number, 'pc' is the offset from the start of the code block. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.
OPCODE'	( -- opcode )	Treat the instruction following the OPCODE' instruction as a literal. Do not execute the next instruction, rather return its opcode. Execution continues with the instruction following the next instruction. The next instructions opcode value will be pushed on to the data stack. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.

call

Usage: ( code-block -- )

call subroutine given by 'code-block'

Subroutine call to another code block. The code block number is given by 'code-block' on top of the data stack. If code block is invalid, the request is ignored. In disassembly row123 is code-block 123, and so on.

Un-protected code cannot call to protected code blocks.
This instruction is a no-op if 'code-block' is invalid.

RETURNS:

ENERGY:

if

Usage: ( expr code-block -- )

call code block if condition

Removes two items from top of stack. If expr is non-zero then code-block is called. Otherwise, execution continues on the next instruction.

Un-protected code cannot call to protected code blocks.
This instruction is a no-op if 'code-block' is invalid.

RETURNS:

ENERGY:

ifelse

Usage: ( expr true-block false-block -- )

call code blocks if condition

removes three items from top of stack. If expr is non-zero then call true-block, else call false-block.

Un-protected code cannot call to protected code blocks.
This instruction is a no-op if calling an invalid 'true-block' or 'false-block'.

RETURNS:

ENERGY:

?loop

Usage: ( n -- )

loop back to start of code block if true

Remove 1 item from the stack. If value is non-zero jump to the start of the current code block. Otherwise continue with the next instruction after '?loop'.

RETURNS:

ENERGY:

?exit

Usage: ( n -- )

exit code block if true

Remove 1 item from the stack. If non-zero then exit current code block.

RETURNS:

ENERGY:

pop

Usage: ( n -- )

Remove item from stack and discard it.

RETURNS:

ENERGY:

dup

Usage: ( a -- a a )

Duplicate item on top of the stack.

RETURNS:

ENERGY:

swap

Usage: ( a b -- b a )

Swap top two elements on the stack.

RETURNS:

ENERGY:

over

Usage: ( a b -- a b a )

Copy second item from the stack.

RETURNS:

ENERGY:

rot

Usage: ( a b c -- b c a )

Rotate third item to top.

RETURNS:

ENERGY:

?dup

Usage: ( n -- n n | 0 )

Duplicate top element if non-zero.

RETURNS:

ENERGY:

-rot

Usage: ( a b c -- c a b )

Rotate top to third position.

RETURNS:

ENERGY:

2swap

Usage: ( a b c d -- c d a b )

Swap pairs.

RETURNS:

ENERGY:

2over

Usage: ( a b c d -- a b c d a b)

Leapfrog pair.

RETURNS:

ENERGY:

2dup

Usage: ( a b -- a b a b )

Dupicate pair.

RETURNS:

ENERGY:

2pop

Usage: ( a b -- )

Remove pair.

RETURNS:

ENERGY:

nip

Usage: ( a b -- b )

Remove 2nd item from stack.

RETURNS:

ENERGY:

tuck

Usage: ( a b -- b a b)

Copy top item to third position.

RETURNS:

ENERGY:

1+

Usage: ( n -- n+1 )

Add 1 to the item on top of the stack.

RETURNS:

ENERGY:

1-

Usage: ( n -- n-1 )

Subtract 1 from item on top of the stack.

RETURNS:

ENERGY:

2+

Usage: ( n -- n+2 )

Add 2 to item on top of the stack

RETURNS:

ENERGY:

2-

Usage: ( n -- n-2 )

Subtract 2 from the item on top of the stack.

RETURNS:

ENERGY:

2/

Usage: ( n -- n/2 )

Half value.

RETURNS:

ENERGY:

2*

Usage: ( n -- n*2 )

Double value.

RETURNS:

ENERGY:

abs

Usage: ( n -- abs(n) )

Absolute value of n.

RETURNS:

ENERGY:

sqrt

Usage: ( n -- sqrt(n) )

Square root. n must be positive.

RETURNS:

ENERGY:

+

Usage: ( a b -- a+b )

Addition top to elements on stack.

RETURNS:

ENERGY:

-

Usage: ( a b -- a-b )

Subtraction first item on stack from 2nd.

RETURNS:

ENERGY:

*

Usage: ( a b -- a*b )

Multiply.

RETURNS:

ENERGY:

/

Usage: ( a b -- a/b )

Divide.

RETURNS:

ENERGY:

mod

Usage: ( a b -- a%b )

Modulos.

RETURNS:

ENERGY:

/mod

Usage: ( a b -- a%b a/b )

Divide and modulos.

RETURNS:

ENERGY:

negate

Usage: ( n -- -n )

negate top item on stack.

RETURNS:

ENERGY:

2negate

Usage: ( a b -- -a -b )

negate top two items on stack.

negate top two items on stack. (useful for computing a "flee" direction to evade something).

RETURNS:

ENERGY:

<<

Usage: ( a b -- a << b )

left shift

Left shift a by b bits. Negative b will perform right shift.

RETURNS:

ENERGY:

>>

Usage: ( a b -- a >> b )

right shift

Right shift a by b bits. Negative b will perform left shift.

RETURNS:

ENERGY:

=

Usage: ( a b -- EQ(a,b) )

Equal to.

RETURNS:

ENERGY:

<>

Usage: ( a b -- NE(a,b) )

Not equal to.

RETURNS:

ENERGY:

<

Usage: ( a b -- LT(a,b) )

Less than.

RETURNS:

ENERGY:

>

Usage: ( a b -- GT(a,b) )

Greater than.

RETURNS:

ENERGY:

<=

Usage: ( a b -- LE(a,b) )

Less than or equal to.

RETURNS:

ENERGY:

>=

Usage: ( a b -- GE(a,b) )

Greater than or equal to.

RETURNS:

ENERGY:

0=

Usage: ( n -- EQ(n,0) )

Is element on top of the stack equal to 0?

RETURNS:

ENERGY:

or

Usage: ( a b -- a|b )

Bitwise OR

Bitwise OR. Can be used as a logical OR operator too, because KFORTH boolean operators return 1 and 0.

RETURNS:

ENERGY:

and

Usage: ( a b -- a&b )

Bitwise AND

Bitwise AND. Can be used a a logical AND operator too, because KFORTH boolean operators return 1 and 0.

RETURNS:

ENERGY:

not

Usage: ( n -- !n )

Logical NOT.

RETURNS:

ENERGY:

invert

Usage: ( n -- ~n )

Invert bits (Bitwise NOT).

RETURNS:

ENERGY:

xor

Usage: ( a b -- a^b )

XOR function.

RETURNS:

ENERGY:

min

Usage: ( a b -- min(a,b) )

Minimum value.

RETURNS:

ENERGY:

max

Usage: ( a b -- max(a,b) )

maximum of top 2 items

Remove 2 items from stack and replace with maximum value.

RETURNS:

ENERGY:

CB

Usage: ( -- CB )

current code block executing

Pushes the current code block number on the data stack. Can be used to implement "relative" code block addressing.

RETURNS:

ENERGY:

R0

Usage: ( -- R0 )

Pushes register R0 on the data stack

RETURNS:

ENERGY:

R1

Usage: ( -- R1 )

Pushes register R1 on the data stack

RETURNS:

ENERGY:

R2

Usage: ( -- R2 )

Pushes register R2 on the data stack

RETURNS:

ENERGY:

R3

Usage: ( -- R3 )

Pushes register R3 on the data stack

RETURNS:

ENERGY:

R4

Usage: ( -- R4 )

Pushes register R4 on the data stack

RETURNS:

ENERGY:

R5

Usage: ( -- R5 )

Pushes register R5 on the data stack

RETURNS:

ENERGY:

R6

Usage: ( -- R6 )

Pushes register R6 on the data stack

RETURNS:

ENERGY:

R7

Usage: ( -- R7 )

Pushes register R7 on the data stack

RETURNS:

ENERGY:

R8

Usage: ( -- R8 )

Pushes register R8 on the data stack

RETURNS:

ENERGY:

R9

Usage: ( -- R9 )

Pushes register R9 on the data stack

RETURNS:

ENERGY:

R0!

Usage: ( val -- )

write to register 0

Removes 1 item 'val' from the data stack and stores 'val' into register R0

RETURNS:

ENERGY:

R1!

Usage: ( val -- )

write to register 1

Removes 1 item 'val' from the data stack and stores 'val' into register R1

RETURNS:

ENERGY:

R2!

Usage: ( val -- )

write to register 2

Removes 1 item 'val' from the data stack and stores 'val' into register R2

RETURNS:

ENERGY:

R3!

Usage: ( val -- )

write to register 3

Removes 1 item 'val' from the data stack and stores 'val' into register R3

RETURNS:

ENERGY:

R4!

Usage: ( val -- )

write to register 4

Removes 1 item 'val' from the data stack and stores 'val' into register R4

RETURNS:

ENERGY:

R5!

Usage: ( val -- )

write to register 5

Removes 1 item 'val' from the data stack and stores 'val' into register R5

RETURNS:

ENERGY:

R6!

Usage: ( val -- )

write to register 6

Removes 1 item 'val' from the data stack and stores 'val' into register R6

RETURNS:

ENERGY:

R7!

Usage: ( val -- )

write to register 7

Removes 1 item 'val' from the data stack and stores 'val' into register R7

RETURNS:

ENERGY:

R8!

Usage: ( val -- )

write to register 8

Removes 1 item 'val' from the data stack and stores 'val' into register R8

RETURNS:

ENERGY:

R9!

Usage: ( val -- )

write to register 9

Removes 1 item 'val' from the data stack and stores 'val' into register R9

RETURNS:

ENERGY:

SIGN

Usage: ( n -- SIGN(n) )

sign

Compute sign of 'n'. If n is negative, SIGN will return -1. if n is greater than 0, SIGN will return 1. If n is 0, SIGN will return 0.

RETURNS:

ENERGY:

PACK2

Usage: ( a b -- n )

combine 2 8-bit integers

Combine two 8-bit integers 'a' and 'b' into a single 16-bit value 'n'.

RETURNS:

ENERGY:

UNPACK2

Usage: ( n -- a b )

unpack 2 8-bit integers

Extract two 8-bit integers 'a' and 'b' from the 16-bit value 'n'.

RETURNS:

ENERGY:

MAX_INT

Usage: ( -- max_int )

maximum integer

Push the maximum signed integer on the data stack. Which is 32767.

RETURNS:

ENERGY:

MIN_INT

Usage: ( -- min_int )

minimum integer

Push the minimum signed integer on the data stack. Which is -32768.

RETURNS:

ENERGY:

HALT

Usage: ( -- )

end the current program

End the current program. This means the cell will be flagged as Dead (shows up red).

RETURNS:

ENERGY:

NOP

Usage: ( -- )

no operation

No operation. Do nothing.

RETURNS:

ENERGY:

R0++

Usage: (-- R0++)

post increment R0

Post Increment the register R0. Returns the value of R0 before it has been incremented.

RETURNS: The value of R0 before incrementing it by 1.

ENERGY:

--R0

Usage: (-- --R0)

decrements R0 by 1, and returns it

Decrements R0 by 1, and returns it.

RETURNS: The value of R0 after decrementing it.

ENERGY:

R1++

Usage: (-- r1++)

post increment R1

Post Increment the register R1. Returns the value of R1 before it has been incremented.

RETURNS: The value of R1 before incrementing it by 1.

ENERGY:

--R1

Usage: (-- --r1)

decrements R1 by 1, and returns it

Decrements R1 by 1, and returns it.

RETURNS: The value of R1 after decrementing it.

ENERGY:

R2++

Usage: (-- r2++)

post increment R2

Post Increment the register R2. Returns the value of R2 before it has been incremented.

RETURNS: The value of R2 before incrementing it by 1.

ENERGY:

--R2

Usage: (-- --r2)

decrements R2 by 1, and returns it

Decrements R2 by 1, and returns it.

RETURNS: The value of R2 after decrementing it.

ENERGY:

R3++

Usage: (-- r3++)

post increment R3

Post Increment the register R3. Returns the value of R3 before it has been incremented.

RETURNS: The value of R3 before incrementing it by 1.

ENERGY:

--R3

Usage: (-- --r3)

decrements R3 by 1, and returns it

Decrements R3 by 1, and returns it.

RETURNS: The value of R3 after decrementing it.

ENERGY:

R4++

Usage: (-- r4++)

post increment R4

Post Increment the register R4. Returns the value of R4 before it has been incremented.

RETURNS: The value of R4 before incrementing it by 1.

ENERGY:

--R4

Usage: (-- --r4)

decrements R4 by 1, and returns it

Decrements R4 by 1, and returns it.

RETURNS: The value of R4 after decrementing it.

ENERGY:

R5++

Usage: (-- r5++)

post increment R5

Post Increment the register R5. Returns the value of R5 before it has been incremented.

RETURNS: The value of R5 before incrementing it by 1.

ENERGY:

--R5

Usage: (-- --r5)

decrements R5 by 1, and returns it

Decrements R5 by 1, and returns it.

RETURNS: The value of R5 after decrementing it.

ENERGY:

R6++

Usage: (-- r6++)

post increment R6

Post Increment the register R6. Returns the value of R6 before it has been incremented.

RETURNS: The value of R6 before incrementing it by 1.

ENERGY:

--R6

Usage: (-- --r6)

decrements R6 by 1, and returns it

Decrements R6 by 1, and returns it.

RETURNS: The value of R6 after decrementing it.

ENERGY:

R7++

Usage: (-- r7++)

post increment R7

Post Increment the register R7. Returns the value of R7 before it has been incremented.

RETURNS: The value of R7 before incrementing it by 1.

ENERGY:

--R7

Usage: (-- --r7)

decrements R7 by 1, and returns it

Decrements R7 by 1, and returns it.

RETURNS: The value of R7 after decrementing it.

ENERGY:

R8++

Usage: (-- r8++)

post increment R8

Post Increment the register R8. Returns the value of R8 before it has been incremented.

RETURNS: The value of R8 before incrementing it by 1.

ENERGY:

--R8

Usage: (-- --r8)

decrements R8 by 1, and returns it

Decrements R8 by 1, and returns it.

RETURNS: The value of R8 after decrementing it.

ENERGY:

R9++

Usage: (-- r9++)

post increment R9

Post Increment the register R9. Returns the value of R9 before it has been incremented.

RETURNS: The value of R9 before incrementing it by 1.

ENERGY:

--R9

Usage: (-- --r9)

decrements R9 by 1, and returns it

Decrements R9 by 1, and returns it.

RETURNS: The value of R9 after decrementing it.

ENERGY:

PEEK

Usage: (n -- value)

get the n'th data stack item from bottom, or -n'th item from top

Get the n'th data stack item from bottom, or -n'th item from top. If 'n' is invalid (too big or too small), then return -1. If 'n' is valid and positive then return the n'th item from the bottom (0-based). If 'n' is valid and negative then return the n'th item from the top (-1-based). 'n' is relative to the state of the stack after 'n' has been removed by this instruction.

The only valid positive values if 'n' are: 0 up to the current stack size minus 1. 0 <= n < stack-size-1.

The valid negative values if 'n' are: -1 down to the minus current stack size. -(stack-size) <= n <= -1.

RETURNS: Returns the value of n'th stack item. If 'n' is invalid (negative or too big), then return -1. If 'n' is valid and positive then return the n'th item from the bottom (0-based). If 'n' is valid and negative then return the n'th item from the top (-1-based).

ENERGY:

POKE

Usage: (value n --)

set the n'th data stack item from bottom, or -n'th item from top

If 'n' is invalid (negative or too big), then don't set anything. If 'n' is valid and positive then set the n'th item from the bottom (0-based). If 'n' is valid and negative then set the n'th item from the top (-1-based). 'n' is relative to the state of the stack after 'n' and 'value' have been removed by this instruction.

The only valid positive values if 'n' are: 0 up to the current stack size minus 1. 0 <= n < stack-size-1.

The valid negative values if 'n' are: -1 down to the minus current stack size. -(stack-size) <= n <= -1.

RETURNS: Returns nothing.

ENERGY:

CBLEN

Usage: (cb -- len)

return the length of codeblock 'cb'

Returns the length of a code block. The code block number to use is given by 'cb'.

Un-protected code cannot query the length of a protected code block. returns -1

RETURNS:Returns length of code block. -1 is returned if the code block is invalid.

ENERGY:

DSLEN

Usage: ( -- len)

return the length of data stack

This instruction returns how many data values are pushed onto the data stack (excludeding 'len').

RETURNS: Returns length of data stack (before the 'len' was pushed).

ENERGY:

CSLEN

Usage: ( -- len)

return the length of call stack

Length of the call stack.

RETURNS: returns how many items are pushed on the call stack.

ENERGY:

TRAP1

Usage: ( -- )

call to code block 1

Call code block 1. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP2

Usage: ( -- )

call to code block 2

Call code block 2. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP3

Usage: ( -- )

call to code block 3

Call code block 3. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP4

Usage: ( -- )

call to code block 4

Call code block 4. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP5

Usage: ( -- )

call to code block 5

Call code block 5. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP6

Usage: ( -- )

call to code block 6

Call code block 6. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP7

Usage: ( -- )

call to code block 7

Call code block 7. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP8

Usage: ( -- )

call to code block 8

Call code block 8. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

TRAP9

Usage: ( -- )

call to code block 9

Call code block 9. This allows un-protected code to call into protected code.

RETURNS:

ENERGY:

NUMBER

Usage: (cb pc -- value)

read number from program memory

Fetch a number from program memory and push that value onto the data stack. This retrieves a value from the program memory. 'cb' is a code block number, 'pc' is the offset from the start of the code block. Note: KFORTH program literals are signed 15-bit integers.

Un-protected code cannot retrieve a number from a protected code block. -1

RETURNS:

-1 is returned if cb is invalid
-2 is returned if pc is invalid
-3 is returned if (cb,pc) contains opcode
else the 15-bit signed kforth program literal is returned. 'value' will be between -16384 and 16383.

ENERGY:

NUMBER!

Usage: (value cb pc -- )

write number to program memory

Write 'value' to program memory at location (cb, pc). 'cb' is the code block number, and 'pc' is the offset into the code block. KFORTH program literals are signed 15-bit integers, therefore 'value' will be reduced to 15-bits. The 15-bit value range is: -16384 and 16383.

Un-protected code cannot write a number to a protected code block.
'value' is reduced to 15-bits by ignoring its top bit.

RETURNS:

ENERGY:

?NUMBER!

Usage: (value cb pc -- value|0)

test and set a number to program memory

Test (and then set) the KFORTH program memory location given by (cb, pc). If it is zero then update it to contain 'value' and return value. Else return 0 and leave location (cb,pc) unchanged. 'cb' is the code block number, and 'pc' is the offset into the code block. KFORTH program literals are signed 15-bit integers. 'value' will be reduced to 15-bits. The 15-bit value range is: -16384 and 16383.

Un-protected code cannot read/write a number to a protected code block. returns 0.
'value' is reduced to 15-bits by ignoring its top bit.
if this location (cb,pc) contains opcode, return 0

RETURNS:

0 - if the variable was non-zero.
value - if the variable was zero, and we updated it to be 'value'.

ENERGY:

OPCODE

Usage: (cb pc -- opcode)

read opcode from program memory

Fetch an opcode from program memory and push its numeric code onto the data stack. This retrieves the opcode from the program memory, 'cb' is a code block number, 'pc' is the offset from the start of the code block. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.

Un-protected code cannot retrieve an opcode from a protected code block. Returns -1
Un-protected code cannot retrieve a protected instruction. Returns -4. This can happen if the un-protected code was seeded with protected instructions.

RETURNS:

-1 is returned if cb is invalid
-2 is returned if pc is invalid
-3 is returned if (cb,pc) contains number
-4 is returned if (cb,pc) contains a protected instruction
else the numeric code for the opcode is returned. This number is a small value between 0 and ~250.

ENERGY:

OPCODE!

Usage: (opcode cb pc -- )

write opcode to program memory

Write an opcode to program memory. This instruction writes code. it writes 'opcode' to program memory, 'cb' is a code block number, 'pc' is the offset from the start of the code block. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.

Un-protected code cannot write an opcode to a protected code block.
Un-protected code cannot write a numeric code corresponding to a protected instruction
cb must be valid
pc must valid
opcode must be a valid numeric code to a defined instruction

RETURNS:

ENERGY:

OPCODE'

Usage: ( -- opcode )

quote the next instruction

Treat the instruction following the OPCODE' instruction as a literal. Do not execute the next instruction, rather return its opcode. Execution continues with the instruction following the next instruction. The next instructions opcode value will be pushed on to the data stack. Opcodes are small integers between 0 and ~250. For example the numeric code for the instruction '+' might be 75.

Un-protected code cannot return the opcode for a protected instruction
there must be a next instruction

RETURNS:

-2 is returned if no next instruction
-3 is returned if next instruction contains a number
-4 is returned if next instruction is a protected instruction, when called from un-protected code.
else the numeric code for the opcode is returned. This number is a small value between 0 and ~250.

ENERGY: