Registry device

This specification describes the registry device of the Bedrock computer system.

The registry device provides access to a persistent shared key-value store.

Ports

Namespace

This port is associated with a byte buffer.

Writing a non-zero byte to this port will write that byte to the associated byte buffer. Writing a zero byte to this port will read a name from the buffer, and then will clear the buffer. If the name is valid, that name will become the active namespace. If the name is invalid, the null namespace will become the active namespace.

Key

This port is associated with a byte buffer.

Writing a non-zero byte to this port will write that byte to the associated byte buffer. Writing a zero byte to this port will read a name from the buffer, and then will clear the buffer. If the name is valid, that name will become the active key. If the name is invalid, the null key will become the active key.

Read value

Writing a value to this port will remove all bytes from the read queue, and then will read the stored value of the active key of the active namespace into the queue if the value exists and is the correct type. If a non-zero value was written to the port, the stored value must be a text value. If a zero value was written to the port, the stored value must be a binary value.

Write value

Writing a value to this port will write the contents of the write queue to the active key of the active namespace, first removing any existing value, and then will remove all bytes from the queue. If a non-zero value was written to the port, the value will be written as a text value. If a zero value was written to the port, the value will be written as a binary value.

Read length

Reading from this port will return the number of bytes waiting in the read queue.

Write length

Reading from this port will return the number of bytes of free space in the write queue.

Writing to this port will remove all bytes from the write queue.

Head

Reading from this port will remove and return a byte from the front of the read queue. If the queue is empty, the value zero will be returned.

Writing a byte to this port will push that byte to the back of the write queue. No byte will be pushed if the queue is full.

Namespace select

Reading from this port will return the number of registered namespaces, excluding the null namespace.

Writing a value to this port will select the namespace addressed by the value written, making it the active namespace. If no namespace is addressed, the null namespace will become the active namespace.

The sort order of the namespaces in the registry is implementation defined, but must be stable. Each namespace is addressed by its position in the sort order. The null namespace will be excluded from the sort order, and will not be addressable.

Key select

Reading from this port will return the number of registered keys in the active namespace.

Writing a value to this port will select the key in the active namespace that is addressed by the value written, making it the active key. If no key is addressed, the null key will become the active key.

The sort order of the keys in the namespace is implementation defined, but must be stable. Each key is addressed by its position in the sort order.

Namespace name

This port is associated with a byte buffer. When the active namespace changes, the buffer is populated with the name of the active namespace.

Reading from this port will read and return a byte from the associated byte buffer.

Writing to this port will set the pointer of the associated byte buffer to zero.

Key name

This port is associated with a byte buffer. When the active key changes, the buffer is populated with the name of the active key.

Reading from this port will read and return a byte from the associated byte buffer.

Writing to this port will set the pointer of the associated byte buffer to zero.

Data structures

Registry

The registry is a persistent key-value store for data that does not change frequently. Every stored value is addressed by a key and a namespace.

The contents of the registry will persist after the system halts.

Registry namespace

A namespace is a name associated with a group of keys in the registry. A namespace only exists if it contains at least one key.

At most 65,535 namespaces can exist in the registry simultaneously. The behaviour when this value is exceeded is undefined.

Registry key

A key is a name associated with a value in the registry. A key belongs to a namespace, and only exists if it has a value.

At most 65,535 keys can exist in a namespace simultaneously. The behaviour when this value is exceeded is undefined.

Active namespace

The active namespace is a name that represents the namespace that will be used when reading and writing a stored value. The initial active namespace is the null namespace.

Active key

The active key is a name that represents the key that will be used when reading and writing a stored value. The initial active key is the null key.

Null namespace

The null namespace is a special namespace that is used for passing values from a launcher or shell. The name of the null namespace is blank.

Values stored in the null namespace are local, and are not shared between Bedrock instances. They are also ephemeral, persisting after a reset but not after the system halts.

Null key

The null key is a special key that is not associated with a value. The name of the null key is blank.

When a value is read from the null key in any namespace, no value will be returned. When a value is written to the null key in any namespace, no value will be stored.

Stored value

A value is a sequence of bytes stored in the registry. The maximum length of a value is 255 bytes.

Each value will be one of two types: a binary value or a text value. A binary value can contain any sequence of bytes. A text value is a UTF-8 encoded string that does not contain any byte less than 0x20. The behaviour when reading or writing a text value that does not meet these requirements is undefined.

Name

A name is a UTF-8 encoded string that does not contain any byte less than 0x20 and is no longer than 127 bytes. If a name does not meet these requirements, it is invalid.

Byte buffer

A byte buffer is a 256 byte block of writeable memory. The initial value of each byte of the buffer is zero. The initial value of the pointer is zero.

Reading a byte from a byte buffer will return the byte referenced by the pointer, and then will increment the pointer by 1, wrapping to zero after 255.

Writing a byte to a byte buffer will write that byte to the buffer address referenced by the pointer, and then will increment the pointer by 1, wrapping to zero after 255.

To clear a byte buffer, the pointer and every byte of the buffer will be set to zero.

To populate a byte buffer with a name, the buffer will be cleared, then every byte of the name will be written to the buffer, and then the pointer will be set to zero.

To read a name from a byte buffer, the buffer contents up to the first zero byte will be read. If the final byte of the buffer is not zero, the name will be invalid.

This device contains four byte buffers: one each for the namespace, key, namespace name, and key name ports.

Read queue

The read queue is a first-in first-out byte queue used to buffer a value read from a key. The maximum length of the queue is 255 bytes.

Write queue

The write queue is a first-in first-out byte queue used to buffer a value written to a key. The maximum length of the queue is 255 bytes.

Implementation

Invalid text values

Invalid text values should be read from and written to the registry as empty values.

Command-line arguments

When launching a Bedrock program from the command line, all command line arguments passed to the program should be registered under the null namespace.

The key for each named argument should be the name of that argument. The key for each positional argument should be the position of that argument as a numeric string, starting from 1. The key named 0 should be reserved for the Bedrock filesystem path that the program was loaded from, if it was loaded from a file.

Safety

Access to the Bedrock registry could allow a malicious program to read and modify sensitive data, or replace the value of a key with malicious data.

To mitigate this, a separate registry could be provided for untrusted programs.

Wake

This device will never send a wake request to the system device.