Files

T

AnachronautandClaude Opus 5 3b800a69e8 Monitor: a line assembler

a <address>, then instructions until a line that is just a dot.

The syntax is the assembler's own: a selector rides on the mnemonic as LDA.0
or LDD.0.1, and leaving one off means Data Pointer 0 exactly as it does in a
source file, so nothing learned at the monitor has to be unlearned when
writing a program. Case is folded, since the assembler does not care either.

Numbers are hexadecimal and bare. A source file writes 0x2000 or 0d16 because
it has both and must say which; a monitor has one and says so once, in the
manual, rather than on every line.

It reads the same table the disassembler does, searched the other way round,
which is the point of it being a table rather than two lists: what a writes,
d reads back, and neither can drift from the other or from the assembler both
were generated from. Instruction lengths come from the shared shape table
too, so the cursor cannot get out of step with what was written.

THE WHOLE LINE IS UNDERSTOOD BEFORE ANYTHING IS WRITTEN. Emitting the opcode
first and discovering a missing operand afterwards leaves half an instruction
in memory, which the next line usually covers up and the last line of a
session does not. Written that way first and fixed.

What cannot be written is a label, and that is the whole difference between
this and the assembler proper: a label is a promise to fill an address in
later, and later is what a line at a time does not have.

The recorded test now types in a complete program - a string poked into Data
Memory, instructions assembled into Program Memory, and the result run - and
includes a lower case mnemonic, both selector forms, an instruction that does
not exist and one missing its value, so the refusals sit beside the successes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-19 22:29:50 -04:00

Apps

Break: name the status register properly and show the Stack Pointer

2026-08-19 22:19:15 -04:00

Bin

CosmOS pre-alpha and launchable application versions of old programs.

2026-08-17 15:31:49 -04:00

Source

Monitor: a line assembler

2026-08-19 22:29:50 -04:00

README.md

Monitor: a line assembler

2026-08-19 22:29:50 -04:00

README.md

CosmOS

Overview:

CosmOS is a small, single-tasking disk operating environment for the SplitBit 8-bit computer. It boots the machine, finds and mounts an SBFS filesystem, provides a command line and memory monitor, loads applications from disk, and takes control back when they finish.

CosmOS is written entirely in SplitBit assembly. It is closer in scale and purpose to a resident monitor or an early disk operating system than to a modern multitasking OS: one program owns the machine at a time, there is no privilege boundary, and applications are assembled for fixed regions of memory. What it provides is a stable home from which those programs can be found, run, and given services without each one having to boot the machine for itself.

Features:

Interactive Shell: Read commands from the SplitBit console and continue until exit or the end of input.
SBFS Filesystem: Mount, list, read, write, delete, and rename files on a SplitBit disk.
Loadable Applications: Validate SBEX files, copy their Program and Data segments into the addresses for which they were assembled, and start them at their declared entry point.
Resident Services: Applications can print strings and numbers, read lines, receive their command arguments, read and write files, and return to the shell through named software interrupts.
Application Vectors: Install interrupt vectors carried by a loadable program and restore whatever they replaced when the program exits.
Stack Reclamation: Save the system Stack before launching an application and take it back on exit, so an application need not unwind itself before returning.
Memory Monitor: Inspect and modify Program Memory, Data Memory, and registered device-memory banks through the SplitBit memory controller, disassemble instructions, and begin execution at an address.
Hardware Discovery: Mount the disk through the device registry rather than assuming that one is present at a particular controller bank.
Native Applications: Includes demonstrations, mathematical programs, interactive programs, a game, and a line-oriented text editor.
Reproducible Disk Image: The makefile assembles the system and every application, then constructs a fresh SBFS image containing the resulting executables.

Building and Running:

CosmOS currently lives inside the SplitBit Emulator repository and uses its assembler, emulator, and disk-image tool. From the repository root, build those tools first:

make

Then build CosmOS and all of its applications:

cd Programs
make cosmos

Build a fresh SBFS application disk as well:

make cosmos-disk

To boot CosmOS with that disk attached:

make run-cosmos

The generated files are kept under Programs/build/:

CosmOS/Source/cosmos.bin is the bootable CosmOS image.
CosmOS/Apps/*.sbx are loadable application images.
cosmos.img is the SBFS disk containing those applications.

The disk is rebuilt from scratch when its applications change, so its contents describe the current source tree rather than accumulating files left by older builds.

Shell Commands:

CosmOS currently provides these built-in commands:

Command	Description
`dir`	List the files on the mounted disk and their sizes.
`load <file>`	Read and validate an SBEX application, then place its code and data where its header requests.
`run [words]`	Start the loaded application and make the rest of the line available to it as an argument.
`delete <file>`	Remove a file from the filesystem and release its blocks.
`rename <file> <to>`	Give a file a different name without moving its contents.
`monitor`	Enter monitor mode, in which the prompt becomes `*` and the commands below are also available.
`help`	Show the built-in command summary.
`exit`	Leave monitor mode if in it, and otherwise halt the machine.

Monitor mode adds the following. It is a mode rather than a separate program because a loaded application occupies the one region a loaded application is given, so a monitor which was itself an application could never examine another one. The mode persists: an application started with g which returns through osExit arrives back at the monitor prompt rather than at the shell.

Command	Description
`x [address]`	Display 64 bytes as hexadecimal and as characters.
`d [address]`	Disassemble eight instructions.
`a <address>`	Assemble instructions into memory until a line containing only a dot.
`s <address> <byte>...`	Write bytes into the bank being examined, including Program Memory.
`b <program\|data\|bank>`	Select a memory space or a registered bank number.
`g <address>`	Begin execution at an address.

x and d share a position, and each leaves it after what it displayed, so either may be given without an address to continue from where the last one stopped.

For example:

> dir
> load Snake.sbx
> run

Loading and running are separate operations for now. A loaded program may be run again without being read from disk again, which is useful both as a monitor facility and as a test that CosmOS correctly restores its Stack and vector table after every run.

CosmOS also boots without a disk. It reports that no filesystem was found, leaves the shell and memory monitor available, and refuses commands that require a mounted disk without stopping the machine.

Included Applications:

The application disk is populated from every assembly file in CosmOS/Apps/. At present it includes:

Edit: A line-oriented text editor that can create, load, modify, and save files from inside CosmOS.
Snake: A playable terminal game using nonblocking single-key input.
Life: A 16 by 16 Conway's Game of Life simulation that returns when it settles or reaches its generation limit.
Keys: An interrupt-driven console demonstration carrying its own hardware vector.
Say: Demonstrates receiving the argument supplied to run.
Files: Writes, reads, renames, and deletes a file using only the system's services, including no filesystem code of its own.
greet and hello: Small examples of, respectively, using CosmOS services and talking directly to SplitBit hardware.
Fib-8, Fib-16, and Fib-32: Fibonacci demonstrations at three integer widths.
Sieve-8 and Sieve-16: Prime sieves covering the 8-bit and 16-bit ranges.

These programs are ordinary SBEX files on SBFS. They are not built into the operating system, and the host-side SplitDisk tool can add or remove other files from an image.

The Application Model:

CosmOS divides the two SplitBit address spaces by convention:

Memory	CosmOS	Loaded application
Program Memory	`0x0000` through `0x1FFF`	`0x2000` and above
Data Memory	`0x0000` through `0x0FFF`	`0x1000` and above

Applications state their actual Program and Data addresses with #Base. The SplitBit assembler then writes an SBEX loadable image containing those addresses, the entry point, the segment lengths, and any vectors the application needs. CosmOS does not relocate code: the addresses in the file must be the addresses for which it was assembled.

This division is an ABI convention rather than protection. An application owns the machine while it runs and may address hardware or CosmOS memory directly. The convention keeps independently assembled software out of the system's way; it is not a security boundary.

System Services:

Applications include Source/services.asm to obtain stable names and vector numbers for the services CosmOS provides. The currently installed services are:

Service	Interface
`osPrintString`	DP0 names a zero-terminated string to print.
`osReadLine`	DP0 names a destination and B is its capacity; Q returns the line length.
`osArgument`	DP0 names a destination and B is its capacity; receives the text following `run`.
`osExit`	Abandon the application's Stack, restore the CosmOS environment, and return to the shell.
`osFileRead`	DP0 names a file and DP1 a destination; Q reports success and DP3 returns its length in bytes.
`osFileSave`	DP0 names a file, DP1 supplies its contents, and A with B give the length; Q reports success.
`osFileDelete`	DP0 names a file to remove; Q reports success.
`osFileRename`	DP0 names an existing file and DP1 its new name; Q reports success.
`osPrintNumber`	A with B give a number to print in decimal without leading zeroes.

The filesystem services exist so that an application need not contain a second copy of the filesystem in order to keep a file. There is deliberately no service to mount a disk: the system mounts one before its first prompt, and an application mounting it again was only ever a consequence of owning a private copy of the library.

A minimal CosmOS application therefore looks like this:

#Include services.asm

#Program
  #Base 0x2000

start:
  SETD.0 Message
  SWI osPrintString
  SWI osExit

#Data
  #Base 0x1000

Message:
  "Hello from CosmOS."

An application may also include its own libraries or access hardware ports directly. The services are an interface offered by the system, not the only way software is allowed to use the computer.

Source Layout:

Source/cosmos.asm: Boot process, shell, loader, monitor, system services, and application lifecycle.
Source/console.asm: Console input, strings, hexadecimal and decimal output, and line handling.
Source/text.asm: String comparison, splitting, and hexadecimal text conversion used by the shell.
Source/sbfs.asm: Target-side implementation of the SplitBit filesystem.
Source/services.asm: The shared names and stable vector numbers used by CosmOS and separately assembled applications.
Apps/: Loadable programs packaged onto the CosmOS disk image.

Tests:

CosmOS is exercised as part of the SplitBit repository's normal test suite:

make test

The tests boot the system with and without a disk and drive the shell through recorded console input. They cover directory traversal, every loader refusal, repeated application runs, memory inspection, vector installation and restoration, command arguments, filesystem deletion and renaming, interactive applications, and editing a file followed by reading the saved result back in a second editor session.

Individual CosmOS tests can be run from the repository root, for example:

./Tests/run.sh cosmos cosmosRun cosmosEdit

Test disks are constructed with the host-side SplitDisk tool. CosmOS is therefore reading filesystems written by an independent implementation of the same format rather than merely checking its filesystem code against itself.

Current Scope:

CosmOS is early software for an experimental computer. It runs one application at a time, has no privilege levels or process isolation, does not relocate applications, and provides a line assembler but not yet a native assembler for source files, nor a linker. Its present purpose is to make SplitBit usable from inside the machine: inspect it, manage persistent files, load programs, provide common services, and return reliably to a command prompt.

The intended long-term milestone is self-hosting: editing SplitBit assembly source under CosmOS, assembling and linking it natively, and eventually rebuilding CosmOS and its own development tools on the machine.

Additional Information:

The SplitBit Programming Manual describes the CPU, devices, memory controller, SBFS, SBEX format, interrupt model, and CosmOS service interface. The SplitBit Assembler Manual documents the assembly language, loadable-program bases, and vector declarations.

License:

CosmOS is part of the SplitBit Emulator project and is licensed under the Apache License, Version 2.0. See the repository's top-level LICENSE file for the full license text.