Rewrite the README around what the system is now

It had become a geological record. The overview was the 2024 one - "load and run binary programs created for SplitBit interactively from the command line" - and the feature list had grown by accretion, so it opened with Debug Mode, CLI Based and Modular Codebase and buried self-hosting at bullet fourteen of seventeen. Three sections were called "Usage". Now it opens with what the machine is and the one fact that makes it worth looking at, with the transcript underneath. The features are grouped into the machine and the software running on it, and the bullets that said nothing are gone: "Binary File Support" and "CLI Based" describe every emulator ever written. The three tools have names in their headings rather than three identical "Usage" ones, and their options are tables rather than bullet lists. There is a map of the repository, which there was not before and which the last two commits made worth having. TWO THINGS IT WAS SAYING THAT WERE NO LONGER TRUE, and nothing checks the README so nothing caught them: "it is still the only way to get a program onto a disk, since nothing running on the machine assembles anything yet" - SplitDisk has not been the only way for two days. "this is what a self-hosted assembler will stand on" - future tense about something that has since happened. The Tests section also claimed five checking scripts and then listed makedisks.sh among them, which builds fixtures rather than checking anything. It is four checks and a runner. Every command in it was run: assembling hello.asm and running the result, and booting the disk to see Snake.sbx load. Three em dashes crept in and were taken out - the whole tracked repository is plain ASCII again, which is now verified rather than assumed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
2026-08-21 13:46:59 -04:00
parent ccf4b384e1
commit 518be9cb17
1 changed files with 138 additions and 85 deletions
@@ -1,142 +1,195 @@
-# SplitBit Emulator
+# SplitBit
-## Overview:
+SplitBit is an 8 bit computer that does not exist: a CPU with its own instruction set, split Program and Data memories, an interrupt and vector system, a bus that programs can enumerate, a memory controller that can write code into memory, and a disk. This repository is a C implementation of the machine, an assembler for it, a tool for its disks, and the software that runs on it, which now includes an operating system and an assembler written in SplitBit's own assembly language.
 SplitBit is a custom 8 bit system designed for hobbyist projects and experimentation: a CPU with its own instruction set, an interrupt and vector system, a bus that programs can enumerate, and a memory controller that can load code. The SplitBit Emulator is a C implementation of it. It allows users to load and run binary programs created for SplitBit interactively from the command line.
-### Features:
+**SplitBit assembles SplitBit.** `Programs/CosmOS/Assembler/` runs on the machine, reads source off a SplitBit disk, and writes a binary back to it with no host involved. It builds the operating system it is running under, and it builds itself, both byte for byte identical to what the C assembler produces from the same source. The test suite then boots the CosmOS that CosmOS built and has *that* one assemble CosmOS again, and the second generation is identical to the first, so the machinery has been through itself. After that the host is a convenience rather than a necessity.
- 8-bit Harvard Architecture: The system memory is separated into two 64k banks, one for the Program Memory and another for the Data Memory.
+
- Custom ISA: A fully implemented instruction set architecture optimized for simplicity and easy assembly programming.
+```
- Debug Mode: Single-step through instructions and monitor the CPU's registers as they change through each cycle.
+> load Asm.sbx
- CLI Based: Debug messages and CPU input and output are supported through the command line.
+> run cosmos.asm
- Binary File Support: Load programs and data from binary files.
+wrote cosmos.bin: program 7036, data 2448, labels 475
- Modular Codebase: Mostly clean separation of CPU, I/O, and utility functions for easy modification.
+> run Asm.asm
- Interrupts: Software traps, hardware lines from devices, and faults, all arriving through one vector table with a full context save.
+wrote Asm.sbx: program 7533, data 4099, labels 555
- Devices: A bus registry that says what a machine is made of, so a program can ask rather than being told.
+```
- Filesystem: SBFS, read and written by SplitBit itself, and by a host tool that speaks the same format so an image can be moved either way.
+
- Loadable Programs: A program that was not booted from carries a header saying where it belongs, and Programs/Loader/loader.asm reads one off a disk, puts it there, and runs it.
+## What Is In Here:
- An Operating System: CosmOS boots the machine, mounts a disk, lists what is on it, loads a program and runs it, and takes the machine back when it finishes. It comes with a library of programs to run, including a game and a line editor that writes files a person typed.
+
- System Services: A loaded program reaches the console and the disk through numbered software interrupts rather than carrying a copy of the code that drives them. The numbers are written down in one file that both sides include, so neither ever types one. It took the editor from 4941 bytes to 1983 without changing a line of what it does.
+| Directory | What it holds |
- A Native Assembler: SplitBit assembles SplitBit. Programs/CosmOS/Assembler/ is an assembler written in SplitBit assembly that runs under CosmOS, reads source off a SplitBit disk, and writes a binary back to it with no host involved. It builds boot images and loadable applications, following every directive the language has. IT ASSEMBLES COSMOS, AND IT ASSEMBLES ITSELF, both byte for byte identical to what the C assembler produces from the same source. Tests/native.sh then boots the CosmOS that CosmOS built and has that one assemble CosmOS again, so the machinery has been through itself: after that the host is a convenience rather than a necessity.
+| --- | --- |
- Streaming Reads: A file bigger than the machine's memory is read a block at a time, through services that keep nothing open between calls. CosmOS's own source is 104K against 64K of Data Memory, so this is what a self-hosted assembler will stand on.
+| `Source/Emulator` | The machine: CPU, memory controller, devices, console, disk |
- Storage: A block device with 256 byte blocks and 16 megabytes of them, backed by an image file on the host. It knows blocks and not files, because a filesystem is meant to be software SplitBit runs.
+| `Source/Assembler` | The assembler that runs on a host |
- Memory Controller: Reads and writes Program Memory, moves blocks between memory banks, reaches memory that devices bring with them, and guards a range against being written by accident. It is how a SplitBit machine loads a program.
+| `Source/DiskTool` | SplitDisk, which reads and writes SplitBit's filesystem |
- Assembler: Assemble human readable assembly language files directly into SplitBit compatible binary files. Supports including external files, handling labels, alignment and reservation, and defining Program, Data and Vector segments.
+| `Programs/Examples` | Programs to read: hello, a calculator, Fibonacci, a prime sieve, Life |
 | `Programs/Libraries` | Code included by name rather than linked, since there is no linker |
 | `Programs/Loader` | The standalone loader CosmOS grew out of |
 | `Programs/CosmOS` | The operating system, its applications, and the native assembler |
 | `Programs/testPrograms` | What the test suite drives |
 | `Tests` | The suite: the manifest, the recorded output, and the scripts that check it |
 ## The Machine:
 - **Harvard architecture.** Two 64K memories, one for instructions and one for data. An instruction can only read the second, which is why strings live there and why the memory controller exists.
 - **Its own instruction set**, 64 instructions, four Data Pointers, and a Q register that holds what the ALU last worked out. Small enough that the table describing it fits in the machine's own memory, which is what lets it disassemble and assemble for itself.
 - **Interrupts.** Software traps, hardware lines from devices, and faults, all arriving through one vector table with a full context save.
 - **A bus programs can enumerate**, so a program can ask what a machine is made of rather than being told.
 - **A memory controller** that reads and writes Program Memory, moves blocks between banks, reaches memory that devices bring with them, and guards a range against being written by accident. It is how a SplitBit machine loads a program.
 - **Storage**: a block device with 256 byte blocks and up to 16 megabytes of them, backed by an image file. It knows blocks and not files, because a filesystem is meant to be software SplitBit runs.
 ## The Software:
 - **SBFS**, a filesystem read and written by SplitBit itself and by a host tool that speaks the same format, so an image can be moved either way and each implementation checks the other.
 - **CosmOS**, an operating system: it boots the machine, mounts a disk, lists what is on it, loads a program and runs it, and takes the machine back when the program finishes. It comes with a library of programs including a game, a line editor, and a monitor that examines memory, disassembles, assembles a line at a time, and sets breakpoints.
 - **Loadable programs.** A program that was not booted from carries a header saying where it belongs, and may bring interrupt handlers of its own for the loader to install and take back again.
 - **System services.** A loaded program reaches the console and the disk through numbered software interrupts rather than carrying a copy of the code that drives them. The numbers are written down in one file both sides include, so neither ever types one. It took the editor from 4941 bytes to 1983 without changing a line of what it does.
 - **Streaming reads.** A file bigger than the machine's memory is read a block at a time, through services that keep nothing open between calls. CosmOS's own source is far larger than its 64K of Data Memory, and this is what the native assembler stands on.
 ## Getting Started:
 Clone it and build the three tools. You need gcc and make, or similar:
 ### Installation:
 1) Clone the repository:
 ```
 git clone https://github.com/RealBusinessAccount/SplitBit-Emulator.git
 cd SplitBit-Emulator
 ```
 2) Build the Emulator, the Assembler and the disk tool: You'll need gcc and make or similar.
 ```
 make
 ```
-The sources are ISO C, and build clean under -std=c11 -pedantic with -Wall -Wextra. Beyond ISO C they need POSIX.1-2008, which the makefile asks for by name, and getopt_long for the long form of the command line options.
+
-3) Assemble a program:
+The sources are ISO C and build clean under `-std=c11 -pedantic` with `-Wall -Wextra`. Beyond ISO C they need POSIX.1-2008, which the makefile asks for by name, and `getopt_long` for the long form of the command line options.
 Assemble something and run it:
 ```
 ./Assembler Programs/Examples/hello.asm
 ```
 4) Run the program:
 ```
 ./SplitBit hello.bin
 ```
-### Usage:
+Or boot the operating system, with a disk of programs and all of its own source on it:
 ```
 cd Programs
 make run-cosmos
 ```
 Then `dir` to see what is there, `load Snake.sbx` and `run` to play something, or `load Asm.sbx` and `run cosmos.asm` to watch the machine build itself.
 ## Running Programs: SplitBit
 ```
 ./SplitBit [options] [binary file]
 ```
 #### Options:
 - -d, --debug: Enable debug mode to single step through cycles. Each key press advances one instruction.
 - -c, --cycles N: Stop after N cycles rather than running until the program halts. Useful for programs that never halt, and for getting the same output from a run every time.
 - -f, --fast: Run as fast as the host machine allows, ignoring the emulated cycle rate.
 - -D, --disk \<file\>: Attach a disk image, creating a 128K one if the file is not there.
 - -W, --write-protect: Attach the disk read only. A disk whose image the host will not let you write is read only whether you ask for this or not.
 - -h, --help: Show help and usage information.
-#### Notes:
+| Option | What it does |
- If the CPU reads a byte that is not an instruction, it goes to the fault handler the program installed. If it installed none, it raises the Fault Flag and halts, and the emulator reports the byte and the address it was found at and exits with a non zero status. The same happens if a program or a device asks for a handler that was never installed.
+| --- | --- |
 | `-d`, `--debug` | Single step through cycles. Each key press advances one instruction. |
 | `-c`, `--cycles N` | Stop after N cycles rather than running until the program halts. Useful for programs that never halt, and for getting the same output from a run every time. |
 | `-f`, `--fast` | Run as fast as the host allows, ignoring the emulated cycle rate. |
 | `-D`, `--disk <file>` | Attach a disk image, creating a 128K one if the file is not there. |
 | `-W`, `--write-protect` | Attach the disk read only. A disk whose image the host will not let you write is read only whether you ask for this or not. |
 | `-h`, `--help` | Show help and usage information. |
-### Usage:
+If the CPU reads a byte that is not an instruction, it goes to the fault handler the program installed. If it installed none, it raises the Fault Flag and halts, and the emulator reports the byte and the address it was found at and exits with a non zero status. The same happens if a program or a device asks for a handler that was never installed.
 ```
 ./SplitDisk <command> <image> [arguments]
 ```
 #### Commands:
 - format \<image\> [blocks] [dirblocks]: Lay down a fresh filesystem. 512 blocks and 8 of directory by default, which is 128K and room for 64 files.
 - list \<image\>: Show what is on the disk.
 - put \<image\> \<file\> [name]: Put a host file onto it. Without a name it uses the file's own, which is often longer than the 22 characters a name may be.
 - get \<image\> \<name\> [file]: Take one off it.
 - delete \<image\> \<name\>: Remove one.
-#### Notes:
+## Assembling: Assembler
 - SplitDisk speaks the same on disk format SplitBit does, so an image it makes is one the machine can read, and one the machine writes is one it can read back. SplitBit writes its own filesystem now, so this is not the only way to get something onto a disk; it is still the only way to get a program onto one, since nothing running on the machine assembles anything yet.
 - Files are laid down contiguously, so a disk can have free blocks without having them in one piece. When that happens put says so rather than putting part of a file on.
 ### Usage:
 ```
 ./Assembler [options] [assembly file]
 ```
 #### Options:
 - -o \<file\>: Write the binary to this path.
 - -I \<dir\>: Look in this directory for included files. May be given more than once.
 - -M \<file\>: Write out which source files the binary depends on, as a make rule.
 - -h, --help: Show help and usage information.
-#### Notes:
+| Option | What it does |
- Without -o, the assembled binary is saved with the same name as the assembly source file, with a .bin extension, in the directory that you call the assembler from.
+| --- | --- |
- Included files are looked for beside the file that includes them, and then along the directories given with -I.
+| `-o <file>` | Write the binary to this path. |
 | `-I <dir>` | Look in this directory for included files. May be given more than once. |
 | `-M <file>` | Write out which source files the binary depends on, as a make rule. |
 | `-h`, `--help` | Show help and usage information. |
-### Building Programs With Make:
+Without `-o` the binary takes the source file's name with a `.bin` extension, in the directory you called the assembler from. Included files are looked for beside the file that includes them, and then along the directories given with `-I`.
-The assembler is built to work with make. The -o option puts the binary where the build system wants it, and -M writes out which libraries went into it, so that editing a library reassembles everything that includes it.
+
 ## Managing Disks: SplitDisk
 ```
 ./SplitDisk <command> <image> [arguments]
 ```
 | Command | What it does |
 | --- | --- |
 | `format <image> [blocks] [dirblocks]` | Lay down a fresh filesystem. 512 blocks and 8 of directory by default, which is 128K and room for 64 files. |
 | `list <image>` | Show what is on the disk. |
 | `put <image> <file> [name]` | Put a host file onto it. Without a name it uses the file's own, which is often longer than the 22 characters a name may be. |
 | `get <image> <name> [file]` | Take one off it. |
 | `delete <image> <name>` | Remove one. |
 SplitDisk speaks the same on disk format SplitBit does, so an image it makes is one the machine can read, and one the machine writes is one it can read back. It is a convenience rather than a necessity: SplitBit writes its own filesystem, and now assembles its own programs, so a disk can be filled without leaving the machine.
 Files are laid down contiguously, so a disk can have free blocks without having them in one piece. When that happens `put` says so rather than putting part of a file on.
 ## Building Programs With Make:
 The assembler is built to work with make. `-o` puts the binary where the build system wants it, and `-M` writes out which libraries went into it, so that editing a library reassembles everything that includes it.
 `Programs/makefile` does this for the programs in this repository:
 Programs/makefile does this for the programs in this repository:
 ```
 cd Programs
 make
 ```
 The rule it uses is small enough to copy into your own projects:
 ```
 $(BUILD)/%.bin: %.asm
 	@mkdir -p $(@D)
-	$(ASM) -I Libraries -M $(@:.bin=.d) -o $@ $<
+	$(ASM) $(INCLUDES) -M $(@:.bin=.d) -o $@ $<
 -include $(BINARIES:.bin=.d)
 ```
-### Tests:
+## Tests:
-The test suite assembles and runs every program in Programs/ and compares the results against recorded output.
+
 ```
 make test
 ```
 Disk images that tests read from are built by Tests/makedisks.sh before the run, using SplitDisk. A test that reads one is therefore checked against a filesystem written by different code from the same written format, rather than against itself.
-The disk tool is checked separately by Tests/disk.sh, which make test runs afterwards: it puts files of every awkward size onto an image and takes them off again, and checks that the things the format says cannot happen are refused.
+The suite assembles and runs every program in `Programs/` and compares the results against recorded output. Tests are defined in `Tests/manifest`, one line per program. To record the current output as the expected result, after you have checked that it is correct:
 Tests/terminal.sh checks the things a recorded output cannot see. Every other test pipes input in and output to a file, which answers what a program prints and is blind to two whole classes of behaviour: **when** something is printed, since piped output is buffered and flushed at exit, so a prompt shown before its answer is asked for and one shown an hour late produce identical files; and **what happens to the terminal**, since key mode only touches one when there is one. Both have gone wrong here, and both were found by a person whose terminal stopped working rather than by anything in this suite. So it runs the emulator under a pseudo-terminal and asks the questions directly: that a prompt arrives before input is read, that a keystroke arrives without Return, that the terminal is handed back however the machine dies, and that suspending and resuming leave it as they found it.
 A cycle count is deliberately **not** part of a recorded result. The last line of the emulator's output has the number taken out of it before anything is compared, keeping only whether the program stopped on its own or ran into its limit, which is behaviour. Two instructions added to CosmOS used to move that number in six unrelated files at once, so a real difference would arrive in a crowd of meaningless ones. Anything that wants to measure cycles should say so in a test of its own.
 Tests/docs.sh then checks the manuals against the code: that every instruction has a row and every row is an instruction, that the counts in the headings are right, that every directive is written down, that every routine the manuals promise exists, and that the worked examples still assemble to the bytes printed beside them. Documentation goes stale quietly, and this is what stops it.
 Tests are defined in Tests/manifest, one line per program. To record the current output as the expected result, after you have checked that it is correct:
 ```
 make bless
 ```
-Programs are built inside Tests/build, so running the suite never overwrites the binaries in Programs/. To run only some of the tests, call the runner directly with their names:
+
 Programs are built inside `Tests/build`, so running the suite never overwrites anything in `Programs/`. To run only some of the tests, call the runner directly with their names:
 ```
 ./Tests/run.sh hello 8bitFibonacci
 ```
 The disk images tests read from are built first by `Tests/makedisks.sh`, using SplitDisk. A
 test that reads one is therefore checked against a filesystem written by different code from
 the same written specification, rather than against itself.
 `Tests/run.sh` drives that comparison. Four more scripts run alongside it, and each exists
 because a recorded file cannot answer its question:
 - **`Tests/disk.sh`** checks the disk tool on its own: files of every awkward size onto an image and off again, and the things the format says cannot happen refused rather than half done.
 - **`Tests/terminal.sh`** checks what a recorded file cannot see. Piped output is buffered and flushed at exit, so a prompt shown before its answer is asked for and one shown an hour late produce identical files; and key mode only touches a terminal when there is one. Both have gone wrong here, and both were found by a person whose terminal stopped working rather than by anything in this suite. So it runs the emulator under a pseudo-terminal and asks directly: that a prompt arrives before input is read, that a keystroke arrives without Return, that the terminal is handed back however the machine dies, and that suspending and resuming leave it as they found it.
 - **`Tests/native.sh`** checks the assembler that runs on SplitBit against the one that runs on the host, byte for byte, on a boot image and four loadable programs, and then on CosmOS and on itself, and then on the CosmOS that CosmOS built.
 - **`Tests/docs.sh`** checks the manuals against the code: that every instruction has a row and every row is an instruction, that the counts in the headings are right, that every directive is written down, that every service the system implements is described and every service described is implemented, that every routine the manuals promise exists, and that the worked examples still assemble to the bytes printed beside them.
 A cycle count is deliberately **not** part of a recorded result. The last line of the emulator's output has the number taken out before anything is compared, keeping only whether the program stopped on its own or ran into its limit, which is behaviour. Two instructions added to CosmOS used to move that number in six unrelated files at once, so a real difference would have arrived in a crowd of meaningless ones. Anything that wants to measure cycles should say so in a test of its own.
 To rebuild both tools with the address and undefined behaviour sanitizers and run the suite under them:
 ```
 make sanitize
 ```
 This catches reads and writes past the end of an array, use after free, leaks, and undefined arithmetic. It also fills fresh allocations with a junk pattern, which turns a read of uninitialised memory from something that quietly works into something the tests notice. It takes about twice as long as make test, and puts the ordinary binaries back when it finishes.
-### Additional Info:
+This catches reads and writes past the end of an array, use after free, leaks, and undefined arithmetic. It also fills fresh allocations with a junk pattern, which turns a read of uninitialised memory from something that quietly works into something the tests notice. It takes about twice as long as `make test`, and puts the ordinary binaries back when it finishes.
 For more information on the custom ISA and programming for SplitBit, see the Programming Manual and Assembler Manual.
-### License:
+## Documentation:
-This project is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).
+
 The **SplitBit Programming Manual** describes the machine: the instruction set, the vector table, interrupts, devices, the memory controller, the console, storage, and what a program may ask the system for.
 The **SplitBit Assembler Manual** describes the language: literal values, labels, segments, the directives, and the assembler that runs on SplitBit itself.
 `Programs/CosmOS/README.md` describes the operating system from the inside.
 ## License:
 Apache License, Version 2.0. You may obtain a copy at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).