collapseos/recipes/rc2014/selfhost/README.md

Assembling Collapse OS from within it

This is where we tie lose ends, complete the circle, loop the loop: we assemble a new Collapse OS entirely from within Collapse OS and write it to EEPROM, either for another RC2014 or for an OS upgrade.

Gathering parts

• stage3 from sdcard recipe. If you want to write to EEPROM as the final step, you'll need a hybrid stage3 that also includes stuff from the eeprom recipe.

Building the binary

Build Collapse OS' from within Collapse OS is very similar to how we do it from the makefile. If you take the time to look at the base recipe Makefile, you'll see cat xcomp.fs | $(STAGE). That's the thing. Open xcomp.fs in a text editor and take a look at it. You'll see that it loads B618, which contains the meat, and then spits stuff to port 2, which is a special signal for the stage binary.

To assemble from RC2014, all you need to do is load B618. This will yield a binary in memory. To know the start/end offset of the binary, you'll type the same two commands and in xcomp.fs, but replace the /MOD 2 PC! 2 PC! words with .X. Then, write that binary between those offsets on your target media. That binary should be the exact same as what you get in os.bin when you run make.

Go ahead, run that. However, one thing you should know is that because the SD card driver is a bit slow, some of these commands take a long time. Multiple minutes. Be patient.

Is that it? Yes. But for your own enlightenment, open B618 and look at it, I'll give you an overview of its contents. I'm not going to explain in detail what each command do, however. You are encouraged to read the in-system documentation for more information.

The first part is configuration of your new system. When RAM starts, where RSP and PSP start, what ports to use for what device, etc. These configuration declarations are expected in the boot code and driver code.

Then, we load the Z80 assembler and the cross compiler (xcomp for short), which we'll of course need for the task ahead.

Then come xcomp overrides, which are needed for xcomp to be effective.

At this point, we're about to begin spitting binary content, this will be our starting offset. ORG will soon be set to your current H@.

Then, we assemble the boot binary, drivers' native words, then inner core, close the binary with a hook word. We're finished with cross-compiling.

We're at the offset that will be CURRENT on boot, so we update LATEST.

Then, we spit the init source code that will be interpreted on boot. And... that's it!

What to do on SDerr?

If you get SDerr in the middle of a LOAD operation, something went wrong with the SD card. The bad news is that it left your xcomp operation in an inconsistent state. The easiest thing to do it to restart the operation from scratch. Those error are not frequent unless hardware is faulty.

Verifying

You can use /tools/memdump to dump the memory between your begin/end offsets so that you can compare against your reference stage 1. Before you do, you have to take yourself out of xcomp mode. First, run XCOFF to go back to your regular dict. Then, run FORGET CODE to undo the xcomp overrides you've added before. That will rewind HERE. You don't want that. Put HERE back to after your ending offset so that you don't overwrite your binary.

Then, you can run /tools/memdump.