From e5f22c7d910c876c69a6f078b0bf32f61469986c Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Sat, 4 Apr 2020 18:10:00 -0400 Subject: [PATCH] rc2014: update README --- recipes/rc2014/README.md | 73 +++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 43 deletions(-) diff --git a/recipes/rc2014/README.md b/recipes/rc2014/README.md index 3c45e8a..6fb15ab 100644 --- a/recipes/rc2014/README.md +++ b/recipes/rc2014/README.md @@ -31,7 +31,6 @@ are other recipes related to the RC2014: ## Recipe The goal is to have the shell running and accessible through the Serial I/O. -To make things fun, we play with I/Os using RC2014's Digital I/O module. You'll need specialized tools to write data to the AT28 EEPROM. There seems to be many devices around made to write in flash and EEPROM modules, but being in @@ -40,46 +39,35 @@ device I use in this recipe. ### Gathering parts -* [zasm][zasm] +* [Forth's stage 2 binary][stage2] * [romwrite][romwrite] and its specified dependencies * [GNU screen][screen] * A FTDI-to-TTL cable to connect to the Serial I/O module of the RC2014 * (Optional) RC2014's Digital I/O module -### Write glue.asm +### Configure your build -[This is what your glue code would look like.](glue.asm) +Modules used in this build are configured through the `conf.fs` file in this +folder. There isn't much to configure, but it's there. -The `platform.inc` include is there to load all platform-specific constants -(such as `RAMSTART` and `RAMEND`). +### Build stage 1 -Then come the reset vectors. If course, we have our first jump to our main init -routine, and then we have a jump to the interrupt handler defined in `acia.asm`. +Self-bootstrapping is in Forth's DNA, which is really nice, but it makes +cross-compiling a bit tricky. It's usually much easier to bootstrap a Forth +from itself than trying to compile it from a foreign host. -We need to plug this one in so that we can receive characters from the ACIA. +This makes us adopt a 2 stages strategy. A tiny core is built from a foreign +host, and then we run that tiny core on the target machine and let it bootstrap +itself, then write our full interpreter binary. -Then comes the usual `di` to aoid interrupts during init, and stack setup. +We could have this recipe automate that 2 stage build process all automatically, +but that would rob you of all your fun, right? Instead, we'll run that 2nd +stage on the RC2014 itself! -We set interrupt mode to 1 because that's what `acia.asm` is written around. - -Then, we init ACIA, shell, enable interrupt and give control of the main loop -to the BASIC shell. - -What comes below is actual code include from parts we want to include in our -OS. As you can see, we need to tell each module where to put their variables. -See `apps/README.md` for details. - -You can also see from the `STDIO_GETC` and `STDIO_PUTC` macros that the shell -is decoupled from the ACIA and can get its IO from anything. See comments in -`kernel/stdio.asm` for details. - -### Build the image - -We only have the shell to build, so it's rather straightforward: - - ../../emul/zasm/zasm ../../kernel < glue.asm > os.bin - -Running `make` will also work. +To build your stage 1, run `make` in this folder, this will yield `os.bin`. +This will contain that tiny core and, appended to it, the Forth source code it +needs to run to bootstrap itself. When it's finished bootstrapping, you will +get a prompt to a full Forth interpreter. ### Emulate @@ -105,23 +93,22 @@ identify the tty bound to it (in my case, `/dev/ttyUSB0`). Then: screen /dev/ttyUSB0 115200 -Press the reset button on the RC2014 and you should see the Collapse OS prompt! -See documentation in `apps/basic/README.md` for details. +Press the reset button on the RC2014 to have Forth begin its bootstrap process. +Note that it has to build more than half of itself from source. It takes a +while (TODO: indicate how many minutes). -For now, let's have some fun with the Digital I/O module. Type this: +Once bootstrapping is done, you'll get a and you should see the Collapse OS +prompt. That's a full Forth interpreter. You can have fun right now. -``` -> a=0 -> 10 out 0 a -> 20 sleep 0xffff -> 30 a=a+1 -> 40 goto 10 -> run -``` +However, that multi-minutes boot is kinda annoying. Moreover, that bootstrap +code being in source form takes precious space from our 8K ROM. We already have +our compiled dictionary in memory. All we need to have a instant-booting Forth +is to combine our stage1 with our compiled dict in memory, after some +relinking. -You now have your Digital I/O lights doing a pretty dance, forever. +TODO: write this. [rc2014]: https://rc2014.co.uk [romwrite]: https://github.com/hsoft/romwrite -[zasm]: ../../tools/emul +[stage2]: ../../emul [screen]: https://www.gnu.org/software/screen/