diff --git a/Programs/CosmOS/README.md b/Programs/CosmOS/README.md new file mode 100644 index 0000000..7438a7f --- /dev/null +++ b/Programs/CosmOS/README.md @@ -0,0 +1,270 @@ +# 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: + +```sh +make +``` + +Then build CosmOS and all of its applications: + +```sh +cd Programs +make cosmos +``` + +Build a fresh SBFS application disk as well: + +```sh +make cosmos-disk +``` + +To boot CosmOS with that disk attached: + +```sh +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 ` | 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 ` | Remove a file from the filesystem and release its blocks. | +| `rename ` | 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. | +| `s
...` | Write bytes into the bank being examined, including Program Memory. | +| `b ` | Select a memory space or a registered bank number. | +| `g
` | 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: + +```text +> 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: + +```asm +#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: + +```sh +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: + +```sh +./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 +does not yet provide a native assembler or 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.