Device specification

This specification describes the standard device interfaces of the Bedrock computer system.

Overview

The device bus in the Bedrock architecture specification allows the Bedrock system to read and write from up to 16 external devices. This specification describes the expected behaviour of each of these devices.

Device interfaces are grouped into four categories: core devices, human interface devices, system interface devices, and custom devices.

Definitions

Flag

A flag is a value with two possible states: set or clear.

Signed integer

A signed integer is an integer value that is represented using two’s compliment form. The sign of a signed value can be flipped by inverting all bits of the value and then incrementing by 1.

Port group

A port group is a contiguous group of ports that are accessed together to allow values larger than a byte to be read or written. Ports belonging to a group are listed with the name ‘grouped’ in a port table. Values are exposed in big-endian byte order, with the lowest-addressed port in the group exposing the highest-order byte of the value.

Port alias

A port alias is an alias of the previous port in a port table (the port with the next lower address). Port aliases are listed with the name ‘aliased’ in a port table. Reading or writing to a port alias is the same as reading or writing to the aliased port.

Atomic read

A port group that implements atomic reads will cache the value exposed by the port group each time the lowest-addressed port in the group is read from. The cached value will be used instead of the live value when reading from each of the remaining ports in the group. The initial value of the read cache for each port group that implements atomic reads is zero.

Atomic write

A port group that implements atomic writes will modify an intermediary cached value each time a port in the group is written to. When the highest-addressed port in the group is written to, the cached value will overwrite the previous value in a single operation. The initial value of the write cache for each port group that implements atomic writes is zero.

Undefined behaviour

Undefined behaviour is behaviour that is triggered when performing an unsupported action. This can result in any behaviour at all, including corruption of the system state. All programs must avoid triggering undefined behaviour. All systems should try to handle undefined behaviour safely and predictably.

Implementation defined

An implementation defined value is a value that will be determined individually by each Bedrock system.

Devices

Core devices

The core devices provide access to features that exist on most computer systems: a sleep mode, additional memory, efficient math operations, and a real-time clock:

Human interface devices

The human interface devices provide access to features for building interactive programs: a mouse, keyboard, screen, and speakers:

A Bedrock system designed to run headless or without user input would not need to implement these devices.

System interface devices

The system interface devices provide access to features for manipulating shared data: network access, a clipboard, and persistent storage:

A Bedrock system designed to run without data persistence or access to other systems would not need to implement these devices.

These devices could be misused by untrusted programs to read sensitive data, delete important files, or freely access the internet, and so should be sandboxed or disconnected by default to protect your system. Safety advisories are included with the specifications for each device.

Custom devices

The custom devices are reserved for the private use of each Bedrock system.

The behaviour of each custom device is undefined. Programs relying on the behaviour of a custom device will not be portable to other Bedrock systems.