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 stage 1

Build Collapse OS' stage 1 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 | $(STAGE2)`. That's the thing.  Open
`xcomp.fs` in a text editor and take a look at it.

To assemble stage 1 from RC2014, all you need to do is to type those commands
in the same order, and replace the `H@ 256 /MOD 2 PC! 2 PC!` lines with `H@ .X`.
Those commands will inform you of the begin/end offsets of the assembled binary.

I'm not going to explain in detail what each command do, but only give you an
overview of what is happening.  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
starts, 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, so we want to know
where we're at. That's why you'll need to type `H@ .X` and write down the
result. That's the starting offset.

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 source code that will be interpreted by stage 1 on boot so
that it bootstraps itself to a full interpreter. Not all units are there
because they don't fit in 8K, but they're sufficient for our needs. We also
need the linker so that we can relink ourselves to stage 2.

Finally, we have initialization code, then a spit of the ending offset.

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.

Once all your commands are run and that you have your begin/end offset (write
them down somewhere), you're at the same point as you were after the `make`
part of the base recipe. The contents between your start and end offset is the
exact same as the contents of `stage1.bin` when you run `make`. Continue your
deployment from there.

Good luck!

### 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. If your at the beginning of it, it's easier to restart it
entirely.

If you're towards the end, you might want to repair it. To do so, you'll have to
bring your `XCURRENT` and `HERE` values to where they were before the LOAD
operation. You could have thought ahead and printed them before the LOAD, but if
you didn't, you'll just have to dig in your memory with `DUMP`.

You're looking at the offset of the last wordref of the *previous* LOAD
operation. That offset is going in `XCURRENT`. Then, you're looking at the end
of that word. That offset goes in `HERE`. Once you've done that, relaunch your
LOAD.

### 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`.