Add the CosmOS README, brought up to date with today's changes
Written by Anachronaut and not previously committed. Three things in it had
gone stale between writing and now, and are corrected here rather than
committed knowingly wrong:
- the shell command table still described dump, which the monitor
supersedes, so it now describes monitor mode and its commands
- the service table listed four services, and there are nine
- the application list did not mention Files
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Anachronaut
co-authored by
Claude Opus 5
Claude Opus 5
parent
3e87a67809
commit
b36d438132
@@ -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 <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. |
|
||||||
|
| `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:
|
||||||
|
|
||||||
|
```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.
|
||||||
Reference in New Issue
Block a user