Specification

This is the full specification for the Bedrock computer system.

This specification is aimed at people who are implementing the system from scratch. For people who are learning about or writing programs for the Bedrock system, the user manual will generally be more useful.

Overview

Bedrock is a portable 8-bit computer system that is designed to be straightforward to implement on a wide variety of computer architectures and form factors. The core system can be implemented by a solo programmer in a day, and the devices are designed to be implemented as needed. Programs written for the system will be able to run on any platform for which a Bedrock system implementation exists.

Programs are distributed as binary files, and are generally no more than 10 kilobytes in size.

Sections

The specification is divided into multiple sections for readability.

• Architecture specification
  The architecture specification describes the architecture and instruction set of the core Bedrock system.
• Assembler specification
  The assembler specification describes the syntax and semantics of the standard Bedrock assembler.
• Metadata specification
  The metadata specification describes how program information can be embedded into a program.

Device specifications

• System device
  The system device provides information about the system and allows the system to wait for events.
• Memory device
  The memory device provides access to up to 16 megabytes of additional working memory.
• Math device
  The math device provides access to multiplication, division, and coordinate space conversion operations.
• Clock device
  The clock device provides access to the current date and time, and to four high-resolution countdown timers.
• Input device
  The input device provides access to input from a mouse, keyboard, and four gamepads.
• Screen device
  The screen device provides access to a 16 colour screen with two layers.
• Tone device
  The tone device has not been designed yet.
• Sampler device
  The sampler device has not been designed yet.
• Stream device
  The stream device provides communication with standard terminal streams and the internet.
• File device
  The file device provides access to a heirarchical filesystem.
• Clipboard device
  The clipboard device provides access to the shared system clipboard and a drag-and-drop interface.
• Registry device
  The registry device provides access to a persistent key-value data store.

Device map

Each device is connected to a slot on the device bus as per the following table:

The device slots 0xC, 0xD, 0xE, and 0xF are reserved for the private use of each Bedrock system implementation. Programs relying on the behaviour of a custom device will not be portable across other Bedrock systems.

Terminology

Byte

A byte is an 8 bit value. Bytes are treated as unsigned integers.

Double

A double (or ‘double-width value’) is an 16 bit value, stored as a pair of bytes in big-endian byte order. Doubles are treated as unsigned integers.

Flag

A flag is a value with only two possible states, set or cleared.

Port group

A port group is a group of device ports that acts as a single larger port, allowing access to larger values. Ports belonging to a group are listed with the name ‘grouped’ in a port table, and are owned by the previous port in the table. Values are exposed in big-endian byte order, with the lowest-addressed port exposing the highest-order byte.

Port alias

A port alias is a device port that acts as a copy of the previous port in the port table. Port aliases are listed with the name ‘aliased’ in a port table. Accessing a port alias is the same as accessing the aliased port.

Atomic read

Some port groups will perform atomic reads of the exposed value. Reading from the lowest-addressed port of the group will cache the the current value of the port group, and reading from any port in the group will return the corresponding byte of the cached value. The initial cached read value of each port group is zero.

Atomic write

Some port groups will perform atomic writes to the exposed value. Writing to any port in the group will set the corresponding byte of a cached value, and writing to the highest-addressed port of the group will commit the cached value, overwriting the exposed value. The initial cached write value of each port group is zero.

Undefined behaviour

Undefined behaviour is behaviour that is triggered by performing an unsupported action, and can include any behaviour at all, including corruption of the system state. Programs must avoid triggering undefined behaviour. Implementations should handle undefined behaviour safely and predictably where possible.

Undefined value

An undefined value is a value that is determined individually by each implementation.