Sieve-16.asm, Life.asm and Fib-16.asm could be read on the machine and not assembled on it.
All three #Include print.asm, and print.asm was not on the disk.
/LIB WAS STILL A HAND-WRITTEN LIST. Programs/Libraries is what an #Include means when it is
not a CosmOS source - print, the integer helpers, the maths - and nobody had thought to name
them, which is the exact failure mirroring the sources was meant to end. It is mirrored now,
so the next one nobody thinks of is there anyway.
AND THE ASSEMBLER SAID NOTHING USEFUL. A missing include returned a failure and printed no
message, so the catch-all at the top said "nothing was written", which is true and useless -
finding out why meant reading the assembler rather than the message. It names the file now,
and where it looked:
cannot find print.asm, not beside the file that asked and not as /Lib/print.asm
Both halves are worth having, because a name that is in neither place is usually one or the
other spelt wrong. The same shape as More's "error 2": a program that knows exactly what
happened, reporting a number or nothing at all.
The disk also depends on the recipe that lays it out now. It did not, so adding the libraries
left an image built without them and the next run reported the same thing missing - which
sends you looking at the change you just made rather than at the stale thing in front of you.
It cost twenty minutes to notice.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
A list of files in a makefile goes stale the moment somebody adds a program and forgets to
name it, and what they forgot is invisible until they go looking for it on the machine. So
SplitDisk gained a mirror command and the disk rule is one line: putting a file where the
others live is now the whole of putting it on the disk.
EVERY FILE GOES THROUGH put AND EVERY DIRECTORY THROUGH mkdir. That is the point of it -
mirror adds a walk and no filesystem code at all, so anything the format refuses here it
refuses everywhere, in the same words. What is new is the walk, and the walk is what the
six checks in Tests/disk.sh are about: that it goes all the way down, that it leaves dotfiles
and named directories behind, and that a name too long stops it.
REFUSED RATHER THAN SKIPPED, because a disk quietly missing a file is the exact failure a
mirror exists to prevent. Which meant four sources had to be renamed - a directory entry
holds 22 characters and they were 23, 23, 24 and 29:
16bitSegmentedSieve.asm -> 16bitSieve.asm
16bitSegmentedSieveModern.asm -> 16bitSieveModern.asm
consoleInterruptTest.asm -> consoleInterrupt.asm
controllerWriteTest.asm -> controllerWrite.asm
The test names in the manifest are unchanged, since those are identifiers and every recorded
result is filed under them. Only where the source lives has moved.
The entries are sorted before anything is written. readdir hands them back in whatever order
the host filesystem feels like, and a disk image that comes out different from one run to the
next is an image no test could compare against another.
The disk grew from one megabyte to four and from 192 directory entries to 1,024. The sources
are 2,850 blocks and the mirror filled the old directory on its first run, which is a thing
that should not need thinking about again.
The Tests fixture disk is deliberately NOT mirrored. It is a controlled fixture with known
contents, and the shipped disk is the one meant to be useful; they want different things.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
The jitter was a stale disk. An image built before the escape sequences came out still had
the old Snake on it, which sends ESC [ H every frame: the console swallows the escape,
because it is below the font's first character, and then draws "[H" as two ordinary letters.
So every frame began two characters to the right and one line further down than the last,
and the board walked down the screen. Not timing at all.
WHAT IS ON A DISK IS WHATEVER WAS BUILT WHEN THE DISK WAS MADE, and a machine whose console
has changed will start that image quite happily. That is the compatibility break we chose
when the parser came out, and it is fine - but it should not be a puzzle, so both run
targets depend on the disk rather than merely using it, and both READMEs say why.
run-voyager boots the same disk on the machine with a screen. It existed only as
EMU=../Voyager in front of run-cosmos, which is not a thing anybody should have to know.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
make run-cosmos handed the emulator a boot image AND a disk, so it took the
direct path every time: memory placed from outside, nothing on the disk
consulted about it. The whole boot chain was built and tested and then not
used by the one command that runs the system.
The disk is formatted with a boot area now, stage two goes into slot zero
as raw bytes, and the system is an ordinary file at /System/Boot/cosmos.bin
- which is what boot.cfg would choose between if there were one. There is
not: stage two falls back to that name when the file is missing, and a
clean install with nothing to configure is the right default.
run-cosmos names no image, so the machine starts itself. The old behaviour
is run-cosmos-direct, which is worth keeping and worth naming honestly: it
is what a debugger does, and it is what to use when the thing being
debugged is the boot chain, since it skips the boot chain.
/Source gains stage1.asm and stage2.asm, so the machine can rebuild what
starts it. Everything stage two includes is already in /Lib, so Asm
stage2.asm on the machine produces the bytes a boot slot takes. Stage one
is the exception and always will be: it is the ROM, and the one part of
this that a disk cannot replace.
Second slot left empty, which is what makes replacing the first survivable.
The demo disk is three directories instead of thirty nine names in one list
with cosmos.asm sitting between fileStream.asm and sbfs.asm:
/Apps what you run
/Source what you name to the assembler
/Lib what those include
The split is by ROLE rather than by which directory the host keeps a file in.
Everything in /Lib is named by an #Include somewhere and by nothing else, which
is what makes it a library rather than a source.
THAT LAYOUT WAS NOT POSSIBLE UNTIL NOW, and finding out why is what this rung
actually cost. An include on the machine was a bare name resolved where you
stood, so every source that calls a service had to sit in the same directory as
services.asm - which is every source worth having. The first arrangement of
this disk put the examples in a directory of their own and none of them would
assemble.
So the native assembler has a search path: beside you, then /Lib. The same rule
the shell already uses for a program it does not recognise, applied to the
thing that reads source, and the same reasoning for it being two fixed places
rather than a list - a list needs somewhere to live between one boot and the
next, and there is no such place yet. It also brings the native assembler
nearer the host one, which has searched -I directories since before there was a
machine to run this on.
The reader's per-file state grew from 293 bytes to 301, because the name it
keeps is a path now and every block of a file is asked for by it. Six of those
would no longer fit the room set aside, so the include list moved up a page.
Both numbers are written down in two places on purpose and both were changed.
dir said cosmos.asm was 17,460 bytes. It is 82,996. The size came out of the
block count's LOW BYTE shifted up and the tail beneath it, which is sixteen
bits, so anything from 256 blocks upward came back as itself less 65,536 - a
plausible number, and wrong. Files that big say their size in blocks now.
Printing the true figure wants decimal printing twenty four bits wide, which is
a page of console.asm to say something nobody reads more precisely than "big".
The Assembler Manual's line about SBFS being flat was the last thing in the
repository still claiming it, and docs.sh now looks for that phrase and three
like it in all four documents. Not a section that is wrong - one clause inside
a paragraph that is otherwise right, which is the shape this kind of staleness
takes.
The duplicate puts are gone with the wildcard that caused them, so building the
disk is quiet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
The demo disk had eight directory blocks, which is sixty four names, and
thirty nine of them were already spoken for. Its two ceilings were nowhere
near each other: the average file on it is twenty six blocks, so sixty four
names run out with the disk forty one per cent full. Names were going to be
gone long before space was, and space is what a disk is usually short of.
Twenty four blocks is one hundred and ninety two names. The difference costs
sixteen blocks of four thousand and ninety six, three tenths of one per cent,
and the superblock has carried this number per disk since the format was
written - so nothing but the makefile line knows or cares what it is.
This is provisioning and not format. Directories, when they arrive, will not
relieve this pressure; under the settled design they add to it, because a
directory spends an entry of its own.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
Found by a review, all three confirmed by trying them rather than by
reading.
1. THE STRICT BUILD CLAIM WAS FALSE. The README says the sources build clean
under -std=c11 -pedantic with -Wall -Wextra, and they did not: realpath is
an XSI interface, and _POSIX_C_SOURCE=200809L does not reach it, so the
assembler would not compile. The ordinary -Os build never saw it, because
without -std=c11 the compiler's own default declares realpath anyway.
_XOPEN_SOURCE=700 is POSIX.1-2008 plus XSI, and covers every file on its
own. Narrowed by compiling each source with each candidate macro rather
than by adding one and hoping.
And 'make strict' now checks it, as part of 'make test'. The README makes
a claim somebody may check by typing it, so the suite types it. Verified
the check bites by putting the old macro back.
2. THE COSMOS README HAD NOT CAUGHT UP WITH THIS WEEK. It said there were no
breakpoints and proposed writing a spare byte over an instruction - two
commits after SWI osBreak was built, which does it without overwriting
anything and is described correctly further down the same file. Its
Current Scope said there was no native assembler and that self-hosting
was the intended long-term milestone. And the streaming section spoke of
a machine "one day going to assemble itself".
All three now say what is true. Self-hosting is described as done, with
what is left of it named: a linker, and an editor that knows what
assembly is.
3. 'make run-hello' DID NOT WORK, and it is the one command the makefile's
own header advertises. It was a pattern rule against $(BUILD)/%.bin,
which worked while every program sat at the top of Programs/ and broke
the moment they were filed into Examples/ - which I did, four commits ago,
without trying it.
The name is looked up among the programs now, so it is the program's name
rather than its path, and an unknown one lists what there is instead of
saying "No rule to make target".
The same sweep was run across all four documents for other claims this week
invalidated. The remaining "not yet" phrases are about faults that genuinely
are not defined yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
Five .asm files sat at the top of Programs/ beside six directories, with
nothing to say which a new file should join - and hello.asm, which is the
native assembler's first target and named in sixteen places, looked like a
stray.
Programs/
Examples/ what you read to learn: hello, printHello, inputTest,
replCalculator, and Fibonacci, primeSieve and gameOfLife
as sets of their own
Libraries/ included by name, no entry point of their own
Loader/ loader.asm, and the loadable program it reads
CosmOS/ the system, its applications and its assembler
testPrograms/ what 'make test' drives
Loader/ is the one worth explaining. loader.asm is not a demonstration: it
reads a program off a disk, puts the two pieces where the header asks, and
jumps to the entry. CosmOS grew out of it and does the same thing as one of
its commands. It is kept because backward compatibility with the simplest
version of the system is a standing goal, and it was sitting loose next to
the demos as though it were one.
Programs/loadable/ was a directory holding one file called hello.asm - a
third thing of that name, and the name said nothing about why it was there.
It is Loader/loadable.asm now, beside the loader that reads it.
Every reference moved with them: the makefile's program list, twelve
manifest lines, makedisks.sh, native.sh, and four paths across the README
and both manuals. Verified by deleting both build directories and running
the whole suite from nothing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
> load Asm.sbx
> run cosmos.asm
wrote cosmos.bin: program 7036, data 2448, labels 475
> run Asm.asm
wrote Asm.sbx: program 7533, data 4099, labels 555
Both byte for byte identical to what the host assembler builds from the
same source. The machine now builds the operating system it is running on,
and builds the thing that built it.
THE CHECK THAT MATTERS MOST IS THE THIRD ONE. A binary that matches could
still have come from an assembler wrong in some way this particular source
happens not to exercise. So Tests/native.sh boots the CosmOS that CosmOS
built and has THAT assemble CosmOS again - and the second generation is
identical to the first, down to the cycle count. It is a fixed point: the
machinery has been through itself. After this the host is a convenience
rather than a necessity.
WHAT STOOD IN THE WAY was not the assembler. It loaded, faulted at 7,780
cycles, and the fault was in CosmOS: a loaded program is staged at 0x8000
before being blitted into place, so the whole FILE has to fit in the 32,768
bytes above it. The assembler's file was 33,983, and 22K of that was
zeroed scratch buffers - because #Reserve emits what it reserves.
None of that is initialised data. It is scratch, wanted only while the
assembler runs, and while it runs everything above its own data is free.
So the buffers are a MAP now rather than declarations - Assembler/scratch.asm
writes down six addresses and the file carries none of it. 33,983 bytes
became 11,648, and the assembler could load itself.
The map has a file of its own because the reader and the label table both
need addresses out of it while neither includes the other.
The sizes are cut to the largest thing it is asked to build, and that turns
out not to be the operating system: the assembler is 555 labels and 11,648
bytes of output against CosmOS's 475 and 9,564. The hardest thing this
assembles is itself.
Also: sizing it for CosmOS meant raising the label table, and raising the
label table is what pushed the file over the staging limit. The two facts
only met because the first one was tried.
Speed, measured rather than guessed: CosmOS takes 80,168,646 cycles, which
is eighty seconds of emulated time and under a second under --fast. Most of
it is a straight walk of 475 label names, several thousand times. Sorting
or bucketing that is easy and was deliberately not written before there was
something to measure.
make run-cosmos now puts every source file on the disk, so the whole thing
can be done rather than read about.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
> load Asm.sbx
> run Keys.asm
wrote Keys.sbx: program 558, data 85, labels 52
> load Keys.sbx
> run
keys, by interrupt. q stops.
ab
the console has been handed back
The machine assembles a program carrying an interrupt handler, the loader
installs its vector, the console interrupts into it, and the shell takes the
vector back at exit. Byte for byte identical to the C assembler's, and
Tests/native.sh now checks a boot image and four loadable programs on every
run.
WHAT IT TOOK:
A declaration and an implementation are the SAME ENTRY. services.asm says
a service is called osPrintString and has number 16; cosmos.asm says
osPrintString is handled by handlePrintString. The name is met twice and
the second time fills in the handler, which is what lets one shared file
serve both the caller and the implementer.
So the first pass declares and the second implements. That is forced: a
handler is an address, and no address is known until every label has been
placed.
Boot in a loadable program fills the entry field rather than being
installed - vector zero is where the whole machine starts, and a program
loaded into a running system has no business saying anything about that.
A boot image is the one thing that does, so there it is installed like any
other, behind a "VEC" marker in the SPBT file.
Device is named by the port, and Device with the five reserved names are
matched without regard to case, the way mnemonics are: they are part of
the language rather than names the programmer chose. Devices have no names
of their own, so they are given one nothing can type.
TWO BUGS, both of a kind worth naming.
The first: "is this a loadable program" was written out as an OR of the two
segment bases in seven places, and the sense wanted is the opposite in most
of them. One of the seven had it backwards and put a version ONE header on a
file carrying vectors, which a loader is right to refuse. It is one flag
now, settled once and tested the same way everywhere.
The second: finding the entry to write a handler into means calling vecFind,
which reads the entry's fields out - including the handler it does not have
yet. An address resolved into VecHandler before the find was overwritten
with zero by the find itself, and the file came out with a vector pointing
at address zero: a slot that looked installed and went nowhere. The
resolved address has a variable of its own now.
Keys.asm and console.asm go on the CosmOS disk, so the whole path can be
watched rather than only tested.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
Both are called hello.asm and they are different programs: Programs/hello.asm
is the 1978-style boot image that writes straight to port 0x00 and HALTs,
and CosmOS/Apps/hello.asm is the loadable one that ends with SWI osExit.
The disk had the first, which assembles to a .bin the shell cannot load, so
watching it work meant taking the file off the disk afterwards.
Now it has the second, and the whole thing is two commands:
> load Asm.sbx
> run hello.asm
wrote hello.sbx: program 22, data 14, labels 3
> load hello.sbx
> run
Hello, World!
It writes over the hello.sbx the host tool put there, so what runs is the
machine's own work. Byte for byte identical to the C assembler's, as ever.
strings.asm stays as it is, and now earns its place by being the odd one
out: no #Include and no #Base, so it assembles to a boot image rather than
a loadable program and the difference between the two is visible on one
disk.
Tests/native.sh still builds the bare metal hello.asm, and should: it is the
only thing that checks the SPBT path end to end, including running what came
out.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
> load Asm.sbx
> run Say.asm
wrote Say.sbx: program 46, data 93, labels 7
> load Say.sbx
> run built by the machine itself
it says: built by the machine itself
The machine assembles an application and then runs what it built. Say,
greet and Files all come out byte for byte identical to the C assembler's,
and Tests/native.sh checks all three on every run alongside the boot image
M1 already covered.
WHAT IT TOOK, and it was more than #Include and #Base:
#Include The reader is a stack of readers. The current file's whole
state goes aside - buffer and all, 292 bytes - the new one
opens, and the end of it pops the old one back. A file goes in
once; including it twice does nothing, which is what lets two
libraries depend on a third. The list is forgotten between the
passes, because the second has to walk the same tree.
#Base Cursors start there, so labels hold the addresses the program
will really have. A program that says where it goes gets the
SBEX header and a .sbx name; one that says nothing gets SPBT
and .bin. A program that bases one segment and leaves the
other unbased with content in it is refused.
#Reserve Runs of zeroes, moved over in the first pass and written in
#Align the second. How many an #Align comes to depends on where the
cursor has reached, which is why both passes keep a cursor.
#Vectors Names are read and numbered, pinned where the source pins
them, so SWI osPrintString resolves. Every application needs
this - a program that calls a service names a vector declared
in a file it includes.
THE TWO PASSES ARE NOW ONE LOOP, walked twice, with Emitting the only
difference. They have to agree about the length of every token, and the way
they stop agreeing is by being two pieces of code that drifted apart -
which is the exact shape of the bug this assembler found in the C one.
Sharing the body means there is nothing to drift. What is left is checked
anyway: the second pass compares its own totals against the first's and
refuses to write the file if they differ.
THE BUG WORTH RECORDING. The tokenizer holds one character of lookahead,
and at an #Include that character belongs to the file being put aside. It
was carried across and handed back on the way out, which is wrong: a file
runs out in the middle of whatever the tokenizer happens to be doing, so
the character arrives in the middle of a word. `start:` came back as `s`
and then `tart:` - and the result assembled into a perfectly plausible
file. The fix is to undo the read instead, so the character is simply still
there when the file is opened again and the question of when to hand it
back never arises.
Three smaller ones, all old friends: three places took the CONTENTS of a
buffer where they wanted its ADDRESS; vecTakeAuto returned its answer in A,
which a RET puts back; and pass two re-declared every vector because only
the label table was being skipped on the second walk.
sameText moved down into numbers.asm from the label table - four parts want
it now, and a reader test that includes neither labels nor tokens has to
build on its own.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
'make run-cosmos' now boots a machine with Asm.sbx on the disk and two
source files to point it at, so the thing can be watched working rather
than only tested:
> load Asm.sbx
> run hello.asm
wrote hello.bin: program 17, data 14, labels 2
> run strings.asm
wrote strings.bin: program 62, data 88, labels 4
Both come out byte for byte identical to the C assembler's, and both run.
hello.asm and testPrograms/stringKeyword.asm are the two single-file
programs with no #Include, which is what the native assembler handles so
far; strings.asm is the second because it has a subroutine and a label
used before it is defined, so it exercises a forward reference that
hello.asm does not.
The assembler builds from its own directory rather than from Apps/,
because it is not one file. Its pieces are found beside it without being
told, since an include is looked for next to the file that asked for it
before anywhere else; only services.asm needs the include path.
ALSO A CORRECTION. Asm.asm's header, its usage message and the Assembler
Manual all said 'run Asm.sbx hello.asm'. That is the convention we talked
about wanting later, not the one this shell has: load and run are separate
commands, so the whole rest of the run line is the argument and that form
asks for a file called "Asm.sbx hello.asm". All three now say load first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
cosmos.img was 256 blocks and two directory blocks: 64K, sixteen files.
Ample for a disk that held nothing but programs, and not enough for the
thing that comes next. The native assembler reads SOURCE from this disk,
and the CosmOS sources alone are 104,142 bytes against the 65,536 a 256
block disk holds - so the machine could not hold its own source code.
2048 blocks and four directory blocks: 512K and room for 32 files.
Nothing was recorded that had to change, which is worth saying rather
than assuming: dir lists names and does not report free space, so no
golden file names a block count.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW
Two changes that arrived together because both live in cosmos.asm.
THE SERVICES. A loaded program that wanted a file had to include the whole
filesystem, carrying two and a half kilobytes of a private copy of code the
system already had running, and then mount a disk that was already mounted.
Five services are added at pinned numbers 20 to 24: osFileRead, osFileSave,
osFileDelete, osFileRename and osPrintNumber.
The sizes fit the registers exactly in both directions. A file that can be
read into Data Memory is under 64K by definition, so its length is sixteen
bits: coming back it is DP3, going out it is A and B together, and neither
direction needs a record in memory whose shape both sides must agree on.
There is deliberately no service to mount a disk. The system mounts one
before its first prompt, and a program mounting it again was only ever a
consequence of owning a second copy of the library, so that call disappears
rather than moving. Apps/Files.asm writes, reads, renames and deletes a file
in 645 bytes and includes nothing but the service names.
THE MONITOR. Previously an application, now part of the shell, because an
application occupies the one region a loaded application is given: a monitor
that was an application could never examine another one, since loading the
thing to be inspected would replace the thing doing the inspecting.
"monitor" turns it on and the prompt becomes "*". It is a mode rather than a
sub-prompt, and it persists: because the mode is a variable the prompt reads
rather than a second loop, and every path back to the prompt goes through one
place including osExit, a program started with "g" that gives the machine back
arrives at the monitor prompt it was started from. Examining a program and
running it therefore do not interrupt each other. "exit" leaves whatever you
are in.
It supersedes dump, and adds disassembly, writing bytes, and jumping to an
address. Its instruction table is generated from the assembler's own list by
Tests/instructiontable.py rather than typed again, and Tests/docs.sh checks
both that the system's copy matches the generator and that the lengths that
table implies are the ones the manual's Bytes column prints. A disassembler
that disagreed about a length would not print one line wrong, it would lose
its place and print everything after it wrong.
Also here: b refuses a bank that is not registered, since asking the
controller for one is refused and a refusal nobody catches stops the machine;
g records the Stack the way run does, without which a program returning
through osExit restored whatever the last run had left; and make cosmos-disk
now depends on the system as well as the image.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AnachronautandClaude Opus 5