This specification describes the architecture required to run Bedrock bytecode.

Terminology

Byte

A byte is an 8-bit value, and is the base unit of data used by Bedrock.

Double

The term double is short for ‘double-width value’, and is a 16-bit value represented as a pair of bytes in big-endian order.

Undefined behaviour

Any operation with undefined behaviour must be avoided by a program.

Program memory

The program memory is a 65536 byte block of read-write memory that holds the current program. The initial value of each byte of memory is zero.

Systems with fewer than 65536 bytes of program memory are partially supported. The behaviour when an unimplemented memory address is read from or written to is undefined.

Reading from memory

Reading a byte from program memory will return the byte at the given memory address.

Reading a double from program memory will read the high byte from the given memory address, and the low byte from the following memory address. The behaviour when a double is read from the highest memory address is undefined.

Writing to memory

Writing a byte to program memory will write that byte to the given memory address.

Writing a double to program memory will write the high byte to the given memory address, and the low byte to the following memory address. The behaviour when a double is written to the highest memory address is undefined.

Loading a program

To load a program into program memory, the program bytecode is copied into program memory starting at address zero. If the program exceeds the length of program memory, the remaining bytes are discarded.

Stacks

The stacks are two identical 256 byte stacks, the working stack and the return stack. The initial value of each byte of stack memory is undefined.

Systems with fewer than 256 bytes of memory per stack are partially supported.

Stack pointer

Each stack has a stack pointer, an 8-bit register that points to the next free byte of stack memory. The initial value of each stack pointer is zero. The behaviour on overflow or underflow is undefined.

Pushing to a stack

Pushing a byte to a stack will write the byte to the stack memory address referenced by the stack pointer, and then will increment the stack pointer by 1.

Pushing a double to a stack will push the high byte of the double, followed by the low byte of the double.

Popping from a stack

Popping a byte from a stack will decrement the stack pointer by 1, and then will read the byte from the stack memory address referenced by the stack pointer.

Popping a double from a stack will pop the low byte of the double first, followed by the high byte of the double.

Device bus

The device bus is a 256 port communications bus for interfacing with up to sixteen different devices. Each device is allocated sixteen ports on the device bus.

Each port is identified by an 8-bit port number. The upper four bits of the port number identify a device slot, and the lower four bits identify a port within that device.

Reading from a device

Reading a byte from the device bus will send a read request to the given device port, and then the device connected to that port will process the read request and return a byte. There is no limit to the time a device can take while processing a read request. If there is no device connected to the given device port, the request will return immediately with a value of zero.

Reading a double from the device bus will read the high byte of the double from the given device port, and the low byte of the double from the following device port. The behaviour when a double is read from the highest port number is undefined.

Writing to a device

Writing a byte to the device bus will send a write request with that byte to the given device port, and then the device connected to that port will process the write request and return. There is no limit to the time a device can take while processing a write request. If there is no device connected to the given device port, the request will return immediately.

Writing a double to the device bus will write the high byte of the double to the given device port, and the low byte of the double to the following device port. The behaviour when a double is written to the highest port number is undefined.

Processor

The processor sequentially executes instructions from program memory.

Program counter

The program counter is a 16-bit register that points to the memory address of the next instruction to be executed. The initial value of the program counter is zero. The behaviour when the program counter overflows is undefined.

After an instruction is read from program memory, the program counter is incremented by 1. After a value is read from program memory due to the effect of immediate mode, the program counter is incremented by 1 for each byte read.

Instructions

Instructions are stored as bytes in program memory. The lower five bits of an instruction byte determine the operation to be performed, and the upper three bits are mode flags that affect how the operation will be performed.

Return mode

Bit 0x80 of the instruction byte is the return mode flag. When set, the operation will use the return stack in place of the working stack, and the working stack in place of the return stack.

Immediate mode

Bit 0x40 of the instruction byte is the immediate mode flag. When set, the first time that the operation would pop a value from a stack, a value of the same size is read instead from program memory, from the address referenced by the program counter.

Wide mode

Bit 0x20 of the instruction byte is the wide mode flag. When set, the instruction will operate on double-size values, otherwise the instruction will operate on byte-size values. Values specified as fixed-size by an instruction are not affected by this mode.

Operation summary

In the notation used in the signature column of the following table, the letters to the left of the -- token represent the values on the stack before the instruction is executed, and the letters to the right represent the values on the stack after the instruction is executed. A * suffix represents a fixed-size double, a ! suffix represents a fixed-size byte, and a plain letter represents a value with a size determined by the state of the double mode flag.

Operations

The terms primary stack and return stack are used in the following descriptions to refer to the stacks once the return mode flag has been applied. The primary stack is normally the working stack, but will be the return stack while the return mode flag is set. The secondary stack is normally the return stack, but will be the working stack while the return mode flag is set.

In the instruction table 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.

HLT

Halt the processor, terminating the current program. If any mode flag is set, do nothing.

The instruction variants DB1, DB2, DB3, DB4, DB5, and DB6 can be used as hooks for implementation defined debug functionality.

JMP

Jump to an address.

The double a is popped from the primary stack. If the wide mode flag is set, the double b is then read from the program counter and pushed to the secondary stack. The double a is then written to the program counter.

JCN

Conditionally jump to an address.

The double a is popped from the primary stack, then the byte t is popped from the primary stack. If the wide mode flag is set and t is not zero, the double b is then read from the program counter and pushed to the secondary stack. If t is not zero, the double a is then written to the program counter.

JCK

Conditionally jump to an address, keeping the test value.

The double a is popped from the primary stack, then the value t is popped from the primary stack, then the value t is pushed to the primary stack. The double a is then written to the program counter if t is not zero.

LDA

Read a value from program memory.

The double a is popped from the primary stack, and then the value v is read from program memory starting at the memory address referenced by a and is pushed to the primary stack.

STA

Write a value to program memory.

The double a is popped from the primary stack, then the value v is popped from the primary stack, and then the value v is written to program memory starting at the memory address referenced by a.

LDD

Read a value from the device bus.

The byte p is popped from the primary stack, then the value v is read from the device bus starting at the device port referenced by p and is pushed to the primary stack.

STD

Write a value to the device bus.

The byte p is popped from the primary stack, then the value v is popped from the primary stack and is written to the device bus starting at the device port referenced by p.

PSH

Move the top value from one stack to the other.

The value x is popped from the secondary stack and is pushed to the primary stack.

POP

Remove the top value of a stack.

The value x is popped from the primary stack.

CPY

Copy the top value from one stack to the other.

The value x is popped from the secondary stack, and then is pushed to the secondary stack, and then is pushed to the primary stack.

SPL

Split packed bytes into two bytes each.

The value x is popped from the primary stack. For each byte b of x, starting with the high byte, create a byte y where the high four bits of b are the low four bits of y and the remainder are unset, and push y to the primary stack, then create a byte z where the low four bits of b are the low four bits of z and the remainder are unset, and push z to the primary stack.

DUP

Duplicate the top value of a stack.

The value x is popped from the primary stack, then is pushed to the primary stack, and then is pushed once more to the primary stack.

OVR

Duplicate the second value of a stack.

The value y is popped from the primary stack, then the value x is popped from the primary stack, then the value x is pushed to the primary stack, then the value y is pushed to the primary stack, and then the value x is pushed to the primary stack.

SWP

Swap the top two values on a stack.

The value y is popped from the primary stack, then the value x is popped from the primary stack, then the value y is pushed to the primary stack, and then the value x is pushed to the primary stack.

ROT

Rotate the top three values on a stack.

The value z is popped from the primary stack, then the value y is popped from the primary stack, then the value x is popped from the primary stack, then the value y is pushed to the primary stack, then the value z is pushed to the primary stack, and then the value x is pushed to the primary stack.

ADD

Find the sum of two values.

The value y is popped from the primary stack, then the value x is popped from the primary stack, and then the value r is calculated as the wrapped addition of y to x and is pushed to the primary stack.

SUB

Find the difference of two values.

The value y is popped from the primary stack, then the value x is popped from the primary stack, and then the value r is calculated as the wrapped subtraction of y from x and is pushed to the primary stack.

INC

Increment a value by 1.

The value x is popped from the primary stack, and then the value r is calculated as the wrapped addition of 1 to x and is pushed to the primary stack.

DEC

Decrement a value by 1.

The value x is popped from the primary stack, and then the value r is calculated as the wrapped subtraction of 1 from x and is pushed to the primary stack.

LTH

Test if one value is less than another.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. If x is less than y, the byte 0xff is pushed to the primary stack, otherwise the byte 0x00 is pushed to the primary stack.

GTH

Test if one value is greater than another.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. If x is greater than y, the byte 0xff is pushed to the primary stack, otherwise the byte 0x00 is pushed to the primary stack.

EQU

Test if two values are equal.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. If x is equal to y, the byte 0xff is pushed to the primary stack, otherwise the byte 0x00 is pushed to the primary stack.

NQK

Test if two values are inequal, keeping the values.

The value y is popped from the primary stack, then the value x is popped from the primary stack, then the value x is pushed to the primary stack, and then the value y is pushed to the primary stack. If x is not equal to y, the byte 0xff is pushed to the primary stack, otherwise the byte 0x00 is pushed to the primary stack.

IOR

Find the bitwise disjunction of two values. This operation is also known as ‘inclusive-or’.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. The value r is then calculated bitwise, where each bit of r is set only if at least one of the corresponding bits of x and y is set. The value r is then pushed to the primary stack.

XOR

Find the bitwise non-equivalence of two values. This operation is also known as ‘exclusive-or’.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. The value r is then calculated bitwise, where each bit of r is set only if exactly one of the corresponding bits of x and y is set. The value r is then pushed to the primary stack.

AND

Find the bitwise conjunction of two values. This operation is also known as ‘and’.

The value y is popped from the primary stack, and then the value x is popped from the primary stack. The value r is then calculated bitwise, where each bit of r is set only if both of the corresponding bits of x and y are set. The value r is then pushed to the primary stack.

NOT

Find the bitwise compliment of a value. This operation is also known as ‘not’.

The value x is popped from the primary stack. The value r is then calculated bitwise, where each bit of r is set only if the corresponding bit of x is not set. The value r is then pushed to the primary stack.

SHF

Shift the bits of a value.

The byte y is popped from the primary stack, then the value x is popped from the primary stack. The value r is calculated from x by shifting the bits of x leftwards by a distance represented by the upper four bits of y, and then by shifting the resultant bits rightwards by a distance represented by the lower four bits of y. The value r is then pushed to the primary stack.

When a value is shifted n bits in one direction, each bit of the value is set to the state of the bit lying n bits in the opposite direction. If this would reach past the end of the value, the bit is unset.

SHC

Rotate the bits of a value. This operation is also known as a ‘circular shift’.

The byte y is popped from the primary stack, then the value x is popped from the primary stack. The value r is calculated from x by rotating the bits of x leftwards by a distance represented by the upper four bits of y, and then by rotating the resultant bits rightwards by a distance represented by the lower four bits of y. The value r is then pushed to the primary stack.

When a value is rotated n bits in one direction, each bit of the value is set to the state of the bit lying n bits in the opposite direction. If this would reach past the end of the value, wrap around to the other end of the value and continue.

TAL

Count the number of set bits in a value. This operation is also known as ‘population count’.

The value x is popped from the primary stack, and then the value r is calculated as the number of bits set in x and is pushed to the primary stack.

REV

Reverse the order of bits in a value.

The value x is popped from the primary stack. The value r is then calculated bitwise, where each bit of r starting from one end of the value is set only if the corresponding bit of x starting from the opposite end of the value is set. The value r is then pushed to the primary stack.