This document is a detailed reference manual for the instruction set of the Bedrock computer system.

If this document doesn’t answer your question, the definitive guide is the Architecture specification.

Summary

How instructions work

An operation and three mode flags.

Eight variants of each operation.

Operation groups

There are 32 operations, three modes. 8 variants of each operation, 256 possible instructions.

Instructions are grouped into four categories

Stack operations

HLT

The HLT operation halts the Bedrock processor, terminating the current program.

Variants: NOP, and DB1-6

If any of the mode flags are set, this instruction will do nothing.

All bytes of program memory are zero by default, and so a program will halt if it jumps

Stops the program.

All uninitialised memory is zero, HTL instructions.

Also NOP, for doing nothing.

Also DB[1-6], for debug stuff, implementation defined. Look at the manual for your implementation.

PSH

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

Pushing a value

When using PSH in immediate mode, the next value in the program will be pushed to a stack. This can be used to push a byte or a double. The value will normally be pushed to the working stack, but can be pushed to the return stack with return mode.

This is such a common operation that there are aliases for each of the four immediate-mode PSH instructions: PSH:, PSH*:, PSHr:, and PSHr*: can be shortened to :, *:, r:, and r*:.

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

Moving between stacks

When using PSH without immediate mode, a value will be moved from one stack to the other. The value will normally move from the return stack to the working stack, but can be moved the other way with return mode.

:01 :02  ( 01 02 |    )
PSHr     ( 01    | 02 )
PSH      ( 01 02 |    )

POP

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

Remove a value from a stack.

Cleaning up before returning from a function.

CPY

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

Duplicate a value across stacks

For keeping a copy around.

Good for loop counters.

DUP

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

duplicate to keep a copy around

good for before a function that doesn’t preserve its arguments.

OVR

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

SWP

The SWP operation exchanges the positions of the top two values on a stack.

insert a value below the current one

turn a byte into a double.

ROT

The ROT operation rotates the positions of the top three values on a stack.

extract values

good for byte below double

Control operations

Decisions in the program

Interacting with the world

JMP

The JMP operation jumps to an address in the program.

Return from a function

JMS

The JMS operation jumps to an address, storing the original address.

Call a function

JCN

The JCN operation jumps to an address if a condition is true.

Decisions, conditional logic

JCS

The JCS operation jumps if a condition is true, storing the original address.

Conditional call, good for no-argument functions.

LDA

The LDA operation loads a value from a memory address onto a stack.

Access an array

Load variables

STA

The STA operation stores a value from a stack to a memory address.

Store variables

Edit code

LDD

The LDD operation loads a value from a device port onto a stack.

Read from device

STD

The STD operation stores a value from a stack to a device port.

Write to device

Numeric operations

ADD

The ADD operation adds two values together.

Adding offsets to addresses, for indexing into an array.

SUB

The SUB operation subtracts one value from another.

INC

The INC operation increments a value by one.

Loops

DEC

The DEC operation decrements a value by one.

Loops

LTH

The LTH operation compares two values, returning true if the first is less than the second.

GTH

The GTH operation compares two values, returning true if the first is greater than the second.

Test if something isn’t zero, since there isn’t a dedicated NEQ instruction

EQU

The EQU operation compares two values, returning true if they are equal.

NQK

The NQK operation compares two values, returning true if they are not equal. The values are also both kept on the stack.

Used for loops

Binary operations

Binary operations treat values as sequences of bits that can be turned on, turned off, and moved left and right.

First half is shifting. Second half is logic.

SHL

SHR

ROL

ROR

IOR

The IOR operation merges two values, keeping the bits that are set in either value.

Merges two values together.

Also logic

Setting bits

XOR

The XOR operation merges two values, keeping the bits that are different in both values.

Finds the bits that are different between two values.

Can be used to invert specific bits in a value. Given a mask.

AND

The AND operation merges two values, keeping the bits that are set in both values.

The AND operation i

pops two values and pushes a value that Keeps the bits that are set in both values.

Can be used to turn off specific bits in a value. Given a mask,

order isn’t important

:55  (  input value - bits are 0101_0101 )
:0F  (   mask value - bits are 0000_1111 )
AND  ( result value - bits are 0000_0101 )

Can also be used to check two boolean values, returning true if both values are true. The values must be either ff or 00.

:00 :00 AND ( returns 00 )
:ff :00 AND ( returns 00 )
:ff :ff AND ( returns ff )

NOT

The NOT operation inverts every bit in a value.

Turn ff into 00

This reference is intended to be used by people working with Bedrock programs. Every instruction is expanded to show the effect of each mode flag combination.

For people implementing a Bedrock system, the exact semantics of each instruction can be found in the architecture specification.

In the instruction table provided for each operation, the * column contains a character when the wide-mode flag is set, the : column contains a character when the immediate-mode flag is set, and the r column contains a character when the return-mode flag is set.

Appendix A: Stack reference

Omits return-mode instructions for brevity. Swap the working stack and return stack columns, and add 0x80 to the instruction value.

i is an immediate value.