System & Program Control
Overview
The SYS interface provides access to system-level program control, scheduling, and timing services.
Unlike native CPU instructions, SYS verbs are handled by the system controller through the EXT bus. Programs may use them to launch or queue programs, suspend execution, and configure the system clock.
Like other EXT operations, a SYS call completes before execution continues with the next instruction.
Program execution
SYS.RUN, SYS.QUEUE, and SYS.NEXT use the same program invocation format:
SYS.<verb> <program> <entrypoint> [arg...]
The program path is followed by an entrypoint and up to 16 optional arguments.
Entrypoints
Entrypoints are passed as strings and resolved by the program being launched.
If the entrypoint begins with $, it is resolved as a label. Otherwise, it is converted to an integer and used as a line number.
An entrypoint that converts to 0 starts at $ENTRY if one is defined, otherwise at line 1.
SYS.RUN "TOOLS" 50
-- > Starts at line 50
SYS.RUN "TOOLS" "50"
-- > Starts at line 50
SYS.RUN "TOOLS" "$diagnostics"
-- > Starts at $diagnostics
SYS.RUN "TOOLS" 0
-- > Starts at $ENTRY, or line 1
Named entrypoints require the $ prefix. For example, "$10" targets the label $10, while "10" targets line 10.
An unprefixed non-numeric string converts to 0 and therefore selects the default entrypoint.
SYS.RUN "TOOLS" "diagnostics"
-- > Starts at $ENTRY, or line 1
Arguments
Up to 16 arguments may be passed after the entrypoint.
Arguments are stored as strings in the launched program and are available as constants #0 through #15.
Integer values are converted to their string representation before being passed.
SYS.RUN "FIB" 0 15 "Hello"
The launched program receives:
#0 = "15"
#1 = "Hello"
The special constant #THIS contains the program path used to launch the current invocation. It may be used when a program needs to invoke or queue itself again.
SYS.RUN — Run Program
SYS.RUN <program> <entrypoint> [arg...]
Terminates the current program and immediately starts another program.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | program |
String value | — | Program path to run. |
| 2 | entrypoint |
String value | — | Starting line or label. |
| 3–18 | arg... |
String value | — | Optional program arguments. |
Modified registers
This operation does not directly modify any registers.
Examples
-- Run a program at its default entrypoint.
SYS.RUN "CHESS" 0
-- > Starts CHESS at $ENTRY, or line 1
-- Start a program at a specific line.
SYS.RUN "TOOLS" 50
-- > Starts TOOLS at line 50
-- Start a program at a named entrypoint.
SYS.RUN "TOOLS" "$diagnostics"
-- > Starts TOOLS at $diagnostics
-- Pass arguments to a program.
SYS.RUN "FIB" 0 15
-- > FIB receives #0 = "15"
Notes
- The current program does not resume after
SYS.RUN.
SYS.QUEUE — Queue Program
SYS.QUEUE <program> <entrypoint> [arg...]
Adds a program to the back of the execution queue.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | program |
String value | — | Program path to queue. |
| 2 | entrypoint |
String value | — | Starting line or label. |
| 3–18 | arg... |
String value | — | Optional program arguments. |
Modified registers
This operation does not modify any registers.
Examples
-- Add programs to the back of the queue.
SYS.QUEUE "FIB" 0 45
SYS.QUEUE "FIB" 0 46
SYS.QUEUE "FIB" 0 47
-- > Programs run in the order they were queued
Notes
SYS.QUEUEdoes not interrupt the currently running program.
SYS.NEXT — Queue Program Next
SYS.NEXT <program> <entrypoint> [arg...]
Adds a program to the front of the execution queue, causing it to run before programs already waiting in the queue.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | program |
String value | — | Program path to queue. |
| 2 | entrypoint |
String value | — | Starting line or label. |
| 3–18 | arg... |
String value | — | Optional program arguments. |
Modified registers
This operation does not modify any registers.
Examples
-- Add two programs normally.
SYS.QUEUE "SECOND" 0
SYS.QUEUE "THIRD" 0
-- Insert another program ahead of them.
SYS.NEXT "FIRST" 0
-- > Queue order:
-- > FIRST
-- > SECOND
-- > THIRD
-- Queue another invocation of this program.
SYS.NEXT #THIS "$return" "Welcome back!"
Notes
SYS.NEXTdoes not interrupt the currently running program.- Programs added with
SYS.NEXTtake priority over programs already waiting in the queue.
Timing
System timing operations control when program execution continues and how quickly the CPU advances between execution cycles.
SYS.WAIT — Wait Cycles
SYS.WAIT <cycles>
Suspends program execution for the specified number of CPU cycles.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | cycles |
Integer value | ≥ 0 |
Number of cycles to wait. |
Modified registers
This operation does not modify any registers.
Examples
-- Wait for 10 CPU cycles.
SYS.WAIT 10
Notes
SYS.WAITis measured in CPU cycles, not seconds.- The amount of real time represented by a cycle depends on the current CPU clock rate.
SYS.CLOCKtherefore affects the approximate real-time duration ofSYS.WAIT.
SYS.SLEEP — Sleep
SYS.SLEEP <seconds>
Suspends program execution for at least the specified number of seconds.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | seconds |
Integer value | ≥ 0 |
Minimum number of seconds to sleep. |
Modified registers
This operation does not modify any registers.
Examples
-- Sleep for at least 5 seconds.
SYS.SLEEP 5
Notes
SYS.SLEEPspecifies a minimum duration in seconds.- Execution resumes on a subsequent CPU cycle after the requested duration has elapsed.
- The configured clock rate can therefore increase the effective sleep duration.
- For example, with
SYS.CLOCK 10000,SYS.SLEEP 1may effectively pause execution for about 10 seconds.
SYS.CLOCK — Clock Rate
SYS.CLOCK <delay>
Sets the CPU clock rate by specifying the delay, in milliseconds, between execution cycles.
Operands
| Position | Name | Type | Range | Description |
|---|---|---|---|---|
| 1 | delay |
Integer value | 50–30000 |
Delay between CPU cycles in milliseconds. |
Modified registers
This operation does not modify any registers.
Examples
-- Run with 50 ms between cycles.
SYS.CLOCK 50
-- Run with 1 second between cycles.
SYS.CLOCK 1000
Notes
- A smaller delay produces a faster clock; a larger delay produces a slower clock.
SYS.CLOCKdirectly affectsSYS.WAIT, which is measured in CPU cycles.SYS.CLOCKcan indirectly extendSYS.SLEEP, because execution resumes on a CPU cycle only after the requested sleep duration has elapsed.