diff --git a/Programs/Fibonacci/16bitFibonacci.asm b/Programs/Examples/Fibonacci/16bitFibonacci.asm similarity index 100% rename from Programs/Fibonacci/16bitFibonacci.asm rename to Programs/Examples/Fibonacci/16bitFibonacci.asm diff --git a/Programs/Fibonacci/32bitFibonacci.asm b/Programs/Examples/Fibonacci/32bitFibonacci.asm similarity index 100% rename from Programs/Fibonacci/32bitFibonacci.asm rename to Programs/Examples/Fibonacci/32bitFibonacci.asm diff --git a/Programs/Fibonacci/8bitFibonacci.asm b/Programs/Examples/Fibonacci/8bitFibonacci.asm similarity index 100% rename from Programs/Fibonacci/8bitFibonacci.asm rename to Programs/Examples/Fibonacci/8bitFibonacci.asm diff --git a/Programs/gameOfLife/16x16Life.asm b/Programs/Examples/gameOfLife/16x16Life.asm similarity index 100% rename from Programs/gameOfLife/16x16Life.asm rename to Programs/Examples/gameOfLife/16x16Life.asm diff --git a/Programs/gameOfLife/16x16LifeModern.asm b/Programs/Examples/gameOfLife/16x16LifeModern.asm similarity index 100% rename from Programs/gameOfLife/16x16LifeModern.asm rename to Programs/Examples/gameOfLife/16x16LifeModern.asm diff --git a/Programs/hello.asm b/Programs/Examples/hello.asm similarity index 100% rename from Programs/hello.asm rename to Programs/Examples/hello.asm diff --git a/Programs/inputTest.asm b/Programs/Examples/inputTest.asm similarity index 100% rename from Programs/inputTest.asm rename to Programs/Examples/inputTest.asm diff --git a/Programs/primeSieve/16bitSegmentedSieve.asm b/Programs/Examples/primeSieve/16bitSegmentedSieve.asm similarity index 100% rename from Programs/primeSieve/16bitSegmentedSieve.asm rename to Programs/Examples/primeSieve/16bitSegmentedSieve.asm diff --git a/Programs/primeSieve/16bitSegmentedSieveModern.asm b/Programs/Examples/primeSieve/16bitSegmentedSieveModern.asm similarity index 100% rename from Programs/primeSieve/16bitSegmentedSieveModern.asm rename to Programs/Examples/primeSieve/16bitSegmentedSieveModern.asm diff --git a/Programs/primeSieve/8bitSieve.asm b/Programs/Examples/primeSieve/8bitSieve.asm similarity index 100% rename from Programs/primeSieve/8bitSieve.asm rename to Programs/Examples/primeSieve/8bitSieve.asm diff --git a/Programs/printHello.asm b/Programs/Examples/printHello.asm similarity index 100% rename from Programs/printHello.asm rename to Programs/Examples/printHello.asm diff --git a/Programs/replCalculator.asm b/Programs/Examples/replCalculator.asm similarity index 100% rename from Programs/replCalculator.asm rename to Programs/Examples/replCalculator.asm diff --git a/Programs/loadable/hello.asm b/Programs/Loader/loadable.asm similarity index 100% rename from Programs/loadable/hello.asm rename to Programs/Loader/loadable.asm diff --git a/Programs/loader.asm b/Programs/Loader/loader.asm similarity index 100% rename from Programs/loader.asm rename to Programs/Loader/loader.asm diff --git a/Programs/makefile b/Programs/makefile index e01ba47..527624e 100644 --- a/Programs/makefile +++ b/Programs/makefile @@ -16,23 +16,27 @@ BUILD ?= build # CosmOS owns the filesystem library and the service names, so it is a place to look too. INCLUDES = -I Libraries -I CosmOS/Source -# The programs worth building. Files in Libraries/ are left out because they have no -# entry point of their own, and the ones in testPrograms/ are covered by 'make test' -# in the parent directory. +# The programs worth building. Every one lives in a directory that says what kind it is: +# Examples/ is what you read to learn, Loader/ is the standalone loader CosmOS grew out of, +# CosmOS/ is the system. Files in Libraries/ are left out because they have no entry point +# of their own, and the ones in testPrograms/ are covered by 'make test' in the parent +# directory. PROGRAMS = \ CosmOS/Source/cosmos.asm \ - hello.asm \ - printHello.asm \ - inputTest.asm \ - replCalculator.asm \ - Fibonacci/8bitFibonacci.asm \ - Fibonacci/16bitFibonacci.asm \ - Fibonacci/32bitFibonacci.asm \ - primeSieve/8bitSieve.asm \ - primeSieve/16bitSegmentedSieve.asm \ - primeSieve/16bitSegmentedSieveModern.asm \ - gameOfLife/16x16Life.asm \ - gameOfLife/16x16LifeModern.asm + Examples/hello.asm \ + Examples/printHello.asm \ + Examples/inputTest.asm \ + Examples/replCalculator.asm \ + Examples/Fibonacci/8bitFibonacci.asm \ + Examples/Fibonacci/16bitFibonacci.asm \ + Examples/Fibonacci/32bitFibonacci.asm \ + Examples/primeSieve/8bitSieve.asm \ + Examples/primeSieve/16bitSegmentedSieve.asm \ + Examples/primeSieve/16bitSegmentedSieveModern.asm \ + Examples/gameOfLife/16x16Life.asm \ + Examples/gameOfLife/16x16LifeModern.asm \ + Loader/loader.asm \ + Loader/loadable.asm BINARIES = $(PROGRAMS:%.asm=$(BUILD)/%.bin) DEPENDENCIES = $(BINARIES:.bin=.d) diff --git a/README.md b/README.md index e38f12e..b2bb7f9 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ SplitBit is a custom 8 bit system designed for hobbyist projects and experimenta - Interrupts: Software traps, hardware lines from devices, and faults, all arriving through one vector table with a full context save. - 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.asm reads one off a disk, puts it there, and runs it. +- 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. - 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. - 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. @@ -35,7 +35,7 @@ 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: ``` -./Assembler Programs/hello.asm +./Assembler Programs/Examples/hello.asm ``` 4) Run the program: diff --git a/SplitBit Assembler Manual.md b/SplitBit Assembler Manual.md index 3e9dbb7..2b07b46 100644 --- a/SplitBit Assembler Manual.md +++ b/SplitBit Assembler Manual.md @@ -306,7 +306,7 @@ An absolute path is taken as it is written. If the file turns up nowhere, the as Because a library is normally referred to by name alone, a program that uses one has to be told where the libraries live: ``` -Assembler -I Libraries primeSieve/8bitSieve.asm +Assembler -I Libraries Examples/primeSieve/8bitSieve.asm ``` Including the same file twice does nothing the second time, so two libraries may both depend on a third without the program that uses them having to know. The assembler compares files by where they really are rather than by how they were spelled, so the same library reached by two different routes is still only assembled once. @@ -491,7 +491,7 @@ wrote hello.bin: program 17, data 14, labels 2 Loading and running are separate commands in CosmOS, so the source file is the argument to `run`. -**Its output must be byte for byte what the host assembler produces from the same source**, and `Tests/native.sh` checks exactly that: it assembles `Programs/hello.asm` both ways and compares the files, then runs the one the machine built. This is the discipline SplitDisk and `sbfs.asm` already work under — two implementations of one written specification, each one checking the other. "It ran" is not good enough for an assembler, because a binary with a label one byte out runs right up until it jumps into the middle of an instruction. +**Its output must be byte for byte what the host assembler produces from the same source**, and `Tests/native.sh` checks exactly that: it assembles `Programs/Examples/hello.asm` both ways and compares the files, then runs the one the machine built. This is the discipline SplitDisk and `sbfs.asm` already work under — two implementations of one written specification, each one checking the other. "It ran" is not good enough for an assembler, because a binary with a label one byte out runs right up until it jumps into the middle of an instruction. ### How It Differs Inside: diff --git a/SplitBit Programming Manual.md b/SplitBit Programming Manual.md index a7c96cd..dca7ace 100644 --- a/SplitBit Programming Manual.md +++ b/SplitBit Programming Manual.md @@ -688,7 +688,7 @@ A program that was not the one the machine booted from carries sixteen bytes in | 14 | 2 | How many bytes of data there are. | | 16 | | The code, then the data, then the vectors. | -Programs/loader.asm reads one off a disk, puts the two pieces where the header asks, and jumps to the entry with BRD. Every part of that already existed: the filesystem finds the file, the memory controller writes Program Memory, and BRD turns an address worked out at run time into somewhere to go. The header is the only new thing. Programs/CosmOS does the same as one of its commands, and then takes the machine back afterwards, which the standalone loader has no way to do. +Programs/Loader/loader.asm reads one off a disk, puts the two pieces where the header asks, and jumps to the entry with BRD. Every part of that already existed: the filesystem finds the file, the memory controller writes Program Memory, and BRD turns an address worked out at run time into somewhere to go. The header is the only new thing. Programs/CosmOS does the same as one of its commands, and then takes the machine back afterwards, which the standalone loader has no way to do. The magic matters for the same reason it does everywhere else on this machine. Without it, loading a text file would put nonsense into Program Memory and then jump into it. diff --git a/Tests/makedisks.sh b/Tests/makedisks.sh index d83fc36..81b2f9b 100755 --- a/Tests/makedisks.sh +++ b/Tests/makedisks.sh @@ -46,7 +46,7 @@ for i in 1 2 3 4 5 6 7 8; do "$TOOL" put "$DISKS/sbfs.img" "filler$i.txt" >/dev/ # bytes, so that what gets loaded is always built from the source beside it. "$TOOL" format "$DISKS/load.img" 64 2 >/dev/null # The assembler writes a loadable program itself, because the source says where it goes. -"$ROOT/Assembler" "$ROOT/Programs/loadable/hello.asm" -o "$WORK/hello.sbx" >/dev/null +"$ROOT/Assembler" "$ROOT/Programs/Loader/loadable.asm" -o "$WORK/hello.sbx" >/dev/null "$TOOL" put "$DISKS/load.img" "$WORK/hello.sbx" >/dev/null # A disk for CosmOS. greet.sbx asks the system for everything it does rather than talking @@ -170,7 +170,7 @@ awk 'BEGIN { for (i = 0; i < 50; i++) printf "small %05d\n", i }' > small.txt # oldest program in the repository: the first thing this machine ever ran is the first # thing it assembles for itself. "$TOOL" format "$DISKS/asm.img" 2048 4 >/dev/null -cp "$ROOT/Programs/hello.asm" hello.asm +cp "$ROOT/Programs/Examples/hello.asm" hello.asm "$TOOL" put "$DISKS/asm.img" hello.asm >/dev/null "$ROOT/Assembler" -I "$ROOT/Programs/CosmOS/Source" -I "$ROOT/Programs/CosmOS/Assembler" \ "$ROOT/Programs/CosmOS/Assembler/readTest.asm" -o "$WORK/readTest.sbx" >/dev/null diff --git a/Tests/manifest b/Tests/manifest index 429e42a..7e6ddeb 100644 --- a/Tests/manifest +++ b/Tests/manifest @@ -30,16 +30,16 @@ # on what a program prints. # ---- Programs that halt on their own ---- -hello | hello.asm | run | - | - -printHello | printHello.asm | run | - | - -8bitFibonacci | Fibonacci/8bitFibonacci.asm | run | - | - -16bitFibonacci | Fibonacci/16bitFibonacci.asm | run | - | - -32bitFibonacci | Fibonacci/32bitFibonacci.asm | run | - | - -8bitSieve | primeSieve/8bitSieve.asm | run | - | - -16bitSegmentedSieve | primeSieve/16bitSegmentedSieve.asm | run | - | - +hello | Examples/hello.asm | run | - | - +printHello | Examples/printHello.asm | run | - | - +8bitFibonacci | Examples/Fibonacci/8bitFibonacci.asm | run | - | - +16bitFibonacci | Examples/Fibonacci/16bitFibonacci.asm | run | - | - +32bitFibonacci | Examples/Fibonacci/32bitFibonacci.asm | run | - | - +8bitSieve | Examples/primeSieve/8bitSieve.asm | run | - | - +16bitSegmentedSieve | Examples/primeSieve/16bitSegmentedSieve.asm | run | - | - # The four pointer rewrite. It emits exactly the same primes as the line above, which # is the whole point of keeping both: the pair is a direct before and after. -16bitSegmentedSieveModern | primeSieve/16bitSegmentedSieveModern.asm | run | - | - +16bitSegmentedSieveModern | Examples/primeSieve/16bitSegmentedSieveModern.asm | run | - | - mathTest | testPrograms/mathTest.asm | run | - | - printTest | testPrograms/printTest.asm | run | - | - int16print | Libraries/int16print.asm | run | - | - @@ -86,7 +86,7 @@ sbfsEditTest | testPrograms/sbfsEditTest.asm | run | - # Loading a program off a disk and running it. Everything below this line existed before # the loader did; the only new part is the sixteen bytes on the front of a loadable # program saying where it goes. -loader | loader.asm | run | - | - | disks/load.img +loader | Loader/loader.asm | run | - | - | disks/load.img # Storage. The image is made fresh for each run, so block 3 starts as zeroes. diskTest | testPrograms/diskTest.asm | run | - | - | disk.img @@ -348,20 +348,20 @@ asm-tokenTest | CosmOS/Assembler/tokenTest.asm | assemble | - asm-scratch | CosmOS/Assembler/scratch.asm | assemble | - | - # ---- Programs driven by console input ---- -inputTest | inputTest.asm | run | inputTest.in | - +inputTest | Examples/inputTest.asm | run | inputTest.in | - inputTestOld | testPrograms/inputTest.asm | run | inputTest.in | - -replCalculator | replCalculator.asm | run | replCalculator.in | - +replCalculator | Examples/replCalculator.asm | run | replCalculator.in | - # ---- Programs that run forever by design, bounded by a cycle count ---- # 3,000,000 cycles is about fourteen generations of the glider, which puts # evolveBoard and its pointer juggling through its paces many times over. -16x16Life | gameOfLife/16x16Life.asm | run | - | 3000000 +16x16Life | Examples/gameOfLife/16x16Life.asm | run | - | 3000000 # The four pointer rewrite, on the same budget so the two can be compared directly. # Note that this cannot show a speed difference: frameDelay is 255 by 255 and swamps # the simulation, so both versions render the same fourteen generations and produce # identical bytes. What it checks is that the rewrite still evolves the board the same # way, which is what a regression test is for. -16x16LifeModern | gameOfLife/16x16LifeModern.asm | run | - | 3000000 +16x16LifeModern | Examples/gameOfLife/16x16LifeModern.asm | run | - | 3000000 # ---- Libraries: no entry point, so only check that they assemble ---- # The CosmOS libraries assemble on their own, unlike print.asm below, which cannot: it diff --git a/Tests/native.sh b/Tests/native.sh index ccdb3d0..c9bbe58 100755 --- a/Tests/native.sh +++ b/Tests/native.sh @@ -57,7 +57,7 @@ mkdir -p "$WORK" -o "$WORK/Asm.sbx" "$ROOT/Programs/CosmOS/Assembler/Asm.asm" >/dev/null || exit 1 "$TOOL" format "$WORK/native.img" 2048 4 >/dev/null -"$TOOL" put "$WORK/native.img" "$ROOT/Programs/hello.asm" hello.asm >/dev/null +"$TOOL" put "$WORK/native.img" "$ROOT/Programs/Examples/hello.asm" hello.asm >/dev/null "$TOOL" put "$WORK/native.img" "$WORK/Asm.sbx" Asm.sbx >/dev/null # The applications, and the file of service names they all include. These are the reason @@ -86,7 +86,7 @@ done check "it wrote a file" grep -q "wrote hello.bin" "$WORK/session.txt" # ---- And the file is the one the host assembler makes ---- -"$ASM" -o "$WORK/reference.bin" "$ROOT/Programs/hello.asm" >/dev/null +"$ASM" -o "$WORK/reference.bin" "$ROOT/Programs/Examples/hello.asm" >/dev/null "$TOOL" get "$WORK/native.img" hello.bin "$WORK/native.bin" >/dev/null 2>&1 if [ -f "$WORK/native.bin" ]; then REPORT="$(wc -c < "$WORK/native.bin" | tr -d ' ') bytes"