This is the user manual for the instruction set of the Bedrock computer system.

This document is aimed at people who are learning about or writing programs for the Bedrock system. For people who are implementing the system from scratch, the architecture specification will provide more relevant information.

Overview

The Bedrock processor can perform 32 different operations, each of which can be combined with three mode flags to create one of 256 different instructions. Each instruction is stored as a single byte in memory.

The architecture manual should be read alongside this manual to understand how each instruction interacts with the rest of the system.

Instructions

Each instruction is a single byte that contains three mode flags and an operation. The three highest bits of the instruction represent the mode flags, and the lower five bits represent the operation:

Each operation has a three letter name, and can be suffixed with the r, *, and : characters to set the corresponding mode flags (in that order).

Return mode

When the return mode flag is set (written as r), the working stack and the return stack will be swapped for that instruction. Whenever a byte would be pushed or popped from one stack, it will instead be pushed or popped from the other stack.

Wide mode

When the wide mode flag is set (written as *), the instruction will oeprate on double values instead of byte values. This will only affect variable-width values, those listed in the signature without a trailing . (byte) or * (double) character.

Immediate mode

When the immediate mode flag is set (written as :), the first argument value that would be popped from a stack by the instruction will instead be read from the bytes of program memory that follow the instruction. The program counter will be incremented for each byte read.

Operations

The signature column in the following table shows the values that are read from and written to the working stack by each operation, separated by --. An optional second signature represents the return stack.

Values followed by a . are bytes, values followed by a * are doubles, and values followed by neither have their width determined by the wide mode flag. Values wrapped in square brackets, as is [b*] for the JCS operation, are only conditionally pushed.

See Appendix A: Expanded reference for a table listing the signatures of all 256 instruction variants.

Stack operations

The stack operations will add, remove, transfer, and permute values on the stacks.

HLT

The HLT operation halts the Bedrock processor, terminating the current program. If any of the mode flags are set, it will do nothing. It does not affect the stacks.

Each byte of memory outside of the loaded program is set to 00 (the value of the HLT instruction), so jumping outside of the program will immediately terminate the system.

The names of the variants of this operation use a different scheme to every other operation. The immediate-mode variant has the name NOP (no operation). It has no effect on the system, and can be used as a placeholder instruction. The six remaining variants are named DB1, DB2, DB3, DB4, DB5, and DB6. They also have no effect on the system, and can be used as hooks for debug functionality. Refer to the individual user manual of your Bedrock system to see how these instructions can be used.

PSH

The PSH operation pushes a value onto a stack, or moves a value between stacks.

Using this operation in immediate mode will push the next value in the program to the working stack, or the return stack in return mode. This is such a common operation that there are aliases for each of the four immediate-mode variants: PSH:, PSH*:, PSHr:, and PSHr*: can each be shortened to :, *:, r:, and r*::

PSH:01 PSHr:02  ( 01    | 02    )
:03    r:04     ( 01 03 | 02 04 )

Using this operation without immediate mode will move a value from the return stack to the working stack, or the other way in return mode. This can be used to temporarily shift a value to another stack so that you can work on the values beneath it, moving it back into place once you’ve finished:

:01 :02  ( 01 02 |    )
PSHr     ( 01    | 02 )
ADD:08   ( 09    | 02 )
PSH      ( 09 02 |    )

POP

The POP operation removes a value from the top of a stack.

This operation is used for removing values from the stacks that are no longer needed, keeping the stacks clear of debris:

:01 :02  ( 01 02 )
POP      ( 01    )
POP      (       )

The immediate-mode variants of this operation can be used to skip over a value without jumping:

:01 :02  ( 01 02 )
POP: 03  ( 01 02 )

CPY

The CPY operation copies a value from one stack to another.

This operation acts similarly to the PSH operation, but it also keeps a copy of the value on the original stack. This can be used to preserve a copy of a value that is about to be modified or consumed, similar to the DUP operation:

:03     ( 03    |    )
CPYr    ( 03    | 03 )
ADD:05  ( 08    | 03 )

The immediate-mode variants of this operation can be used to push a value to both stacks with a single instruction:

CPY:01     ( 01       | 01       )
CPY*:0203  ( 01 02 03 | 01 02 03 )

DUP

The DUP operation duplicates the value at the top of a stack.

This operation can be used to preserve a copy of a value that is about to be modified or consumed, similar to the CPY operation:

:03        ( 03    )
DUP        ( 03 03 )
ADD:05     ( 03 08 )

The immediate-mode variants of this operation will push two copies of a value to a stack with a single instruction:

DUP:01     ( 01 01             )
DUP*:0203  ( 01 01 02 03 02 03 )

OVR

The OVR operation copies the second value on a stack to the top of the stack.

This operation can be used to preserve copies of two doubles that are about to be modified or consumed, similar to the DUP operation but reaching further down the stack:

*:0102 *:0304  ( 01 02 03 04             )
OVR*           ( 01 02 03 04 01 02       )
OVR*           ( 01 02 03 04 01 02 03 04 )

The immediate-mode variant OVR: can be used to duplicate a byte and convert it to a double with a single instruction:

:02         ( 02       )
OVR:00      ( 02 00 02 )

SWP

The SWP operation swaps the top two values on a stack.

This operation can be used to temporarily surface the second value on a stack to operate on:

:03 :05  ( 03 05 )
SWP      ( 05 03 )
ADD:40   ( 05 43 )
SWP      ( 43 05 )

The immediate-mode variant SWP: can be used to convert a byte to a double with a single instruction:

:02           ( 02    )
SWP:00        ( 00 02 )

ROT

The ROT operation rotates the top three values on a stack:

The modeless variant ROT can be used to surface a byte from underneath a double:

:02 *:0001  ( 02 00 01 )
ROT         ( 00 01 02 )

Control operations

The control operations will set the program counter, and access values from devices and program memory.

JMP

The JMP operation sets the program counter to address a*, jumping to that address in the program.

This operation can be used link together multiple pieces of a program, tracing a path between labels:

@A JMP:B   ( runs first  )
@C JMP:D   ( runs third  )
@B JMP:C   ( runs second )
@D HLT     ( runs fourth )

It can also create an infinite loop in a program. This can be used for an event loop, where the program repeatedly handles incoming device events:

@main
  :'.' STD:86     ( print a dot    )
  *:0040 STD*:38  ( set a timer    )
  *:1000 STD:00   ( wait for timer )
  JMP:main        ( loop to start  )

The return-mode variant JMPr can be used to return from a function call. It will consume the return address stored on the return stack by the JMS operation, returning control to just after the function was called:

:05            ( 05 |       )
JMS:add-2 HLT  ( 07 |       )

@add-2         ( 05 | addr* )
  ADD:02       ( 07 | addr* )
  JMPr         ( 07 |       )

JMS

The JMS operation sets the program counter to address a*, jumping to that address in the program and storing the original address b* on the return stack.

This operation can be used to perform a function call. The address of the next instruction will be stored to the return stack just before jumping, and a JMPr instruction will return to that address to end the function:

:05        ( 05 )
JMS:add-2  ( 07 )
JMS:add-2  ( 09 )
HLT        ( 09 )

@add-2     ( 05 | addr* )
  ADD:02   ( 07 | addr* )
  JMPr     ( 07 |       )

The return- and immediate-mode variant JMSr: can be used with the block syntax to implement anonymous functions (also called lambdas). The function address will be placed on the working stack, and the program will jump to the closing brace:

%λ: JMSr: ;

:05 λ:{ ADD:02 JMPr }  ( 05 λ* )
JMS HLT                ( 07    )

The same technique can also be used to implement anonymous strings:

%λ: JMSr: ;

λ:{"This is a string. "}  ( string* )

JCN

The JCN operation sets the program counter to address a* if the condition t is not zero, performing a conditional jump.

This operation can be used to perform a conditional jump, jumping to a different section of the program if a value is true, or continuing without jumping if the value is false. A value is true if it isn’t zero:

:01 JCN:if-true
@if-false  HLT  ( program ends here if value was false )
@if-true   HLT  ( program ends here if value was true  )

This can also be used to loop over a section of code by using a loop counter as the jump condition. The loop counter will decrement with each iteration of the loop, and the program will keep looping until the counter reaches zero:

:08 @loop           ( loop eight times  )
  :'.' STD:86       ( print a dot       )
  DEC DUP JCN:loop  ( decrement counter )
POP                 ( remove counter    )

The immediate-mode variant JCN: can be used with the block syntax to skip over a block of code if a condition is true:

:02 :01                 ( 02 01 )
JMS:sort-ascending HLT  ( 01 02 )

@sort-ascending  ( a b -- c d )
  DUP* GTH JCN:{ SWP } JMPr

JCS

The JCS operation sets the program counter to address a* if the condition t is not zero, performing a conditional jump. The original address b* will be stored one the return stack if the jump was performed.

This operation can be used to perform a conditional function call, similar to the JCN and JMS operations. It can only be used to call functions that don’t add or remove values from the stack, because any values pushed to the stack for the function will not be consumed if the function isn’t called. To work around this, the operation can be used to call a no-argument function that pushes values to the stack and jumps to the intended function:

:01 JCS:print-a HLT

@print-a  ( -- )
  :'A' JMP:print-char

@print-char  ( c -- )
  STD:86 JMPr

LDA

The LDA operation loads the value v from address a*.

This operation can be used to read from a variable, a value that has been saved to memory for later:

LDA:var HLT  ( 03 )

@var 03

The wide-mode variants of this operation can be used to read a double value from memory:

LDA*:var HLT  ( 12 34 )

@var 1234

STA

The STA operation stores the value v at address a*.

This operation can be used to write a value to a variable, to be read back later with the LDA operation:

:03 STA:var  (    )
LDA:var HLT  ( 03 )

@var 00

The wide-mode variants of this operation can be used to write a double value to memory:

*:1234 STA*:var  (       )
LDA*:var HLT     ( 12 34 )

@var 0000

This operation can also be used to overwrite instruction bytes in memory, modifying the program:

:DEC STA:op  (    )
:03 @op INC  ( 02 )

LDD

The LDD operation loads the value v from device port p. The port value is always a byte.

This operation is used to read a value from a device port:

LDD:0C  ( wst )

The wide-mode variants of this operation can be used to read from two consecutive ports with a single instruction:

LDD*:0C  ( wst rst )

STD

The STD operation stores the value v to device port p. The port value is always a byte.

This operation is used to write a value to a device port:

:'B' STD:86  (    )

The wide-mode variants of this operation can be used to write to two consecutive ports with a single instruction:

*:'BB' STD*:86  (    )

Integer operations

The integer operations will add, subtract, and compare values as integers.

ADD

The ADD operation adds x and y, returning the result r.

:02 :03 ADD  ( 05 )

SUB

The SUB operation subtracts y from x, returning the result r.

:05 :03 SUB  ( 02 )

INC

The INC operation increments x by one, returning the result r.

:03 INC  ( 04 )

DEC

The DEC operation decrements x by one, returning the result r.

:03 DEC  ( 02 )

LTH

The LTH operation checks if x is less than y, returning the truth byte t. The truth byte is FF if true or 00 if false.

:02 :03 LTH  ( FF )

This operation can be combined with the NOT operation to check if x is greater than or equal to y:

:02 :03 LTH NOT  ( 00 )

GTH

The GTH operation checks if x is greater than y, returning the truth byte t. The truth byte is FF if true or 00 if false.

:02 :03 GTH  ( 00 )

This operation can be combined with the NOT operation to check if x is less than or equal to y:

:02 :03 GTH NOT  ( FF )

EQU

The EQU operation checks if x is equal to y, returning the truth byte t. The truth byte is FF if true or 00 if false.

:02 :03 EQU  ( 00 )

This operation can be combined with the NOT operation to check if x is equal to y, similar to the NQK operation but without keeping both values:

:02 :03 EQU NOT  ( FF )

NQK

The NQK operation checks if x is not equal to y, keeping both values and returning the truth byte t. The truth byte is FF if true or 00 if false.

:02 :03 NQK  ( 02 03 FF )

This operation can be used to loop over a range of values. The end value is kept beneath the loop counter, and the NQK instruction is used to compare both values without consuming them, with the truth value being passed to the JCN instruction. The program will keep looping until the loop counter becomes equal to the end value:

:5B :41 @loop       ( end i )
  DUP STD:86        ( end i )
  INC NQK JCN:loop  ( end i )
POP POP             (       )

This operation can be combined with the NOT operation to check if x is equal to y while keeping both values, similar to the EQU operation:

:02 :03 NQK NOT  ( 02 03 00 )

Binary operations

The binary operations will shift, rotate, and perform logical operations on values as binary.

SHL

The SHL operation shifts the bits of x to the left by y places, returning the result r.

:A7     ( A7 ) ( binary 10100111 )
SHL:04  ( 70 ) ( binary 01110000 )

This operation can be used to multiply a number by a power of 2. Each bit shifted to the left will double the value:

:01     ( 01 ) ( binary 00000001 )
SHL:01  ( 02 ) ( binary 00000010 )
SHL:01  ( 04 ) ( binary 00000100 )
SHL:01  ( 08 ) ( binary 00001000 )

SHR

The SHR operation shifts the bits of x to the right by y places, returning the result r.

:A7     ( A7 ) ( binary 10100111 )
SHR:04  ( 0A ) ( binary 00001010 )

This operation can be used to divide a number by a power of 2. Each bit shifted to the right will halve the value:

:08     ( 08 ) ( binary 00001000 )
SHL:01  ( 04 ) ( binary 00000100 )
SHL:01  ( 02 ) ( binary 00000010 )
SHL:01  ( 01 ) ( binary 00000001 )
SHL:01  ( 00 ) ( binary 00000000 )

ROL

The ROL operation rotates the bits of x to the left by y places, returning the result r.

:92     ( 92 ) ( binary 10010010 )
ROL:02  ( 4A ) ( binary 01001010 )

ROR

The ROR operation rotates the bits of x to the right by y places, returning the result r.

:92     ( 92 ) ( binary 10010010 )
ROR:02  ( A4 ) ( binary 10100100 )

IOR

The IOR operation finds the union of the bits of x and y, with each bit being set in the result r if it is set in x or y.

:33   ( 33    ) ( 33 is binary 00110011 )
:0F   ( 33 0F ) ( 0F is binary 00001111 )
IOR   ( 3F    ) ( 3F is binary 00111111 )

XOR

The XOR operation finds the difference between the bits of x and y, with each bit being set in the result r if it is set in only one of x or y.

:33   ( 33    ) ( 33 is binary 00110011 )
:0F   ( 33 0F ) ( 0F is binary 00001111 )
XOR   ( 3C    ) ( 3F is binary 00111100 )

AND

The AND operation finds the intersection of the bits of x and y, with each bit being set in the result r if it is set in both x and y.

:33   ( 33    ) ( 33 is binary 00110011 )
:0F   ( 33 0F ) ( 0F is binary 00001111 )
AND   ( 02    ) ( 3F is binary 00000011 )

This operation can be used to conditionally add a value without using a jump. The example below converts a hexadecimal digit to a character byte, adding 30 to values 00..09 and 37 to values 0A..0F. To do this, we compare the value using GTH:09 to get FF or 00, and then we use AND:07 to convert that to 07 or 00. We can then ADD:30 to get 37 or 30, adding this to the original digit value:

:0B JMS:digit-to-char STD:86 HLT

@digit-to-char
  DUP GTH:09 AND:07 ADD:30 ADD JMPr

NOT

The NOT operation inverts the bits of x, with each bit being set in r if it isn’t set in x.

:3F  ( 3F ) ( binary 00111111 )
NOT  ( C0 ) ( binary 11000000 )

Appendix A: Expanded reference

In the following table, the r column represents return mode, * represents wide mode, and : reresents immediate mode. Instructions are grouped by operation, with the first instruction of each group being hyperlinked to that operation.

For the signatures listed in the working stack and return stack columns, the i value represents an immediate value read from memory. Values with a trailing * are doubles, and all other values are bytes. Signatures with no argument values or return values have been omitted for clarity.