This is the user manual for the registry device of the Bedrock computer system.
This document is aimed at people who are learning about or writing programs for the Bedrock system. For people who are implementing the system from scratch, the registry device specification will provide more relevant information.
Overview
The registry device provides access to a persistent key-value data store, shared between all Bedrock programs.
Concepts
The registry is used for sharing short values between programs, with values persisting after the program is closed. This is useful for storing user preferences or paths to recently accessed files.
Each value is stored under a key, which is the name that is used to locate the value, and keys are grouped into namespaces. Keys and namespaces are automatically created as they are written to, and deleted as they are cleared. The name of a key or namespace is a UTF-8 encoded string that is at most 127 bytes long and does not contain any byte from 00 to 1F.
Each value can either be a text value, which is a UTF-8 encoded string that does not contain any byte from 00 to 1F, or a binary value, which is unrestricted. Values can be at most 255 bytes long.
The null namespace is the namespace with an empty name, and is treated differently to all other namespaces. Values written to the null namespace do not persist after the program is closed, but they do persist across a program reset. Command-line arguments passed to a Bedrock program are written as values to the null namespace, with the key of a named argument being the argument name, and the key of a positional argument being the position of that argument as a number starting from 1. If the program was loaded from a file, the file path is stored as key 0.
Ports
| Port | Name | Description | Read | Write |
|---|---|---|---|---|
B0 |
Namespace | Select a namespace by name. | ✗ | ✓ |
B1 |
Key | Select a key by name. | ✗ | ✓ |
B2 |
Read value | Read value from selected key. | ✗ | ✓ |
B3 |
Write value | Write value to selected key. | ✗ | ✓ |
B4 |
Read queue | Bytes waiting in the read queue. | ✓ | ✗ |
B5 |
Write queue | Bytes free in the write queue. | ✓ | ✓ |
B6 |
Head | Read and write to the access queues. | ✓ | ✓ |
B7 |
aliased | aliased | ✓ | ✓ |
B8 |
Namespace select | Select a namespace by index. | ✓ | ✓ |
B9 |
grouped | grouped | ✓ | ✓ |
BA |
Key select | Select a key by index. | ✓ | ✓ |
BB |
grouped | grouped | ✓ | ✓ |
BC |
Namespace name | Name of the selected namespace. | ✓ | ✓ |
BD |
Key name | Name of the selected key. | ✓ | ✓ |
BE |
Delete namespace | Delete the selected namespace. | ✗ | ✓ |
BF |
Delete key | Delete the selected key. | ✗ | ✓ |
Namespace
Writing each byte of a name to this port followed by a zero byte will select the namespace with that name. Writing an empty name will select the null namespace, which contains arguments passed to the program.
Key
Writing each byte of a name to this port followed by a zero byte will select the key with that name inside the selected namespace. Writing an empty name will select the null key, which cannot be written to.
Read value
Writing a byte to this port will load the value of the selected key into the read queue if the value is the correct type, first clearing the queue. Each value can contain either binary or text data; writing a non-zero byte will load a text value and writing a zero byte will load a binary value.
Write value
Writing a byte to this port will overwrite the value of the selected key with the contents of the write queue, clearing the queue. Each value can contain either binary or text data; writing a non-zero byte will store a text value and writing a zero byte will store a binary value.
Read queue
Reading a byte from this port will return the number of bytes waiting in the read queue.
Write queue
Reading a byte from this port will return the number of bytes of space free in the write queue, and writing any value will clear the queue.
Head
Reading a byte from this port will remove and return a byte from the front of the read queue, and writing a byte will push the byte onto the write queue.
This port is followed by a port alias, allowing double values to be read or written with a single instruction.
Namespace select
Reading a double from this port will return the number of namespaces that contain keys, excluding the null namespace. Writing a double to this port will select the indexed namespace.
Key select
Reading a double from this port will return the number of keys in the selected namespace that have a value. Writing a double to this port will select the indexed key.
Namespace name
Reading from this port will return the next byte from the name of the selected namespace, ending with a zero byte. Writing any value will restart the name from the beginning.
Key name
Reading from this port will return the next byte from the name of the selected key, ending with a zero byte. Writing any value will restart the name from the beginning.
Delete namespace
Writing any value to this port will delete all keys in the selected namespace.
Delete key
Writing any value to this port will delete the selected key.
Wake behaviour
This device will never wake the system from sleep