SplitBit-Emulator/Programs/CosmOS

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.
osBreak	Stops the application, shows every register as it had them, waits for a key, and carries on.
osFileInfo	DP0 names a file; Q reports whether it is there and DP3 returns how many blocks it occupies.
osFileBlock	DP0 names a file, DP1 a destination, and A with B give which block; Q reports success and DP3 returns how many of the block's bytes belong to the file.

osFileInfo and osFileBlock are how an application reads a file too big to hold. A whole file arrives through osFileRead, which cannot help with anything above 64K, and CosmOS's own source is above it. Neither call keeps anything open: each one names the file and says which block it wants, so an application that stops halfway leaves nothing behind. Both report why they failed rather than only that they did - 1 for no disk, 2 for no such file, 3 for a block past the end, and 4 for a disk that would not read - because running off the end is how a reader learns it has finished.

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.