System device

This is the user manual for the system 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 system device specification will provide more relevant information.

Overview

The system device provides information about the Bedrock system, including system and author names, memory limits, and the available devices. It also allows the program to be paused until an event occurs on another device, and for a new instance of the program to be forked.

Concepts

The Bedrock system can be put to sleep by writing to the sleep port, pausing the program until an event occurs on one of the other devices. The system can listen out for events on any combination of devices, ignoring all other devices, and when the system does wake, the device responsible for the wake can be found by reading the wake port.

The name, authors, and device name ports provide information about the system as a UTF-8 encoded string. Reading from one of these ports will return the next byte of the string, with a zero byte marking the end of the string, and writing to the port will restart the string from the beginning.

The sleep and connected devices ports each use double values to represent lists of devices. Each bit of a double represents one of the devices connected to this system, starting with the system device at bit 8000, and a device is included in the list if the bit representing it is set. The following table shows the bits associated with each device:

Ports

Sleep

Writing a double to this port will pause the program until an event occurs on a device. The double determines which devices are permitted to wake the system, with each bit representing one of the sixteen devices, starting with the system device at bit 8000. Refer to the table under the Concepts section for the full bit mapping.

See the waiting for a device event example.

Wake

Reading from this port will return the slot number of the device that last woke the system, with the system device being slot number 00.

See the waiting for a device event example.

Fork

Writing a zero byte to this port will reset the Bedrock system, clearing the stacks and resetting all devices. The contents of the program memory will be preserved, and the program will start running again from address zero.

Writing a non-zero byte to this port will fork the Bedrock system. A new program window will open, the contents of the program memory will be copied into the new window, and the program in the existing window will continue to run as normal. The program in the new window will start running from address zero.

Device name

Each of the four device name ports provide the name of one of the four custom devices connected to this Bedrock system as a UTF-8 encoded string. Reading from one of these ports will return the next byte of that string, with a zero byte marking the end of the string, and writing any value will restart the string from the beginning. If no device is connected, the string will be empty.

See the reading a string example.

Name

This port provides the name and version of this Bedrock system as a UTF-8 encoded string. The name and version are separated by a slash, in the format bedrock-pc/1.0.0. Reading a byte from this port will return the next byte of the string, with a zero byte marking the end of the string, and writing any value will restart the string from the beginning.

See the reading a string example.

Authors

This port provides a list of names of the authors of this Bedrock system as a UTF-8 encoded string. Every name but the last is separated from the next by a newline character. Reading a byte from this port will return the next byte of the string, with a zero byte marking the end of the string, and writing any value will restart the string from the beginning.

See the reading a string example.

Program memory

Reading a double from this port will return the number of bytes of program memory available on this Bedrock system. This will return zero on most systems, indicating that all 65536 bytes are available.

Working stack

Reading a byte from this port will return the number of bytes of working stack memory available on this Bedrock system. This will return zero on most systems, indicating that all 256 bytes are available.

Return stack

Reading a byte from this port will return the number of bytes of return stack memory available on this Bedrock system. This will return zero on most systems, indicating that all 256 bytes are available.

Connected devices

Reading a double from this port will return a double representing the list of devices that are currently connected to this Bedrock system. Each bit represents one of the sixteen devices, starting from the system device at bit 8000. Refer to the table under the Concepts section for the full bit mapping.

Wake behaviour

This device will immediately wake the system from sleep. This is useful for triggering behaviours that only occur when the system is put to sleep, without having to stop the program.

Examples

Waiting for a device event

When a program needs to wait for an input, the program can be paused by writing to the sleep port, waking up when new input has been received on one of the chosen devices. The value written to the sleep port determines which devices are permitted to wake the system.

This example uses the value 1000, which represents the clock device:

@start
  :'.' STD:86     ( print a dot to the terminal      )
  *:0040 STD*:38  ( set timer for a quarter second   )
  *:1000 STD*:00  ( sleep until a clock event occurs )
  JMP:start       ( loop back to the start           )

This example uses the value 1800, which represents both the clock and input devices. When the system wakes, the wake port is checked to see which device was responsible:

JMS:on-clock  ( start the timer )

@start
  *:1800 STD*:00 LDD:02
  DUP EQU:03 JCS:on-clock
  DUP EQU:04 JCS:on-input
  POP JMP:start

@on-clock  ( -- )
  *:0040 STD*:38    ( set timer for a quarter second )
  :'C' STD:86 JMPr  ( print a C to the terminal      )

@on-input  ( -- )
  :'I' STD:86 JMPr  ( print an I to the terminal     )

Reading a string

The name, authors, and device name ports each provide information about the Bedrock system as a UTF-8 encoded string. To read a string from one of these ports, we write a byte to the port to restart the string, and then we read bytes from the port until a zero byte is returned:

:08 JMS:print-device-string HLT

@print-device-string  ( port -- )
  OVR:00 STD            ( port ) ( write zero byte to the port )
  STA:~port JMP:~start  (      ) ( store port in program, jump )
  &loop                 ( char )
    STD:86 &start       (      ) ( write char to the terminal  )
    LDD:[&port 00]      ( char ) ( load next char from port    )
    DUP JCN:~loop       ( char ) ( loop if char is not zero    )
  POP JMPr              (      ) ( clear the stack, return     )