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.
This commit is contained in:
parent
480cf342fa
commit
7001446212
@ -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.
|
||||
|
@ -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.
|
||||
|
0
recipes/.gitignore → arch/.gitignore
vendored
0
recipes/.gitignore → arch/.gitignore
vendored
@ -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
|
@ -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
|
2
arch/z80/rc2014/blk/600
Normal file
2
arch/z80/rc2014/blk/600
Normal file
@ -0,0 +1,2 @@
|
||||
601 ACIA 606 Zilog SIO driver
|
||||
615 SPI relay 619 Xcomp unit
|
@ -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
|
@ -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
|
@ -1,5 +1,6 @@
|
||||
# See /doc/hw/z80/trs80.txt
|
||||
TARGET = os.bin
|
||||
BASE = ../..
|
||||
BASE = ../../..
|
||||
BLKPACK = $(BASE)/tools/blkpack
|
||||
STAGE = $(BASE)/cvm/stage
|
||||
|
@ -1,5 +1,6 @@
|
||||
# See /doc/hw/z80/z80mbc2.txt
|
||||
TARGET = os.bin
|
||||
BASEDIR = ../..
|
||||
BASEDIR = ../../..
|
||||
CDIR = $(BASEDIR)/cvm
|
||||
STAGE = $(CDIR)/stage
|
||||
|
2
blk/001
2
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
|
||||
|
28
doc/faq.txt
Normal file
28
doc/faq.txt
Normal file
@ -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".
|
||||
|
@ -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.
|
55
doc/hw/8086/pcat.txt
Normal file
55
doc/hw/8086/pcat.txt
Normal file
@ -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...).
|
52
doc/hw/arduinouno/at28.txt
Normal file
52
doc/hw/arduinouno/at28.txt
Normal file
@ -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/
|
Before Width: | Height: | Size: 118 KiB After Width: | Height: | Size: 118 KiB |
42
doc/hw/at28.txt
Normal file
42
doc/hw/at28.txt
Normal file
@ -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.
|
@ -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.
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user