Complete overhaul of recipes

Recipes contain bits and pieces of hardware-related knowledge, but
these bits feel sparse. I've been wanting to consolidate hardware-
related documentation for a while, but always fell at odds with the
recipes organisation.

We don't have recipes anymore, just a /doc/hw section that contains
hardware-related documentation which often translate to precise
instructions to run Collapse OS on a specific machine.

With this new organisation, I hope to end up with a better, more
solid documentation.

CONTRIBUTING.md

@@ -12,8 +12,7 @@ microcontrollers with low-tech tools. We accept only contributions advancing
 the project towards that goal.
 
 Although Collapse OS is mostly a software product, it's also a documentation
-repository. Improving documentation and recipes make the project advance
-towards its goal.
+repository. Improving documentation make the project advance towards its goal.
 
 That Collapse OS has such a narrow goal might disappoint many people who are
 enthusiastic about the technological achievement. Sorry for that.

README.md

@@ -40,8 +40,8 @@ it's not a z80 emulator, but a *javascript port of Collapse OS*!
 * `cvm`: A C implementation of Collapse OS, allowing it to run natively on any
          POSIX platform.
 * `doc`: Documentation.
-* `recipes`: collection of recipes that assemble Collapse OS on a specific
-             machine.
+* `arch`: collection of makefiles that assemble Collapse OS on different
+          machines.
 * `tools`: Tools for working with Collapse OS from "modern" environments. For
            example, tools for facilitating data upload to a Collapse OS machine
            through a serial port.

arch/8086/pcat/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/8086/pcat.txt
 TARGET = disk.bin
-BASE = ../..
+BASE = ../../..
 CDIR = $(BASE)/cvm
 BLKPACK = $(BASE)/tools/blkpack
 STAGE = $(CDIR)/stage

arch/z80/rc2014/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/z80/rc2014.txt for details
 TARGET = os.bin
-BASE = ../..
+BASE = ../../..
 CDIR = $(BASE)/cvm
 EDIR = $(BASE)/emul/z80
 STAGE = $(CDIR)/stage

arch/z80/rc2014/blk/600

@@ -0,0 +1,2 @@
+601 ACIA                       606 Zilog SIO driver
+615 SPI relay                  619 Xcomp unit

arch/z80/sms/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/z80/sms.txt
 TARGET = os.bin
-BASE = ../..
+BASE = ../../..
 STAGE = $(BASE)/cvm/stage
 BLKPACK = $(BASE)/tools/blkpack
 SMSROM = $(BASE)/tools/smsrom

arch/z80/ti84/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/z80/ti84.txt
 TARGET = os.bin
-BASE = ../..
+BASE = ../../..
 CDIR = $(BASE)/cvm
 STAGE = $(CDIR)/stage
 BLKPACK = $(BASE)/tools/blkpack

arch/z80/trs80/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/z80/trs80.txt
 TARGET = os.bin
-BASE = ../..
+BASE = ../../..
 BLKPACK = $(BASE)/tools/blkpack
 STAGE = $(BASE)/cvm/stage
 

arch/z80/z80mbc2/Makefile

@@ -1,5 +1,6 @@
+# See /doc/hw/z80/z80mbc2.txt
 TARGET = os.bin
-BASEDIR = ../..
+BASEDIR = ../../..
 CDIR = $(BASEDIR)/cvm
 STAGE = $(CDIR)/stage
 

blk/001

@@ -6,7 +6,7 @@ MASTER INDEX
 160 AVR SPI programmer
 170-259 unused                260 Cross compilation
 280 Z80 boot code             350 Core words
-400-410 unused
+400 AT28 EEPROM driver        401-410 unused
 410 PS/2 keyboard subsystem   418 Z80 SPI Relay driver
 420 SD Card subsystem         440 8086 boot code
 470-519 unused                520 Fonts

doc/faq.txt

@@ -0,0 +1,28 @@
+# Frequently asked questions
+
+# What is the easiest way to run Collapse OS on a modern
+  computer?
+
+Run the C VM in folder "/cvm". Run "make", then "./forth".
+See doc/usage.txt for the rest.
+
+# How do I use the different emulators?
+
+Ah, you've noticed that /emul contains quite a few emulators.
+Code in this folder only build emulators, not the binary to run
+under it. It's the /arch folder that contains the makefiles to
+build Collapse OS binaries to run under those.
+
+When a binary built in /arch has a corresponding emulator, the
+makefile has a "emul" target that you can use.
+
+For example, "cd arch/z80/rc2014 && make emul" builds RC2014's
+Collapse OS, the RC2014 emulator and then invokes the emulator.
+
+# How do I fill my SD card with Collapse OS' FS?
+
+Very easy. You see that "/cvm/blkfs" file? You dump it to your
+raw device.  For example, if the device you get when you insert
+your SD card is "/dev/sdb", then you type "cat emul/blkfs | sudo
+tee /dev/sdb > /dev/null".
+

doc/hardware.txt

@@ -1,30 +0,0 @@
-# Running Collapse OS on real hardware
-
-Collapse OS is designed to run on ad-hoc post-collapse hardware
-build from scavenged parts. These machines don't exist yet.
-
-To make Collapse OS as likely as possible to be useful in a
-post-collapse world, we try to give as many examples as possible
-of deployment on hacked-up hardware.
-
-For example, we include a recipe for running a Sega Master
-System with a PS/2 keyboard plugged to a hacked up controller
-cord with an AVR MCU interfacing between the PS/2 connector and
-the controller port.
-
-This setup, for which drivers are included in Collapse OS, exist
-in only one copy, the copy the author of the recipe made.
-
-However, the idea is that this recipe, which contains schematics
-and precise instructions, could help a post-collapse engineer
-to hack her way around and achieve something similar. She would
-then have a good example of schematics and drivers that are
-known to work.
-
-If you want to run Collape OS on real hardware, take a look at
-arch-specific documentation in /recipes and see if some of the
-supported hardware is close to something you have.
-
-Easy pickings are PC/AT (which run on modern PCs supporting
-legacy BIOS), Sega Genesis w/ Everdrive and TI-84+. Those
-options don't require any soldering.

doc/hw/8086/pcat.txt

@@ -0,0 +1,55 @@
+# PC/AT
+
+PC-compatible machines need no introduction. They are one of the
+most popular machines of all time. Collapse OS has a 8086
+assembler and has boot code allowing it to run on a
+PC/AT-compatible machine, using BIOS interrupts in real mode.
+Collapse OS always runs in real mode.
+
+In this recipe, we will compile Collapse OS and write it to a
+USB drive that is bootable on a modern PC-compatible machine.
+
+# Gathering parts
+
+* A modern PC-compatible machine that can boot from a USB drive.
+* A USB drive
+
+# Build the binary
+
+Running "make" in /arch/8086/pcat will yield:
+
+* mbr.bin: a 512 byte binary that goes at the beginning of the
+           disk
+* os.bin: 8086 Collapse OS binary
+* disk.bin: a concatenation of the above, with "blkfs" appended
+            to it starting at 0x2000.
+
+disk.bin is what goes on the USB drive.
+
+This binary has BLK and AT-XY support, which means you have disk
+I/Os and can run VE.
+
+# Emulation
+
+You can run the built binary in Collapse OS' 8086 emulator using
+"make emul".
+
+The 8086 emulator is barbone. If you prefer to use it on a more
+realistic setting, use QEMU. The command is:
+
+    qemu-system-i386 -drive file=disk.bin,if=floppy,format=raw
+
+# Running on a modern PC
+
+First, copy disk.bin onto your USB drive. For example, on an
+OpenBSD machine, it could look like:
+
+    doas dd if=disk.bin of=/dev/sd1c
+
+Your USB drive is now BIOS-bootable. Boot your computer and
+enter your BIOS setup to make sure that "legacy boot" (non-EFI
+boot, that is, BIOS boot) is enabled. Configure your boot device
+priority to ensure that the USB drive has a chance to boot.
+
+Reboot, you have Collapse OS. Boot is of course instantaneous
+(we're not used to this with modern software...).

doc/hw/arduinouno/at28.txt

@@ -0,0 +1,52 @@
+# Writing to a AT28 EEPROM from a modern environment
+
+The Arduino Uno is a very popular platform based on the
+ATMega328p. While Collapse OS doesn't run on AVR MCUs (yet?),
+the Arduino can be a handy tool, which is why we have recipes
+for it here.
+
+In this recipe, we'll build ourselves an ad-hoc EEPROM holder
+which is designed to be driven from an Arduino Uno.
+
+# Gathering parts
+
+* An Arduino Uno
+* A AT28C64B
+* 2 '164 shift registers
+* Sockets, header pins, proto board, etc.
+* AVRA[1] (will soon rewrite to Collapse OS' ASM)
+* avrdude to send program to Arduino
+
+# Schema
+
+Schema is at img/at28wr.jpg.
+
+This is a rather simple circuit which uses 2 chained '164 shift
+register to drive the AT28 address pins and connects CE, WE, OE
+and the data pins directly to the Arduino. Pins have been chosen
+so that the protoboard can plug directly on the Arduino's right
+side (except for VCC, which needs to be wired).
+
+PD0 and PD1 are not used because they're used for the UART.
+
+AT28 selection pins are pulled up to avoid accidental writes due
+to their line floating before Arduino's initialization.
+
+I've put 1uf decoupling caps next to each IC.
+
+# Software
+
+The software in code/at28wr.asm listens to the UART and writes
+every byte it receives to the AT28, starting at address 0. It
+expects tty-escaped content (see /tools/ttysafe).
+
+After having written the byte, it re-reads it from the EEPROM
+and spits it back to the UART, tty-escaped.
+
+# Usage
+
+After you've build and sent your binary to the Arduino with
+"make send", you can send your (tty-safe!) content to your
+EEPROM using /tools/pingpong.
+
+[1]: http://avra.sourceforge.net/

doc/hw/at28.txt

@@ -0,0 +1,42 @@
+# Writing to a AT28 from Collapse OS
+
+# Gathering parts
+
+* A RC2014 Classic
+* An extra AT28C64B
+* 1x 40106 inverter gates
+* Proto board, RC2014 header pins, wires, IC sockets, etc.
+
+# Building the EEPROM holder
+
+The AT28 is SRAM compatible so you could use a RAM module for
+it. However, there is only one RAM module with the Classic
+version of the RC2014 and we need it to run Collapse OS.
+
+You could probably use the 64K RAM module for this purpose, but
+I don't have one and I haven't tried it. For this recipe, I
+built my own module which is the same as the regular ROM module
+but with WR wired and geared for address range 0x2000-0x3fff.
+
+If you're tempted by the idea of hacking your existing RC2014
+ROM module by wiring WR and write directly to the range
+0x0000-0x1fff while running it, be aware that it's not that
+easy. I was also tempted by this idea, tried it, but on bootup,
+it seems that some random WR triggers happen and it corrupts the
+EEPROM contents. Theoretically, we could go around that by
+putting the AT28 in write protection mode, but I preferred
+building my own module.
+
+I don't think you need a schematic. It's really simple.
+
+# Writing contents to the AT28
+
+There is an AT28! writer word in B400 which is A!-compatible
+(see "Addressed devices" in doc/usage.txt) and and waits until
+the write is complete before returning. If you use C! directly,
+bytes you write might not have the time to completely write
+themselves before you write another one.
+
+To use, set A! with "' AT28! ' A! **!". Once this is done, you
+can use MOVE, or /tools/upload, both will call A! and do the
+right thing. Unset A! with "' C! ' A! **!" afterwards.

doc/hw/avr.txt

@@ -1,10 +1,10 @@
 # Making an ATmega328P blink
 
 Collapse OS has an AVR assembler and an AVR programmer. If you
-have a SPI relay as described in the SD card recipe, then you
-almost have all it takes to make an ATmega328P blink.
+have a SPI relay (see doc/hw/spi.txt), then you almost have all
+it takes to make an ATmega328P blink.
 
-First, read `doc/avr.txt`. You'll see that it tells you how to
+First, read doc/avr.txt. You'll see that it tells you how to
 build an AVR programmer that works with your SPI relay. You
 might already have such device. For example, I use the same
 device as the one I connect to my Sparkfun AVR Pocket
@@ -14,7 +14,7 @@ a 6-pin ribbon cable to connect it to my SPI relay.
 If you have a SD card connected to the same SPI relay, you'll
 face a timing challenge: SD specs specifies that the minimum
 SPI clock is 100kHz, but depending on your setup, you might end
-up with an effective `SCK` below that. My own clock setup looks
+up with an effective SCK below that. My own clock setup looks
 like this:
 
 I have a RC2014 Dual clock which allows me to have easy access
@@ -27,16 +27,16 @@ the "no division" position, and when I communicate with the
 AVR chip, I move the switch to increase the divisor.
 
 Once you've done this, you can test that you can communicate
-with your AVR chip by doing `160 163 LOADR` (turn off your
+with your AVR chip by doing "160 163 LOADR" (turn off your
 programmer or else it might mess up the SPI bus and prevent you
 from using your SD card) and then running:
 
     1 asp$ aspfl@ .x 0 (spie)
 
-(Replace `1` by your SPI device ID) If everything works fine,
+(Replace "1" by your SPI device ID) If everything works fine,
 you'll get the value of the low fuse of the chip.
 
-## Building the blink binary
+# Building the blink binary
 
 A blink program for the ATmega328P in Collapse OS would look
 like this:
@@ -56,10 +56,10 @@ like this:
             PORTB 5 SBI,
         L1 ( loop ) ' RJMP LBL,
 
-See `doc/asm.txt` for details. For now, you'll paste this into
-an arbitrary unused block. Let's use `999`.
+See doc/asm.txt for details. For now, you'll paste this into
+an arbitrary unused block. Let's use 999.
 
-    $ cd recipes/rc2014
+    $ cd arch/z80/rc2014
     $ xsel > blk/999
     $ rm blkfs
     $ make
@@ -76,8 +76,8 @@ this binary:
     0 aspfp! 0 (spie) ;
     write
 
-The first line assembles a 16 words binary beginning at `ORG @`,
+The first line assembles a 16 words binary beginning at "ORG @",
 then the rest of the lines are about writing these 16 words to
-the AVR chip (see `doc/avr.txt` for details). After you've run
+the AVR chip (see doc/avr.txt for details). After you've run
 this, if everything went well, that chip if it has a LED
 attached to PB5, will make that LED blink slowly.