diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f20bc0..73a8a44 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index d07eebd..b36d92e 100644 --- a/README.md +++ b/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. diff --git a/recipes/.gitignore b/arch/.gitignore similarity index 100% rename from recipes/.gitignore rename to arch/.gitignore diff --git a/recipes/pcat/Makefile b/arch/8086/pcat/Makefile similarity index 93% rename from recipes/pcat/Makefile rename to arch/8086/pcat/Makefile index f83e733..94f7aff 100644 --- a/recipes/pcat/Makefile +++ b/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 diff --git a/recipes/pcat/blk/600 b/arch/8086/pcat/blk/600 similarity index 100% rename from recipes/pcat/blk/600 rename to arch/8086/pcat/blk/600 diff --git a/recipes/pcat/blk/602 b/arch/8086/pcat/blk/602 similarity index 100% rename from recipes/pcat/blk/602 rename to arch/8086/pcat/blk/602 diff --git a/recipes/pcat/blk/604 b/arch/8086/pcat/blk/604 similarity index 100% rename from recipes/pcat/blk/604 rename to arch/8086/pcat/blk/604 diff --git a/recipes/pcat/blk/606 b/arch/8086/pcat/blk/606 similarity index 100% rename from recipes/pcat/blk/606 rename to arch/8086/pcat/blk/606 diff --git a/recipes/pcat/blk/607 b/arch/8086/pcat/blk/607 similarity index 100% rename from recipes/pcat/blk/607 rename to arch/8086/pcat/blk/607 diff --git a/recipes/pcat/blk/608 b/arch/8086/pcat/blk/608 similarity index 100% rename from recipes/pcat/blk/608 rename to arch/8086/pcat/blk/608 diff --git a/recipes/pcat/blk/610 b/arch/8086/pcat/blk/610 similarity index 100% rename from recipes/pcat/blk/610 rename to arch/8086/pcat/blk/610 diff --git a/recipes/pcat/blk/612 b/arch/8086/pcat/blk/612 similarity index 100% rename from recipes/pcat/blk/612 rename to arch/8086/pcat/blk/612 diff --git a/recipes/pcat/mbr.fs b/arch/8086/pcat/mbr.fs similarity index 100% rename from recipes/pcat/mbr.fs rename to arch/8086/pcat/mbr.fs diff --git a/recipes/pcat/xcomp.fs b/arch/8086/pcat/xcomp.fs similarity index 100% rename from recipes/pcat/xcomp.fs rename to arch/8086/pcat/xcomp.fs diff --git a/recipes/rc2014/Makefile b/arch/z80/rc2014/Makefile similarity index 88% rename from recipes/rc2014/Makefile rename to arch/z80/rc2014/Makefile index a9fe24b..87a93e2 100644 --- a/recipes/rc2014/Makefile +++ b/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 diff --git a/arch/z80/rc2014/blk/600 b/arch/z80/rc2014/blk/600 new file mode 100644 index 0000000..7e55833 --- /dev/null +++ b/arch/z80/rc2014/blk/600 @@ -0,0 +1,2 @@ +601 ACIA 606 Zilog SIO driver +615 SPI relay 619 Xcomp unit diff --git a/recipes/rc2014/blk/601 b/arch/z80/rc2014/blk/601 similarity index 100% rename from recipes/rc2014/blk/601 rename to arch/z80/rc2014/blk/601 diff --git a/recipes/rc2014/blk/602 b/arch/z80/rc2014/blk/602 similarity index 100% rename from recipes/rc2014/blk/602 rename to arch/z80/rc2014/blk/602 diff --git a/recipes/rc2014/blk/603 b/arch/z80/rc2014/blk/603 similarity index 100% rename from recipes/rc2014/blk/603 rename to arch/z80/rc2014/blk/603 diff --git a/recipes/rc2014/blk/604 b/arch/z80/rc2014/blk/604 similarity index 100% rename from recipes/rc2014/blk/604 rename to arch/z80/rc2014/blk/604 diff --git a/recipes/rc2014/blk/605 b/arch/z80/rc2014/blk/605 similarity index 100% rename from recipes/rc2014/blk/605 rename to arch/z80/rc2014/blk/605 diff --git a/recipes/rc2014/blk/606 b/arch/z80/rc2014/blk/606 similarity index 100% rename from recipes/rc2014/blk/606 rename to arch/z80/rc2014/blk/606 diff --git a/recipes/rc2014/blk/607 b/arch/z80/rc2014/blk/607 similarity index 100% rename from recipes/rc2014/blk/607 rename to arch/z80/rc2014/blk/607 diff --git a/recipes/rc2014/blk/608 b/arch/z80/rc2014/blk/608 similarity index 100% rename from recipes/rc2014/blk/608 rename to arch/z80/rc2014/blk/608 diff --git a/recipes/rc2014/blk/609 b/arch/z80/rc2014/blk/609 similarity index 100% rename from recipes/rc2014/blk/609 rename to arch/z80/rc2014/blk/609 diff --git a/recipes/rc2014/blk/610 b/arch/z80/rc2014/blk/610 similarity index 100% rename from recipes/rc2014/blk/610 rename to arch/z80/rc2014/blk/610 diff --git a/recipes/rc2014/blk/619 b/arch/z80/rc2014/blk/619 similarity index 100% rename from recipes/rc2014/blk/619 rename to arch/z80/rc2014/blk/619 diff --git a/recipes/rc2014/xcomp.fs b/arch/z80/rc2014/xcomp.fs similarity index 100% rename from recipes/rc2014/xcomp.fs rename to arch/z80/rc2014/xcomp.fs diff --git a/recipes/sms/.gitignore b/arch/z80/sms/.gitignore similarity index 100% rename from recipes/sms/.gitignore rename to arch/z80/sms/.gitignore diff --git a/recipes/sms/Makefile b/arch/z80/sms/Makefile similarity index 92% rename from recipes/sms/Makefile rename to arch/z80/sms/Makefile index a7bb9a7..a2ab8dc 100644 --- a/recipes/sms/Makefile +++ b/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 diff --git a/recipes/sms/blk/600 b/arch/z80/sms/blk/600 similarity index 100% rename from recipes/sms/blk/600 rename to arch/z80/sms/blk/600 diff --git a/recipes/sms/blk/602 b/arch/z80/sms/blk/602 similarity index 100% rename from recipes/sms/blk/602 rename to arch/z80/sms/blk/602 diff --git a/recipes/sms/blk/603 b/arch/z80/sms/blk/603 similarity index 100% rename from recipes/sms/blk/603 rename to arch/z80/sms/blk/603 diff --git a/recipes/sms/blk/604 b/arch/z80/sms/blk/604 similarity index 100% rename from recipes/sms/blk/604 rename to arch/z80/sms/blk/604 diff --git a/recipes/sms/blk/605 b/arch/z80/sms/blk/605 similarity index 100% rename from recipes/sms/blk/605 rename to arch/z80/sms/blk/605 diff --git a/recipes/sms/blk/606 b/arch/z80/sms/blk/606 similarity index 100% rename from recipes/sms/blk/606 rename to arch/z80/sms/blk/606 diff --git a/recipes/sms/blk/607 b/arch/z80/sms/blk/607 similarity index 100% rename from recipes/sms/blk/607 rename to arch/z80/sms/blk/607 diff --git a/recipes/sms/blk/608 b/arch/z80/sms/blk/608 similarity index 100% rename from recipes/sms/blk/608 rename to arch/z80/sms/blk/608 diff --git a/recipes/sms/blk/610 b/arch/z80/sms/blk/610 similarity index 100% rename from recipes/sms/blk/610 rename to arch/z80/sms/blk/610 diff --git a/recipes/sms/blk/611 b/arch/z80/sms/blk/611 similarity index 100% rename from recipes/sms/blk/611 rename to arch/z80/sms/blk/611 diff --git a/recipes/sms/blk/612 b/arch/z80/sms/blk/612 similarity index 100% rename from recipes/sms/blk/612 rename to arch/z80/sms/blk/612 diff --git a/recipes/sms/blk/613 b/arch/z80/sms/blk/613 similarity index 100% rename from recipes/sms/blk/613 rename to arch/z80/sms/blk/613 diff --git a/recipes/sms/blk/614 b/arch/z80/sms/blk/614 similarity index 100% rename from recipes/sms/blk/614 rename to arch/z80/sms/blk/614 diff --git a/recipes/sms/blk/615 b/arch/z80/sms/blk/615 similarity index 100% rename from recipes/sms/blk/615 rename to arch/z80/sms/blk/615 diff --git a/recipes/sms/blk/616 b/arch/z80/sms/blk/616 similarity index 100% rename from recipes/sms/blk/616 rename to arch/z80/sms/blk/616 diff --git a/recipes/sms/blk/617 b/arch/z80/sms/blk/617 similarity index 100% rename from recipes/sms/blk/617 rename to arch/z80/sms/blk/617 diff --git a/recipes/sms/blk/620 b/arch/z80/sms/blk/620 similarity index 100% rename from recipes/sms/blk/620 rename to arch/z80/sms/blk/620 diff --git a/recipes/sms/blk/621 b/arch/z80/sms/blk/621 similarity index 100% rename from recipes/sms/blk/621 rename to arch/z80/sms/blk/621 diff --git a/recipes/sms/blk/622 b/arch/z80/sms/blk/622 similarity index 100% rename from recipes/sms/blk/622 rename to arch/z80/sms/blk/622 diff --git a/recipes/sms/xcomp.fs b/arch/z80/sms/xcomp.fs similarity index 100% rename from recipes/sms/xcomp.fs rename to arch/z80/sms/xcomp.fs diff --git a/recipes/ti84/Makefile b/arch/z80/ti84/Makefile similarity index 93% rename from recipes/ti84/Makefile rename to arch/z80/ti84/Makefile index 6f9503f..d602b89 100644 --- a/recipes/ti84/Makefile +++ b/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 diff --git a/recipes/ti84/blk/600 b/arch/z80/ti84/blk/600 similarity index 100% rename from recipes/ti84/blk/600 rename to arch/z80/ti84/blk/600 diff --git a/recipes/ti84/blk/601 b/arch/z80/ti84/blk/601 similarity index 100% rename from recipes/ti84/blk/601 rename to arch/z80/ti84/blk/601 diff --git a/recipes/ti84/blk/602 b/arch/z80/ti84/blk/602 similarity index 100% rename from recipes/ti84/blk/602 rename to arch/z80/ti84/blk/602 diff --git a/recipes/ti84/blk/603 b/arch/z80/ti84/blk/603 similarity index 100% rename from recipes/ti84/blk/603 rename to arch/z80/ti84/blk/603 diff --git a/recipes/ti84/blk/604 b/arch/z80/ti84/blk/604 similarity index 100% rename from recipes/ti84/blk/604 rename to arch/z80/ti84/blk/604 diff --git a/recipes/ti84/blk/605 b/arch/z80/ti84/blk/605 similarity index 100% rename from recipes/ti84/blk/605 rename to arch/z80/ti84/blk/605 diff --git a/recipes/ti84/blk/606 b/arch/z80/ti84/blk/606 similarity index 100% rename from recipes/ti84/blk/606 rename to arch/z80/ti84/blk/606 diff --git a/recipes/ti84/blk/607 b/arch/z80/ti84/blk/607 similarity index 100% rename from recipes/ti84/blk/607 rename to arch/z80/ti84/blk/607 diff --git a/recipes/ti84/blk/608 b/arch/z80/ti84/blk/608 similarity index 100% rename from recipes/ti84/blk/608 rename to arch/z80/ti84/blk/608 diff --git a/recipes/ti84/blk/609 b/arch/z80/ti84/blk/609 similarity index 100% rename from recipes/ti84/blk/609 rename to arch/z80/ti84/blk/609 diff --git a/recipes/ti84/blk/610 b/arch/z80/ti84/blk/610 similarity index 100% rename from recipes/ti84/blk/610 rename to arch/z80/ti84/blk/610 diff --git a/recipes/ti84/blk/614 b/arch/z80/ti84/blk/614 similarity index 100% rename from recipes/ti84/blk/614 rename to arch/z80/ti84/blk/614 diff --git a/recipes/ti84/blk/615 b/arch/z80/ti84/blk/615 similarity index 100% rename from recipes/ti84/blk/615 rename to arch/z80/ti84/blk/615 diff --git a/recipes/ti84/blk/616 b/arch/z80/ti84/blk/616 similarity index 100% rename from recipes/ti84/blk/616 rename to arch/z80/ti84/blk/616 diff --git a/recipes/ti84/blk/617 b/arch/z80/ti84/blk/617 similarity index 100% rename from recipes/ti84/blk/617 rename to arch/z80/ti84/blk/617 diff --git a/recipes/ti84/blk/618 b/arch/z80/ti84/blk/618 similarity index 100% rename from recipes/ti84/blk/618 rename to arch/z80/ti84/blk/618 diff --git a/recipes/ti84/blk/619 b/arch/z80/ti84/blk/619 similarity index 100% rename from recipes/ti84/blk/619 rename to arch/z80/ti84/blk/619 diff --git a/recipes/ti84/blk/620 b/arch/z80/ti84/blk/620 similarity index 100% rename from recipes/ti84/blk/620 rename to arch/z80/ti84/blk/620 diff --git a/recipes/ti84/keys/02.key b/arch/z80/ti84/keys/02.key similarity index 100% rename from recipes/ti84/keys/02.key rename to arch/z80/ti84/keys/02.key diff --git a/recipes/ti84/keys/04.key b/arch/z80/ti84/keys/04.key similarity index 100% rename from recipes/ti84/keys/04.key rename to arch/z80/ti84/keys/04.key diff --git a/recipes/ti84/keys/0A.key b/arch/z80/ti84/keys/0A.key similarity index 100% rename from recipes/ti84/keys/0A.key rename to arch/z80/ti84/keys/0A.key diff --git a/recipes/ti84/keys/0F.key b/arch/z80/ti84/keys/0F.key similarity index 100% rename from recipes/ti84/keys/0F.key rename to arch/z80/ti84/keys/0F.key diff --git a/recipes/ti84/xcomp.fs b/arch/z80/ti84/xcomp.fs similarity index 100% rename from recipes/ti84/xcomp.fs rename to arch/z80/ti84/xcomp.fs diff --git a/recipes/trs80/Makefile b/arch/z80/trs80/Makefile similarity index 87% rename from recipes/trs80/Makefile rename to arch/z80/trs80/Makefile index 1d5773e..0b82132 100644 --- a/recipes/trs80/Makefile +++ b/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 diff --git a/recipes/trs80/blk/600 b/arch/z80/trs80/blk/600 similarity index 100% rename from recipes/trs80/blk/600 rename to arch/z80/trs80/blk/600 diff --git a/recipes/trs80/blk/602 b/arch/z80/trs80/blk/602 similarity index 100% rename from recipes/trs80/blk/602 rename to arch/z80/trs80/blk/602 diff --git a/recipes/trs80/blk/603 b/arch/z80/trs80/blk/603 similarity index 100% rename from recipes/trs80/blk/603 rename to arch/z80/trs80/blk/603 diff --git a/recipes/trs80/blk/604 b/arch/z80/trs80/blk/604 similarity index 100% rename from recipes/trs80/blk/604 rename to arch/z80/trs80/blk/604 diff --git a/recipes/trs80/blk/605 b/arch/z80/trs80/blk/605 similarity index 100% rename from recipes/trs80/blk/605 rename to arch/z80/trs80/blk/605 diff --git a/recipes/trs80/blk/606 b/arch/z80/trs80/blk/606 similarity index 100% rename from recipes/trs80/blk/606 rename to arch/z80/trs80/blk/606 diff --git a/recipes/trs80/blk/607 b/arch/z80/trs80/blk/607 similarity index 100% rename from recipes/trs80/blk/607 rename to arch/z80/trs80/blk/607 diff --git a/recipes/trs80/blk/609 b/arch/z80/trs80/blk/609 similarity index 100% rename from recipes/trs80/blk/609 rename to arch/z80/trs80/blk/609 diff --git a/recipes/trs80/blk/610 b/arch/z80/trs80/blk/610 similarity index 100% rename from recipes/trs80/blk/610 rename to arch/z80/trs80/blk/610 diff --git a/recipes/trs80/blk/612 b/arch/z80/trs80/blk/612 similarity index 100% rename from recipes/trs80/blk/612 rename to arch/z80/trs80/blk/612 diff --git a/recipes/trs80/blk/613 b/arch/z80/trs80/blk/613 similarity index 100% rename from recipes/trs80/blk/613 rename to arch/z80/trs80/blk/613 diff --git a/recipes/trs80/xcomp.fs b/arch/z80/trs80/xcomp.fs similarity index 100% rename from recipes/trs80/xcomp.fs rename to arch/z80/trs80/xcomp.fs diff --git a/recipes/z80mbc2/Makefile b/arch/z80/z80mbc2/Makefile similarity index 79% rename from recipes/z80mbc2/Makefile rename to arch/z80/z80mbc2/Makefile index 8e4ee11..e73c393 100644 --- a/recipes/z80mbc2/Makefile +++ b/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 diff --git a/recipes/z80mbc2/xcomp.fs b/arch/z80/z80mbc2/xcomp.fs similarity index 100% rename from recipes/z80mbc2/xcomp.fs rename to arch/z80/z80mbc2/xcomp.fs diff --git a/blk/001 b/blk/001 index d5cbb0c..30ae562 100644 --- a/blk/001 +++ b/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 diff --git a/recipes/rc2014/blk/613 b/blk/400 similarity index 100% rename from recipes/rc2014/blk/613 rename to blk/400 diff --git a/doc/faq.txt b/doc/faq.txt new file mode 100644 index 0000000..40b8c78 --- /dev/null +++ b/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". + diff --git a/doc/hardware.txt b/doc/hardware.txt deleted file mode 100644 index 935cb60..0000000 --- a/doc/hardware.txt +++ /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. diff --git a/doc/hw/8086/pcat.txt b/doc/hw/8086/pcat.txt new file mode 100644 index 0000000..826bc1e --- /dev/null +++ b/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...). diff --git a/doc/hw/arduinouno/at28.txt b/doc/hw/arduinouno/at28.txt new file mode 100644 index 0000000..d6b4a1b --- /dev/null +++ b/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/ diff --git a/recipes/arduinouno/at28dump.asm b/doc/hw/arduinouno/code/at28dump.asm similarity index 100% rename from recipes/arduinouno/at28dump.asm rename to doc/hw/arduinouno/code/at28dump.asm diff --git a/recipes/arduinouno/at28wr.asm b/doc/hw/arduinouno/code/at28wr.asm similarity index 100% rename from recipes/arduinouno/at28wr.asm rename to doc/hw/arduinouno/code/at28wr.asm diff --git a/recipes/arduinouno/at28wr.jpg b/doc/hw/arduinouno/img/at28wr.jpg similarity index 100% rename from recipes/arduinouno/at28wr.jpg rename to doc/hw/arduinouno/img/at28wr.jpg diff --git a/doc/hw/at28.txt b/doc/hw/at28.txt new file mode 100644 index 0000000..b0bdfb7 --- /dev/null +++ b/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. diff --git a/recipes/rc2014/avr.md b/doc/hw/avr.txt similarity index 78% rename from recipes/rc2014/avr.md rename to doc/hw/avr.txt index d6d8823..767c946 100644 --- a/recipes/rc2014/avr.md +++ b/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. diff --git a/recipes/rc2014/ps2ctl.asm b/doc/hw/code/ps2ctl.asm similarity index 100% rename from recipes/rc2014/ps2ctl.asm rename to doc/hw/code/ps2ctl.asm diff --git a/doc/hw/intro.txt b/doc/hw/intro.txt new file mode 100644 index 0000000..e7479fb --- /dev/null +++ b/doc/hw/intro.txt @@ -0,0 +1,65 @@ +# 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. + +# Organisation of this folder + +While /doc's top folder contain documentation about software, +this folder contains instructions and schematics about ways to +get Collapse OS running on actual hardware. + +Each CPU architecture has its own subfolder with recipes about +specific machines of that arch, while /doc/hw's top folder +contain instructions on broader topics, such as SD cards, +floppies, EEPROM, etc. + +Most instructions have companion code in /arch that is conve- +niently wrapped in Makefiles for easy building. + +# How to use + +If you want to run Collape OS on real hardware, browse this +folder's contents until you find something that closely matches +your own hardware (or hardware-to-be). + +If you live in a pre-collapse world and are looking for an easy +platform to try Collapse OS on, 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. + +# Drivers + +Most instructions in this subfolder tell you to add drivers to +your Collapse OS. What is meant by this is that you need to +rebuild your binary with an augmented xcomp unit. See +doc/bootstrap.txt for details, but the short version is: + +When instructions tell you to declare constant XXX, then load +drivers from block BYYY and then add word ZZZ to the initial- +ization string, what is meant is that: + +1. At the top of your xcomp unit, add constant XXX next to other + declarations. +2. Between "xcomp core low" and "xcomp core high" loading, + insert the loading of BYYY. Order may matter. +3. At the end, in the ,"" string just before EOT, insert the + ZZZ word. Order may matter. diff --git a/doc/hw/ps2.txt b/doc/hw/ps2.txt new file mode 100644 index 0000000..99aa565 --- /dev/null +++ b/doc/hw/ps2.txt @@ -0,0 +1,79 @@ +# Interfacing a PS/2 keyboard + +Collapse OS needs a way to input commands and keyboards are one +of the most straightforward ways to proceed. The PS/2 protocol +is very widespread and relatively simple. + +We explain here how to interface a PS/2 keyboard with a RC2014. + +# Gathering parts + +* A RC2014 Classic that could install the base recipe +* A PS/2 keyboard. A USB keyboard + PS/2 adapter should work, + but I haven't tried it yet. +* A PS/2 female connector. +* ATtiny85/45/25 (main MCU for the device) +* 74xx595 (shift register) +* 40106 inverter gates +* Diodes for A*, IORQ, RO. +* Proto board, RC2014 header pins, wires, IC sockets, etc. +* AVRA (https://github.com/hsoft/avra). The code for this recipe + hasn't been translated to Collapse OS' AVR assembler yet. + +# Building the PS/2 interface + +Let's start with the PS/2 connector (see img/ps2-conn.png), +which has two pins. + +Both are connected to the ATtiny45, CLK being on PB2 to have +INT0 on it. + +The DATA line is multi-use. That is, PB1 is connected both to +the PS/2 data line and to the 595's SER. This saves us a +precious pin. + +The ATtiny 45 (img/ps2-t45.png) hooks everything together. CE +comes from the z80 bus (img/ps2-z80.png). + +The 595 (img/ps2-595.png) allows us to supply the z80 bus with +data within its 375ns limits. SRCLR is hooked to the CE line so +that whenever a byte is read, the 595 is zeroed out as fast as +possible so that the z80 doesn't read "false doubles". + +The 595, to have its SRCLR becoming effective, needs a RCLK +trigger, which doesn't happen immediately. It's the ATtiny45, in +its PCINT interrupt, that takes care of doing that trigger (as +fast as possible). + +Our device is read only, on one port. That makes the "Chip +Enable" (CE) selection rather simple. In my design, I chose the +IO port 8, so I inverted A3. I chose a 40106 inverter to do +that, do as you please for your own design. + +I wanted to hook CE to a flip flop so that the MCU could relax a +bit more w.r.t. reacting to its PB4 pin changes, but I didn't +have NAND gates that are fast enough in stock, so I went with +this design. But otherwise, I would probably have gone the +flip-flop way. Seems more solid. + +Then, all you need to do is to assemble code/ps2ctl.asm and load +it onto your ATtiny. + +# Using the PS/2 interface + +To use this interface, you have to build a new Collapse OS +binary. This binary needs two things. + +First, we need a "(ps2kc)" routine (see doc/protocol.txt). In +this case, it's easy, it's ": (ps2kc) 8 PC@ ;". Then, we can +load PS/2 subsystem. You add "411 414 LOADR". Then, at +initialization, you add "PS2$". You also need to define PS2_MEM +at the top. You can probably use "SYSVARS + 0x7a". + +The PS/2 subsystem provides "(key)" from "(ps2kc)". + +For debugging purposes, you might not want to go straight to +plugging PS/2 "(key)" into the system. What I did myself was to +load the PS/2 subsystem *before* ACIA (which overrides with its +own "(key)") and added a dummy word in between to access PS/2's +key. diff --git a/doc/hw/sdcard.txt b/doc/hw/sdcard.txt new file mode 100644 index 0000000..1ef4316 --- /dev/null +++ b/doc/hw/sdcard.txt @@ -0,0 +1,29 @@ +# Accessing SD cards + +SD cards support the SPI protocol. If you have a SPI relay +(doc/hw/spi.txt) and a driver for it that implement the SPI +protocol (doc/protocol.txt), you're a few steps away from +accessing SD cards! + +What you need to do is to add the SDC subsystem to your Collapse +OS binary. First, define SDC_DEVID to a mask selecting the +proper device on your SPI relay (this is what is sent to +"(spie)"). For example, a SDC_DEVID or 1, 2, 4, or 8 would +select SPI device 1, 2, 3 or 4. + +The subsystem is loaded with "423 436 LOADR". + +Initialization of the SDC system is done in multiple steps. +First, the BLK system needs to be initialized with "BLK$". Then +you can plug SDC@ and SDC! into BLK with "' SDC@ BLK@* !" and +"' SDC! BLK! !". That only needs to be done once per boot. + +Then, the SD card that was inserted needs to be initialized. You +can do it with "SDC$". If you have no error, it means that the +system can spek to your card, that sync is fine, etc. You can +read/write right now. SDC$ needs to run every time a new card +is inserted. + +Collapse OS' SDC drivers are designed to read from the very +first 512 sector of the card, mapping them to blocks +sequentially, 2 sectors per block. diff --git a/doc/hw/spi.txt b/doc/hw/spi.txt new file mode 100644 index 0000000..d7f90be --- /dev/null +++ b/doc/hw/spi.txt @@ -0,0 +1,13 @@ +# Communicating through SPI + +Many very useful device are able to communicate through the SPI +protocol, for example, SD cards and AVR MCUs. In many cases, +however, CPUs can't "speak SPI" because of their inability to +bit-bang. + +In most cases, we need an extra peripheral, which we can build +ourselves, to interface with devices that "speak SPI". We call +this peripheral a SPI relay. + +The design of those relays depend on the CPU architecture. See +spi.txt in arch-specific folders for more information. diff --git a/doc/hw/tty.txt b/doc/hw/tty.txt new file mode 100644 index 0000000..bc89398 --- /dev/null +++ b/doc/hw/tty.txt @@ -0,0 +1,11 @@ +# Remote access to Collapse OS + +If you interface to your machine through a serial communication +device and that you have a POSIX environment on the other side, +Collapse OS provides tools in /tools which can be very useful +to you. + +Uploading data to Collapse OS' memory is a frequent need +and /tools/upload can help you there. + +See details in the /tools folder directly. diff --git a/recipes/sms/ps2ctl.fs b/doc/hw/z80/code/smsps2ctl.fs similarity index 100% rename from recipes/sms/ps2ctl.fs rename to doc/hw/z80/code/smsps2ctl.fs diff --git a/recipes/sms/ps2-to-sms.png b/doc/hw/z80/img/ps2-to-sms.png similarity index 100% rename from recipes/sms/ps2-to-sms.png rename to doc/hw/z80/img/ps2-to-sms.png diff --git a/recipes/rc2014/spirelay.jpg b/doc/hw/z80/img/spirelay.jpg similarity index 100% rename from recipes/rc2014/spirelay.jpg rename to doc/hw/z80/img/spirelay.jpg diff --git a/doc/hw/z80/rc2014.txt b/doc/hw/z80/rc2014.txt new file mode 100644 index 0000000..9a91c53 --- /dev/null +++ b/doc/hw/z80/rc2014.txt @@ -0,0 +1,65 @@ +# RC2014 + +The RC2014[1] is a nice and minimal z80 system that has the +advantage of being available in an assembly kit. Assembling it +yourself involves quite a bit of soldering due to the bus +system. However, one very nice upside of that bus system is that +each component is isolated and simple. + +The machine used in this recipe is the "Classic" RC2014 with an +8k ROM module , 32k of RAM, a 7.3728Mhz clock and a serial I/O. + +The ROM module being supplied in the assembly kit is an EPROM, +not EEPROM, so you can't install Collapse OS on it. You'll have +to supply your own. + +There are many options around to boot arbitrary sources. What +was used in this recipe was a AT28C64B EEPROM module. I chose it +because it's compatible with the 8k ROM module which is very +convenient. If you do the same, however, don't forget to set the +A14 jumper to high because what is the A14 pin on the AT27 ROM +module is the WE pin on the AT28! Setting the jumper high will +keep is disabled. + +The goal is to have the shell running and accessible through the +Serial I/O. + +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. If you don't have any but have a Arduino Uno, +take a look at doc/hw/arduinouno. + +# Gathering parts + +* A "classic" RC2014 with Serial I/O +* An AT28C64B and a way to write to it. +* A FTDI-to-TTL cable to connect to the Serial I/O module + +# Build the binary + +Building the binary is as simple as running "make" in +/arch/z80/rc2014. This will yield "os.bin" which can then be +written to EEPROM. + +This build is controlled by the xcomp.fs unit, which loads +blk/618. That's what you need to modify if you want to customize +your build. + +# Emulate + +The Collapse OS project includes a RC2014 emulator suitable for +this image. You can invoke it with "make emul". + +# Running + +Put the AT28 in the ROM module, don't forget to set the A14 +jumper high, then power the thing up. Connect a FTDI-to-TTL +cable to the Serial I/O module and identify the tty bound to it +(in my case, "/dev/ttyUSB0"). Then: + + screen /dev/ttyUSB0 115200 + +Press the reset button on the RC2014 and the "ok" prompt should +appear. + +[1]: https://rc2014.co.uk diff --git a/doc/hw/z80/sio.txt b/doc/hw/z80/sio.txt new file mode 100644 index 0000000..3412890 --- /dev/null +++ b/doc/hw/z80/sio.txt @@ -0,0 +1,22 @@ +# Using Zilog's SIO as a console + +The RC2014 has an optional module called the Dual Serial Module +SIO/2 which is built around Zilog's SIO chip. This module is +nice because when paired with the Dual Clock Module and when +using port B, it's possible to run a UART with a baud rate lower +than 115200. + +Collapse OS has a driver for it (although for now, only port A +is supported by it). Let's use it. + +* Let's assume a xcomp unit similar to the one in + /arch/z80/rc2014. +* Locate SIO driver in /arch/z80/rc2014/blk +* The driver main page gives you references for declarations and + for code. +* In the base xcomp unit, replace ACIA declarations with SIO's +* Replace ACIA code with SIO's +* At the bottom, replace "ACIA$" with "SIO$". + +Rebuild the binary and you're done. "(key)" and "(emit)" will +go through the SIO. diff --git a/doc/hw/z80/sms.txt b/doc/hw/z80/sms.txt new file mode 100644 index 0000000..91d6aec --- /dev/null +++ b/doc/hw/z80/sms.txt @@ -0,0 +1,81 @@ +# Sega Master System + +The Sega Master System was a popular gaming console running on +z80. It has a simple, solid design and, most interestingly of +all, its even more popular successor, the Megadrive (Genesis) +had a z80 system for compatibility! + +This makes this platform *very* scavenge-friendly and worth +working on. + +SMS Power[1] is an awesome technical resource to develop for this +platform and this is where most of my information comes from. + +This platform is tight on RAM. It has 8k of it. However, if you +have extra RAM, you can put it on your cartridge. + +# Gathering parts + +* A Sega Master System or a MegaDrive (Genesis). +* A Megadrive D-pad controller. +* A way to get an arbitrary ROM to run on the SMS. Either through a writable + ROM cartridge or an Everdrive[2]. + +# Hacking up a ROM cart + +SMS Power has instructions to transform a ROM cartrige into a +battery-backed SRAM one, which allows you to write to it through +another device you'll have to build. This is all well and good, +but if you happen to have an AT28 EEPROM, things are much +simpler! + +Because AT28 EEPROM are SRAM compatible, they are an +almost-drop-in replacement to the ROM you'll pop off your +cartridge. AT28 are a bit expensive, but they're so handy! For +SMS-related stuff, I recommend the 32K version instead of the 8K +one because fitting Collapse OS with fonts in 8K is really +tight. + +1. De-solder the ROM +2. Take a 28 pins IC socket +3. Cut off its WE pin (the one just under VCC), leaving a tiny + bit of metal. +4. Hard-wire it to VCC so that WE is never enabled. +5. Solder your socket where the ROM was. +6. Insert Collapse OS-filled EEPROM in socket. + +As simple as this! (Note that this has only been tested on a SMS +so far. I haven't explored whether this can run on a megadrive). + +# Build the ROM + +Running "make os.sms" in /arch/z80/sms will produce a "os.sms" +ROM that can be put as is on a SD card to the everdrive or +flashed as is on a writable ROM cart. Then, just run the thing! + +To run Collapse OS in a SMS emulator, run "make emul". + +# Usage + +Our input is a D-Pad and our output is a TV. The screen is 32x28 +characters. A bit tight, but usable. + +D-Pad is used as follow: + +* There's always an active cursor. On boot, it shows "a". +* Up/Down increase/decrease the value of the cursor. +* Left/Right does the same, by increments of 5. +* A button is backspace. +* B button skips cursor to next "class" (number, lowcase, + upcase, symbols). +* C button "enters" cursor character and advance the cursor by + one. +* Start button is like pressing Return. + +Of course, that's not a fun way to enter text, but using the +D-Pad is the easiest way to get started which doesn't require +soldering. Your next step after that would be to build a PS/2 +keyboard adapter! See smsps2.txt + +[1]: http://www.smspower.org +[2]: https://krikzz.com diff --git a/doc/hw/z80/smsps2.txt b/doc/hw/z80/smsps2.txt new file mode 100644 index 0000000..1acfad7 --- /dev/null +++ b/doc/hw/z80/smsps2.txt @@ -0,0 +1,124 @@ +# PS/2 keyboard on the SMS + +Using the shell with a D-pad on the SMS is doable, but not fun +at all! We're going to build an adapter for a PS/2 keyboard to +plug as a SMS controller. + +The PS/2 logic will be the same as the regular PS/2 adapter (see +doc/hw/ps2.txt) but instead of interfacing directly with the +bus, we interface with the SMS' controller subsystem (that is, +what we poke on ports 0x3f and 0xdc). + +How will we achieve that? A naive approach would be "let's limit +ourselves to 7bit ASCII and put TH, TR and TL as inputs". That +could work, except that the SMS will have no way reliable way +(except timers) of knowing whether polling two identical values +is the result of a repeat character or because there is no new +value yet. + +On the AVR side, there's not way to know whether the value has +been read, so we can't to like on the RC2014 and reset the value +to zero when a RO request is made. + +We need communication between the SMS and the PS/2 adapter to be +bi-directional. That bring the number of usable pins down to 6, +a bit low for a proper character range. So we'll fetch each +character in two 4bit nibbles. TH is used to select which nibble +we want. + +TH going up also tells the AVR MCU that we're done reading the +character and that the next one can come up. + +As always, the main problem is that the AVR MCU is too slow to +keep up with the rapid z80 polling pace. In the regular adapter, +I hooked CE directly on the AVR, but that was a bit tight +because the MCU is barely fast enough to handle this signal +properly. I did that because I had no proper IC on hand to build +a SR latch. + +In this recipe, I do have a SR latch on hand, so I'll use it. TH +triggering will also trigger that latch, indicating to the MCU +that it can load the next character in the '164. When it's done, +we signal the SMS that the next char is ready by resetting the +latch. That means that we have to hook the latch's output to TR. + +Nibble selection on TH doesn't involve the AVR at all. All 8 +bits are pre-loaded on the '164. We use a 4-channel multiplexer +to make TH select either the low or high bits. + +# Gathering parts + +* A SMS that can run Collapse OS +* A PS/2 keyboard. A USB keyboard + PS/2 adapter should work, + but I haven't tried it yet. +* A PS/2 female connector. +* A SMS controller you can cannibalize for the DB-9 connection. + A stock DB-9 connector isn't deep enough. +* ATtiny85/45/25 (main MCU for the device) +* 74xx164 (shift register) +* 74xx157 (multiplexer) +* A NOR SR-latch. I used a 4043. +* Proto board, wires, IC sockets, etc. + +# Historical note + +As I was building this prototype, I was wondering how I would +debug it. I could obviously not hope for it to work as a +keyboard adapter on the first time, right on port A, driving the +shell. I braced myself mentally for a logic analyzer session and +some kind of arduino-based probe to test bit banging results. + +And then I thought "why not use the genesis?". Sure, driving the +shell with the D-pad isn't fun at all, but it's possible. So I +hacked myself a temporary debug kernel with a "a" command doing +a probe on port B. It worked really well! + +It was a bit less precise than logic analyzers and a bit of +poking-around and crossing-fingers was involved, but overall, I +think it was much less effort than creating a full test setup. + +There's a certain satisfaction to debug a device entirely on +your target machine... + +# Building the PS/2 interface + +See schematic at img/ps2-to-sms.png. The PS/2-to-AVR part is +identical to doc/hw/ps2.txt. + +We control the '164 from the AVR in a similar way to what we did +in rc2014/ps2, that is, sharing the DATA line with PS/2 (PB1). +We clock the '164 with PB3. Because the '164, unlike the '595, +is unbuffered, no need for special RCLK provisions. + +Most of the wiring is between the '164 and the '157. Place them +close. The 4 outputs on the '157 are hooked to the first 4 lines +on the DB-9 (Up, Down, Left, Right). + +In my prototype, I placed a 1uf decoupling cap next to the AVR. +I used a 10K resistor as a pull-down for the TH line (it's not +always driven). + +If you use a 4043, don't forget to wire EN. On the '157, don't +forget to wire ~G. + +The code expects a SR-latch that works like a 4043, that is, S +and R are triggered high, S makes Q high, R makes Q low. R is +hooked to PB4. S is hooked to TH (and also the A/B on the '157). +Q is hooked to PB0 and TL. + +The code for the ATtiny is in code/smsps2ctl.fs. You can build +it with /cvm/avra.sh. + +# Building the binary + +We start with the base SMS xcomp and add a few things: + +1. at the top: "SYSVARS 0x72 + CONSTANT PS2_MEM" +2. After VDP load: "621 LOAD : (ps2kc) (ps2kcB) ;" (that binds + us to port B) +3. Right after: "411 414 LOADR" (that gives us "(key)") +4. After "VDP$": "PS2$". + +Rebuild, send to SMS, then run with your keyboard interface +plugged to PortB. It should mostly work. There are still a few +glitches to iron out... diff --git a/doc/hw/z80/spi.txt b/doc/hw/z80/spi.txt new file mode 100644 index 0000000..4cc2d99 --- /dev/null +++ b/doc/hw/z80/spi.txt @@ -0,0 +1,74 @@ +# Building a SPI relay for the z80 + +In this recipe, we build a SPI relay (see /doc/hw/spi.txt) for +a RC2014. + +# Gathering parts + +* A RC2014 Classic +* A proto board + header pins with 39 positions so we can make + a RC2014 card. +* Diodes, resistors and stuff +* 40106 (Inverter gates) +* 74xx138 (Decoder) +* 74xx375 (Latches) +* 74xx125 (Buffer) +* 74xx161 (Binary counter) +* 74xx165 (Parallel input shift register) +* 74xx595 (Shift register) + +# Building the SPI relay + +The schematic (img/spirelay.jpg) works well with the SD Card +subsystem (B420). Of course, it's not the only possible design +that works, but I think it's one of the most straighforwards. + +This relay communicates through the z80 bus with 2 ports, DATA +and CTL and allows up to 4 devices to be connected to it at +once, although only one device can ever be active at once. This +schema only has 2 (and the real prototype I've built from it), +but the '375 has room for 4. In this schema, DATA is port 4, CTL +is port 5. + +We activate a device by sending a bitmask to CTL, this will end +up in the '375 latches and activate the SS pin of one of the +device, or deactivate them all if 0 is sent. + +You then initiate a SPI exchange by sending a byte to send to +the DATA port. This byte will end up in the '165 and the '161 +counter will be activated, triggering a clock for the SPI +exchange. At each clock, a bit is sent to MOSI from the '161 and +received from MISO into the '595, which is the byte sent to the +z80 bus when we read from DATA. + +When the '161 is wired to the system clock, as it is in the +schema, two NOPs are a sufficient delay between your DATA write +and subsequent DATA read. + +However, if you build yourself some kind of clock override and +run the '161 at something slower than the system clock, those 2 +NOPs will be too quick. That's where that '125 comes into play. +When reading CTL, it spits RUNNING into D0. This allows you to +know when the result of the SPI exchange is ready to be fetched. +Make sure you AND away other bits, because they'll be garbage. + +The '138 is to determine our current IORQ mode (DATA/CTL and +WR/RO), the '106 is to provide for those NOTs sprinkled around. + +Please note that this design is inspired by +https://www.ecstaticlyrics.com/electronics/SPI/fast_z80_interface.html + +Advice 1: Make SCK polarity configurable at all 3 endpoints (the +595, the 165 and SPI connector). Those jumpers will be useful +when you need to mess with polarity in your many tinkering +sessions to come. + +Advice 2: Make input CLK override-able. SD cards are plenty fast +enough for us to use the system clock, but you might want to +interact with devices that require a slower clock. + +# Driving the relay + +There is a provider for the SPI protocol (doc/protocol.txt) that +work with this device in B418. It needs SPI_DATA and SPI_CTL +constants which in this case are 4 and 5 respectively. diff --git a/doc/hw/z80/ti84.txt b/doc/hw/z80/ti84.txt new file mode 100644 index 0000000..3da4b10 --- /dev/null +++ b/doc/hw/z80/ti84.txt @@ -0,0 +1,145 @@ +# TI-84+ + +The TI-84+ is a machine with many advantages, one being that +it's very popular. It also has a lot of flash memory and RAM. + +Its builtin keyboard and screen, however, are hard to use, +especially the screen. With a tiny font, the best we can get is +a 24x10 console. + +There is, however, a built-in USB controller that might prove +very handy. + +I haven't opened one up yet, but apparently, they have limited +scavenging value because its z80 CPU is packaged in a +TI-specific chip. Due to its sturdy design, and its ample RAM +and flash, we could imagine it becoming a valuable piece of +equipment if found intact. + +The best pre-collapse ressource about it is WikiTI[1]. + +As it is now, with its tiny screen and cumbersome keyboard, +Collapse OS is not really usable on the TI-84+. One could +imagine a scenario where one has a terminal and uses the TI-84+ +through the link for its large amount of flash and RAM. But +using it standalone? Nah, not even post-collapse. + +Therefore, this recipe is more of a "look, I run!" demo. + +# Gathering parts + +* A TI-84+ +* A USB cable +* tilp[2] +* mktiupgrade[3] + +# Build the ROM + +Running "make" in /arc/z80/ti84 will result in "os.rom" being +created. + +# Emulate + +Collapse OS has a builtin TI-84+ emulator using XCB for display +in emul/hw/ti. You can invoke it with "make emul". + +You will start with a blank screen, it's normal, you haven't +pressed the "ON" key yet. This key is mapped to tilde (~) in the +emulator. Once you press it, the Collapse OS prompt will appear. +See emul/hw/ti/README.md for details. + +# Upload to the calculator + +# Background notes + +Getting software to run on it is a bit tricky because it needs +to be signed with TI-issued private keys. Those keys have long +been found and are included in keys/. With the help of the +mktiupgrade, an upgrade file can be prepared and then sent +through the USB port with the help of tilp. + +That, however, requires a modern computing environment. As of +now, there is no way of installing Collapse OS on a TI-8X+ +calculator from another Collapse OS system. + +Because it is not on the roadmap to implement complex +cryptography in Collapse OS, the plan is to build a series of +pre-signed bootloader images. The bootloader would then receive +data through either the Link jack or the USB port and write that +to flash (I haven't verified that yet, but I hope that data +written to flash this way isn't verified cryptographically by +the calculator). + +As modern computing fades away, those pre-signed binaries would +become opaque, but at least, would allow bootstrapping from +post-modern computers. + +# Instructions + +WARNING: the instructions below will wipe all the contents of +your calculator, including TI-OS. + +To send your ROM to the calculator, you'll need two more tools: +mktiupgrade and tilp. + +Once you have them, you need to place your calculator in +"bootloader mode", that is, in a mode where it's ready to +receive a new binary from its USB cable. To do that you need +to: + +1. Shut down the calculator by removing one of the battery. +2. Hold the DEL key +3. But the battery back. +4. A "Waiting... Please install operating system now" message\ + will appear. + +Once this is done, you can plug the USB cable in your computer +and run "make send". This will create an "upgrade file" with +mktiupgrade and then push that upgrade file with tilp. tilp will +prompt you at some point. Press "1" to continue. + +When this is done, you can press the ON button to see Collapse +OS' prompt! + +# Validation errors + +Sometimes, when uploading an upgrade file to your calculator, +you'll get a validation error. You can always try again, but in +my own experience, some specific binaries will simply always be +refused by the calculator. Adding random "nop" or reordering +lines (when it makes sense, of course) should fix the problem. + +I'm not sure whether it's a bug with the calculator or with +mktiupgrade. + +# Usage + +The shell works like a normal BASIC shell, but with very tight +screen space. + +When pressing a "normal" key, it spits the symbol associated to +it depending on the current mode. In normal mode, it spits the +digit/symbol. In Alpha mode, it spits the letter. In Alpha+2nd, +it spits the uppercase letter. + +Special keys are Alpha and 2nd. Pressing them toggles the +associated mode. Alpha and 2nd mode don't persist for more than +one character. After the character is spit, mode reset to +normal. + +Pressing 2nd then Alpha will toggle the A-Lock mode, which is a +persistent mode. The A-Lock mode makes Alpha enabled all the +time. While A-Lock mode is enabled, you have to enable Alpha to +spit a digit/symbol. + +Simultaneous keypresses have undefined behavior. One of the keys +will be registered as pressed. Mode key don't work by +simultaneously pressing them with a "normal" key. The presses +must be sequential. + +Keys that aren't a digit, a letter, a symbol that is part of +7-bit ASCII or one of the two mode key have no effect. + +[1]: http://wikiti.brandonw.net/index.php +[2]: http://lpg.ticalc.org/prj_tilp/ +[3]: https://github.com/KnightOS/mktiupgrade diff --git a/doc/hw/z80/trs80.txt b/doc/hw/z80/trs80.txt new file mode 100644 index 0000000..97768e5 --- /dev/null +++ b/doc/hw/z80/trs80.txt @@ -0,0 +1,311 @@ +# TRS-80 Model 4p + +The TRS-80 (models 1, 3 and 4) are among the most popular z80 +machines. They're very nicely designed and I got my hands on a +4p with two floppy disk drives and a RS-232 port. In this +recipe, we're going to get Collapse OS running on it. + +# Not entirely standalone + +Collapse OS uses the TRS-80 drivers rather than its own. On most +TRS-80 models, those drivers are on ROM, but in the case of the +4P model, those drivers are on the TRSDOS disk (well, from what +I understand, not all of it, but still, a big part of it). + +It would be preferable to develop drivers from scratch, but it +represents a significant effort for a modest payout (because +it's only actually useful when you want to use a 4P model that +has no TRSDOS disk). + +Maybe those drivers will be developed later, but it's not a +priority for now. + +# Floppy or RS-232? + +There are many ways to get Collapse OS to run on it. One would +involve writing it to a floppy. I bought myself old floppy +drives for that purpose, but I happen to not have any functional +computer with a floppy port on it. I still have the motherboard +of my old pentium, but I don't seem to have a video card for it +any more. + +Because my 4p has a RS-232 port and because I have equipment to +do serial communication from modern machines (I didn't have a +DB-9 to DB-25 adapter though, I had to buy one), I chose that +route. + +# Gathering parts + +* A TRS-80 model 4p with a RS-232 port +* A TRSDOS 6.x disk +* A means to do serial communication. In my case, that meant: + * A USB-to-serial device + * A null modem cable + * A DB-9 gender changer + * A DB-9 to DB-25 adapter + +# Overview + +We need to send sizeable binary programs through the RS-232 port +and then run it. The big challenge here is ensuring data +integrity. Sure, serial communication has parity check, but it +has no helpful way of dealing with parity errors. When parity +check is enabled and that a parity error occurs, the byte is +simply dropped on the receiving side. Also, a double bit error +could be missed by those checks. + +What we'll do here is to ping back every received byte back and +have the sender do the comparison and report mismatched data. + +Another problem is ASCII control characters. When those are sent +across serial communication channels, all hell breaks lose. When +sending binary data, those characters have to be avoided. We use +tools/ttysafe for that. + +Does TRSDOS have a way to receive this binary inside these +constraints? Not to my knowledge. As far as I know, the COMM +program doesn't allow this. + +What are we going to do? We're going to punch in a binary +program to handle that kind of reception! You're gonna feel real +badass about it too... + +# Keyboard tips + +* "_" is CLEAR+ENTER. + +# Building the binary + +You can build the binary to send to the TRS-80 with "make" in +/arch/z80/trs80, which will yield +"os.bin". You'll need it later. + +# Testing serial communication + +The first step here is ensuring that you have bi-directional +serial communication. To do this, first prepare your TRS-80: + + set *cl to com + setcomm (word=8,parity=no) + +The first line loads the communication driver from the COM/DRV +file on the TRSDOS disk and binds it to *cl, the name generally +used for serial communication devices. The second line sets +communication parameters in line with what is generally the +default on modern machine. Note that I left the default of 300 +bauds as-is. + +Then, you can run "COMM *cl" to start a serial communication +console. + +Then, on the modern side, use your favorite serial communication +program and set the tty to 300 baud with option "raw". Make sure +you have -parenb. + +If your line is good, then what you type on either side should +echo on the other side. If it does not, something's wrong. +Debug. + +# Punching in the goodie + +As stated in the overview, we need a program on the TRS-80 that: + +1. Listens to *cl +2. Echoes each character back to *cl +3. Adjusts ttysafe escapes +4. Stores received bytes in memory + +You're in luck: that program has already been written. It's in +B612 and B613 in /arch/z80/trs80/blk. By running "make" earlier, +you have, in your current folder, a blkfs that contains those +blocks. To have a forth running on it, you could overwrite +/cvm/blkfs and run /cvm/forth. You can then compile it with: + + 5 LOAD ( z80 assembler ) + 0x0238 CONSTANT COM_DRV_ADDR + 0x3000 CONSTANT DEST_ADDR + 612 LOAD + 613 LOAD + +Then, you can use "DUMP" to visualize the data you'll need to +punch in: + + H@ ORG @ - ORG @ DUMP + +It can run from any offset (all jumps in it are relative), but +writes to DEST_ADDR. Make sure you don't place it in a way to be +overwritten by its received data. + +Wondering what is that COM_DRV_ADDR constant? That's the DCB +handle of your *cl device. You will need to get that address +before you continue. Go read the following section and come back +here. + +How will you punch that in? The "debug" program! This very +useful piece of software is supplied in TRSDOS. To invoke it, +first run "debug (on)" and then press the BREAK key. You'll get +the debug interface which allows you to punch in any data in any +memory address. Let's use 0x5000 which is the offset it's +designed for. + +For reference: to go back to the TRSDOS prompt, it's +"o". + +First, display the 0x5000-0x503f range with the d5000 +command (I always press Enter by mistake, but it's space you +need to press). Then, you can begin punching in with +h5000. This will bring up a visual indicator of the +address being edited. Punch in the stuff with a space in between +each byte and end the edit session with "x". + +# Getting your DCB address + +In the previous step, you need to set COM_DRV_ADDR to your "DCB" +address for *cl. That address is your driver "handle". To get +it, first get the address where the driver is loaded in memory. +You can get this by running "device (b=y)". That address you see +next to *cl? that's it. But that's not our DCB. + +To get your DBC, go explore that memory area. Right after the +part where there's the *cl string, there's the DCB address +(little endian). On my setup, the driver was loaded in 0x0ff4 +and the DCB address was 8 bytes after that, with a value of +0x0238. Don't forget that z80 is little endian. 38 will come +before 02. + +# Saving that program for later + +If you want to save yourself typing for later sessions, why not +save the program you've painfully typed to disk? TRSDOS enables +that easily. Let's say that you typed your program at 0x5000 and +that you want to save it to RECV/CMD on your second floppy +drive, you'd do: + + dump recv/cmd:1 (start=x'5000',end=x'5030',tra='5000') + +A memory range dumped this way will be re-loaded at the same +offset through "load recv/cmd:1". Even better, TRA indicates +when to jump after load when using the RUN command. Therefore, +you can avoid all this work above in later sessions by simply +typing "recv" in the DOS prompt. + +Note that you might want to turn "debug" off for these commands +to run. I'm not sure why, but when the debugger is on, launching +the command triggers the debugger. + +# Sending binary through the RS-232 port + +Once you're finished punching your program in memory, you can +run it with g5000 (not space). If you've saved it to +disk, run "recv" instead. Because it's an infinite loop, your +screen will freeze. You can start sending your data. + +To that end, there's the tools/pingpong program. It takes a +device and a filename to send. Before you send the binary, make +it go through tools/ttysafe first (which just takes input from +stdin and spits tty-safe content to stdout): + + ./ttysafe < stage1.bin > stage1.ttysafe + +On OpenBSD, the invocation can look like: + + doas ./pingpong /dev/ttyU0 os.ttysafe + +You will be prompted for a key before the contents is sent. This +is because on OpenBSD, TTY configuration is lost as soon as the +TTY is closed, which means that you can't just run stty before +running pingpong. So, what you'll do is, before you press your +key, run "doas stty -f /dev/ttyU0 300 raw" and then press any +key on the pingpong invocation. + +If everything goes well, the program will send your contents, +verifying every byte echoed back, and then send a null char to +indicate to the receiving end that it's finished sending. This +will end the infinite loop on the TRS-80 side and return. That +should bring you back to a refreshed debug display and you +should see your sent content in memory, at the specified address +(0x3000 if you didn't change it). + +If there was no error during pingpong, the content should be +exact. Nevertheless, I recommend that you manually validate a +few bytes using TRSDOS debugger before carrying on. + +*debugging tip*: Sometimes, the communication channel can be a +bit stubborn and always fail, as if some leftover data was +consistently blocking the channel. It would cause a data +mismatch at the very beginning of the process, all the time. +What I do in these cases is start a "COMM *cl" session on one +side and a screen session on the other, type a few characters, +and try pingpong again. + +# Saving to disk + +If everything went well, you could run Collapse OS with +g3000. But instead of doing that, why not save it to +disk? + + dump cos/cmd:1 (start=x'5000',end=x'7000',tra='5000') + +And there we go! A Collapse OS launchable from floppy! + +# Sending blkfs to floppy + +As it is, your system fully supports reading and writing to +floppy drive 1. It also had *CL< to read a char from *cl and +*CL> to emit a char to *cl. + +That's all you need to have a full Collapse OS with access to +disk blocks. + +First, make sure your floppies are formatted. Collapse OS is +currently hardcoded to single side and single density, which +means there's a limit of 100 blocks per disk. + +You'll need to send those blocks through RS-232. Begin by taking +over the prompt: + + ' *CL> ' EMIT **! + ' *CL< ' KEY **! + +See B80 for details about those RAM offsets. Your serial link +now has the prompt. You will also have to make your newlines +CRLF. The TRS-80 wants CR only, but serial communications (and +blkup) expect CRLF: + + ' CRLF ' NL **! + +Now, you can use /tools/blkup to send a disk's contents. First, +extract the first 100 blocks from blkfs: + + dd if=emul/blkfs bs=1024 count=100 > d1 + +Now, insert your formatted disk in drive 1 and push your blocks: + + tools/blkup /dev/ttyUSB0 0 d1 + +It takes a while, but you will end up having your first 100 +blocks on floppy! Go ahead, LIST around. Then, repeat for other +disks. + +# Floppy organisation + +Making blkfs span multiple disk is a bit problematic with +regards to absolute block references in the code. You'll need to +work a bit to design your very own Collapse OS floppy set. See +/doc/usage.txt for details. + +# Coming back to keyboard + +Once you're done, you will want to go back to local control: + + ' CR ' NL **! + ' (emit) ' EMIT **! + ' (key) ' KEY **! + +# Self-hosting + +As it is, your installment of Collapse OS is self-hosting using +instructions from /doc/selfhost.txt. The difference is that +instead of writing the binary you have in memory to EEPROM, +you'll quit to TRSDOS with BYE and use TRSDOS' DUMP utility to +save to disk like you already did before. diff --git a/doc/hw/z80/z80mbc2.txt b/doc/hw/z80/z80mbc2.txt new file mode 100644 index 0000000..8da114c --- /dev/null +++ b/doc/hw/z80/z80mbc2.txt @@ -0,0 +1,57 @@ +# Z80-MBC2 + +The Z80-MBC2[1] combines a Z80 and an ATMEGA32A to provide a +CP/m capable computing environment. It features a SD card +bootloader which makes running Collapse OS on it rather simple. + +In this recipe, we're going to run Collapse OS on the Z80-MBC2, +interfacing through its serial port. We're going to use the +MBC's API to implement BLK on the SD card. + +# Gathering parts + +* A Z80-MBC2 computer with its SD card module and a properly + flashed "IOS" on the ATMega32A. +* A FTDI-to-TTL cable to connect to the serial port. + +# Building the binary + +Running "make" in arch/z80/z80mbc2 will yield "os.bin" which is +what we want. + +# Running on the Z80-MBC2 + +Mount the SD card on your modern computer and copy "os.bin" as +"autoboot.bin", overwriting the binary that was previously +there. + +We also have to copy the blkfs over. This is done by using IOS' +drive system. Each "DSxNyy.DSK" file on the card is a drive, +each drive has 512 track of 32 sectors of 512 bytes, so one +drive is plenty for our needs. Collapse OS hardcodes drive 0. + +Each drive is part of a set. IOS theoretically supports up to 10 +sets, but the binary shipped by default only accepts 4. You have +to overwrite an existing set. I used set 3. So, copy "blkfs" to +file "DS3N00.DSK". If you want, you can change the name of the +set by changing the contents of "DS3NAM.DAT". + +Put back the SD card in the Z80-MBC2 and power it up by +connecting the FTDI adapter to it (red: VCC, black: GND, green: +TX, white: RX). + +The FTDI adapter will show up as something like "ttyUSB0" (or +"ttyU0" on OpenBSD). Connect to it with "screen" or "cu" or +whatever you like. Baud rate of the Z80-MBC2 appears to be +hardcoded to 115200. + +Then, enable IOS program selection by holding RESET and USER at +the same time, wait 2 seconds, releasing RESET, wait 2 seconds, +releasing USER. You should then be given a 1-8 choice. + +You begin by selecting the proper disk set, which is through +choice 8, then you select the Autoboot binary through choice 4. + +You are now in Collapse OS. + +[1]: https://hackaday.io/project/159973-z80-mbc2-a-4-ics-homebrew-z80-computer diff --git a/doc/intro.txt b/doc/intro.txt index 60e2737..12f8e10 100644 --- a/doc/intro.txt +++ b/doc/intro.txt @@ -39,10 +39,11 @@ likely to have access to a modern computer. The best place to begin is to build the C VM of Collapse OS in /cvm. You can then begin playing with it with the help of usage.txt and impl.txt. -When you're ready to move to real hardware, read hardware.txt. +When you're ready to move to real hardware, read hw/intro.txt. # Other topics in this documentation +* Frequently asked questions (faq.txt) * Dictionary of core Forth words (dict.txt) * Editing text (ed.txt) * Assembling binaries (asm.txt) diff --git a/doc/selfhost.txt b/doc/selfhost.txt new file mode 100644 index 0000000..4106fb4 --- /dev/null +++ b/doc/selfhost.txt @@ -0,0 +1,79 @@ +# 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. + +Build Collapse OS' from within Collapse OS is very similar to +how we do it from the makefiles in /arch. If you take +the time to look one, you'll see something that look like "cat +xcomp.fs | $(STAGE)". That's the thing. Open "xcomp.fs" in a +text editor and take a look at it. Some xcomp units are simple +proxy to a block, which you'll find in the blk/ subfolder for +this recipe. + +To assemble Collapse OS from within it, all you need to do is +execute the content of this unit, minus the 2 lines of "spitting +to port 2" at the end of the unit, which is a special signal for +the stage binary. + +The rest can be executed on any Collapse OS system with enough +memory. It will yield a binary in memory. To know the start/end +offset of the binary, you'll type the same two commands at the +end of 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". You now have a new Collapse +OS deployment. + +Is that it? Yes. But for your own enlightenment, let's look at +the xcomp unit in more details. Full details are at +doc/bootstrap.txt. + +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 proper 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 self host from a machine with a SD card and 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". + diff --git a/recipes/README.md b/recipes/README.md deleted file mode 100644 index 6c30fbe..0000000 --- a/recipes/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Recipes - -Because Collapse OS is a meta OS that you assemble yourself on an improvised -machine of your own design, there can't really be a build script. Not a -reliable one anyways. - -Because the design of post-collapse machines is hard to predict, it's hard to -write a definitive guide to it. - -The approach we're taking here is a list of recipes: Walkthrough guides for -machines that were built and tried pre-collapse. With a wide enough variety of -recipes, I hope that it will be enough to cover most post-collapse cases. - -That's what this folder contains: a list of recipes that uses parts supplied -by Collapse OS to run on some machines people tried. - -In other words, parts often implement logic for hardware that isn't available -off the shelf, but they implement a logic that you are likely to need post -collapse. These parts, however *have* been tried on real material and they all -have a recipe describing how to build the hardware that parts have been written -for. - -## Structure - -Each top folder represents an architecture. In that top folder, there's a -`README.md` file presenting the architecture as well as instructions to -minimally get Collapse OS running on it. Then, in the same folder, there are -auxiliary recipes for nice stuff built around that architecture. - -Installation procedures are centered around using a modern system to install -Collapse OS. These are the most useful instructions to have under both -pre-collapse and post-collapse conditions because even after the collapse, -we'll interact mostly with modern technology for many years. - -There are, however, recipes to write to different storage media, thus making -Collapse OS fully reproducible. For example, you can use `rc2014/eeprom` to -write arbitrary data to a `AT28` EEPROM. - -The `rc2014` architecture is considered the "canonical" one. That means that -if a recipe is considered architecture independent, it's the `rc2014` recipe -folder that's going to contain it. - -For example, `rc2014/eeprom` can be considered architecture independent because -it's much more about the `AT28` than about a specific z80 architecture. You can -adapt it to any supported architecture with minimal hassle. Therefore, it's -not going to be copied in every architecture recipe folder. - -`rc2014` installation recipe also contains more "newbie-friendly" instructions -than other installation recipes, which take this knowledge for granted. It is -therefore recommended to have a look at it even if you're not planning on using -a RC2014. diff --git a/recipes/arduinouno/Makefile b/recipes/arduinouno/Makefile deleted file mode 100644 index 1cad12a..0000000 --- a/recipes/arduinouno/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -PROGNAME = at28wr -USBDEV = /dev/cuaU0 -BAUDS = 115200 -AVRDUDEARGS = -F -V -c arduino -P $(USBDEV) -b $(BAUDS) -AVRDUDEMCU = atmega328p -TARGET = $(PROGNAME).hex -AVRA = avra - -# Rules - -.PHONY: send all clean - -all: $(TARGET) - @echo Done! - -send: $(TARGET) - avrdude $(AVRDUDEARGS) -p $(AVRDUDEMCU) -U flash:w:$(TARGET) - -$(TARGET): $(PROGNAME).asm - $(AVRA) -o $@ $(PROGNAME).asm - -clean: - rm -f $(TARGET) *.S.eep.hex *.S.obj diff --git a/recipes/arduinouno/README.md b/recipes/arduinouno/README.md deleted file mode 100644 index c3c0673..0000000 --- a/recipes/arduinouno/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Arduino Uno - -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. - -* [Writing to a AT28 EEPROM from a modern environment](at28.md) diff --git a/recipes/arduinouno/at28.md b/recipes/arduinouno/at28.md deleted file mode 100644 index 7b1b3e8..0000000 --- a/recipes/arduinouno/at28.md +++ /dev/null @@ -1,45 +0,0 @@ -# Writing to a AT28 EEPROM from a modern environment - -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][avra] (will soon rewrite to Collapse OS' ASM) -* avrdude to send program to Arduino - -## Schema - -![Schema](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 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`. - -[avra]: http://avra.sourceforge.net/ diff --git a/recipes/pcat/README.md b/recipes/pcat/README.md deleted file mode 100644 index 6cd63d3..0000000 --- a/recipes/pcat/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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 this folder with 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 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...). diff --git a/recipes/rc2014/README.md b/recipes/rc2014/README.md deleted file mode 100644 index cc19e5d..0000000 --- a/recipes/rc2014/README.md +++ /dev/null @@ -1,95 +0,0 @@ -# RC2014 - -The [RC2014][rc2014] is a nice and minimal z80 system that has the advantage -of being available in an assembly kit. Assembling it yourself involves quite a -bit of soldering due to the bus system. However, one very nice upside of that -bus system is that each component is isolated and simple. - -The machine used in this recipe is the "Classic" RC2014 with an 8k ROM module -, 32k of RAM, a 7.3728Mhz clock and a serial I/O. - -The ROM module being supplied in the assembly kit is an EPROM, not EEPROM, so -you can't install Collapse OS on it. You'll have to supply your own. - -There are many options around to boot arbitrary sources. What was used in this -recipe was a AT28C64B EEPROM module. I chose it because it's compatible with -the 8k ROM module which is very convenient. If you do the same, however, don't -forget to set the A14 jumper to high because what is the A14 pin on the AT27 -ROM module is the WE pin on the AT28! Setting the jumper high will keep is -disabled. - -## Related recipes - -This recipe is for installing a minimal Collapse OS system on the RC2014. There -are other recipes related to the RC2014: - -* [Writing to a AT28 from Collapse OS](eeprom.md) -* [Accessing a MicroSD card](sdcard.md) -* [Self-hosting](selfhost.md) -* [Interfacing a PS/2 keyboard](ps2.md) -* [Using Zilog's SIO as a console](sio.md) -* [Making an ATmega328P blink](avr.md) - -## Recipe - -The goal is to have the shell running and accessible through the Serial I/O. - -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 -a "understand everything" mindset, I [built my own][romwrite]. This is the -device I use in this recipe. - -### Gathering parts - -* A "classic" RC2014 with Serial I/O -* [Forth's stage binary][stage] -* [romwrite][romwrite] and its specified dependencies -* [GNU screen][screen] -* A FTDI-to-TTL cable to connect to the Serial I/O module - -### Build the binary - -Building the binary is as simple as running `make`. This will yield `os.bin` -which can then be written to EEPROM. - -This build is controlled by the `xcomp.fs` unit, which loads `blk/618`. That's -what you need to modify if you want to customize your build (if you do, you'll -need to rebuild `/emul/stage` because the blkfs is embedded in it). - -### Emulate - -The Collapse OS project includes a RC2014 emulator suitable for this image. -You can invoke it with `make emul`. See `emul/hw/rc2014/README.md` for details. - -### Write to the ROM - -Plug your romwrite atmega328 to your computer and identify the tty bound to it. -In my case (arduino uno), it's `/dev/ttyACM0`. Then: - - screen /dev/ttyACM0 9600 - CTRL-A + ":quit" - cat rom.bin | pv -L 10 > /dev/ttyACM0 - -See romwrite's README for details about these commands. - -Note that this method is slow and clunky, but before long, you won't be using -it anymore. Writing to an EEPROM is much easier and faster from a RC2014 -running Collapse OS, so once you have that first Collapse OS ROM, you'll be -much better equipped for further toying around (unless, of course, you already -had tools to write to EEPROM. In which case, you'll be ignoring this section -altogether). - -### Running - -Put the AT28 in the ROM module, don't forget to set the A14 jumper high, then -power the thing up. Connect the FTDI-to-TTL cable to the Serial I/O module and -identify the tty bound to it (in my case, `/dev/ttyUSB0`). Then: - - screen /dev/ttyUSB0 115200 - -Press the reset button on the RC2014 and the "ok" prompt should appear. - -[rc2014]: https://rc2014.co.uk -[romwrite]: https://github.com/hsoft/romwrite -[stage]: ../../emul -[screen]: https://www.gnu.org/software/screen/ diff --git a/recipes/rc2014/blk/600 b/recipes/rc2014/blk/600 deleted file mode 100644 index 3cea5ef..0000000 --- a/recipes/rc2014/blk/600 +++ /dev/null @@ -1,8 +0,0 @@ -RC2014 Recipe - -Support code for the RC2014 recipe. Contains drivers for the -ACIA, SD card and AT28 EEPROM. - -601 ACIA 606 Zilog SIO driver -612 AT28 EEPROM 615 SPI relay -619 Xcomp unit diff --git a/recipes/rc2014/blk/612 b/recipes/rc2014/blk/612 deleted file mode 100644 index 69195a9..0000000 --- a/recipes/rc2014/blk/612 +++ /dev/null @@ -1,6 +0,0 @@ -AT28 Driver - -Write to an AT28 EEPROM while making sure that proper timing -is followed and verify data integrity. - -Load with "593 LOAD" diff --git a/recipes/rc2014/eeprom.md b/recipes/rc2014/eeprom.md deleted file mode 100644 index f3bb862..0000000 --- a/recipes/rc2014/eeprom.md +++ /dev/null @@ -1,52 +0,0 @@ -# Writing to a AT28 from Collapse OS - -## Goal - -Write in an AT28 EEPROM from within Collapse OS so that you can have it update -itself. - -## 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. - -### Building the binary - -The binary from the base recipe has almost all it needs to write to EEPROM. The -only thing it needs is the AT28 driver from B592. You could add it to the -`xcomp` unit and rebuild, but the driver is so tiny, you're probably better off -loading it at runtime. - -If your system has mass storage, it's as easy as a LOAD. If it doesn't, you -can use `/tools/exec` to send `blk/593` to the RC2014. - -## Writing contents to the AT28 - -The driver provides `AT28!` which can be plugged in adev's `A!*`. You can do so -with `' AT28! A!* !`. - -Then, upload your binary to EEPROM with: - - ./upload 2000 diff --git a/recipes/rc2014/ps2-595.png b/recipes/rc2014/ps2-595.png deleted file mode 100644 index 83e7639..0000000 Binary files a/recipes/rc2014/ps2-595.png and /dev/null differ diff --git a/recipes/rc2014/ps2-conn.png b/recipes/rc2014/ps2-conn.png deleted file mode 100644 index a9236b5..0000000 Binary files a/recipes/rc2014/ps2-conn.png and /dev/null differ diff --git a/recipes/rc2014/ps2-t45.png b/recipes/rc2014/ps2-t45.png deleted file mode 100644 index 48e7fd0..0000000 Binary files a/recipes/rc2014/ps2-t45.png and /dev/null differ diff --git a/recipes/rc2014/ps2-z80.png b/recipes/rc2014/ps2-z80.png deleted file mode 100644 index ab9c45d..0000000 Binary files a/recipes/rc2014/ps2-z80.png and /dev/null differ diff --git a/recipes/rc2014/ps2.md b/recipes/rc2014/ps2.md deleted file mode 100644 index 7610ee7..0000000 --- a/recipes/rc2014/ps2.md +++ /dev/null @@ -1,83 +0,0 @@ -# Interfacing a PS/2 keyboard - -Serial connection through ACIA is nice, but you are probably plugging a modern -computer on the other side of that ACIA, right? Let's go a step further away -from those machines and drive a PS/2 keyboard directly! - -## Goal - -Have a PS/2 keyboard drive the stdio input of the Collapse OS shell instead of -the ACIA. - -## Gathering parts - -* A RC2014 Classic that could install the base recipe -* A PS/2 keyboard. A USB keyboard + PS/2 adapter should work, but I haven't - tried it yet. -* A PS/2 female connector. Not so readily available, at least not on digikey. I - de-soldered mine from an old motherboard I had laying around. -* ATtiny85/45/25 (main MCU for the device) -* 74xx595 (shift register) -* 40106 inverter gates -* Diodes for `A*`, `IORQ`, `RO`. -* Proto board, RC2014 header pins, wires, IC sockets, etc. -* [AVRA][avra] - -## Building the PS/2 interface - -Let's start with the PS/2 connector, which has two pins: - -![PS/2 connector](ps2-conn.png) - -Both are connected to the ATtiny45, `CLK` being on `PB2` to have `INT0` on it. - -The `DATA` line is multi-use. That is, `PB1` is connected both to the PS/2 data -line and to the 595's `SER`. This saves us a precious pin. - -![ATtiny45](ps2-t45.png) - -The ATtiny 45 hooks everything together. `CE` comes from the z80 bus, see below. - -![74xx595](ps2-595.png) - -This allows us to supply the z80 bus with data within its 375ns limits. `SRCLR` -is hooked to the `CE` line so that whenever a byte is read, the 595 is zeroed -out as fast as possible so that the z80 doesn't read "false doubles". - -The 595, to have its `SRCLR` becoming effective, needs a `RCLK` trigger, which -doesn't happen immediately. It's the ATtiny45, in its `PCINT` interrupt, that -takes care of doing that trigger (as fast as possible). - -![z80](ps2-z80.png) - -Our device is read only, on one port. That makes the "Chip Enable" (`CE`) -selection rather simple. In my design, I chose the IO port 8, so I inverted -`A3`. I chose a 40106 inverter to do that, do as you please for your own design. - -I wanted to hook `CE` to a flip flop so that the MCU could relax a bit more -w.r.t. reacting to its `PB4` pin changes, but I didn't have NAND gates that are -fast enough in stock, so I went with this design. But otherwise, I would -probably have gone the flip-flop way. Seems more solid. - -## Using the PS/2 interface - -To use this interface, you have to build a new Collapse OS binary. We'll use -the xcomp unit from the base recipe and modify it. - -First, we need a `(ps2kc)` routine. In this case, it's easy, it's -`: (ps2kc) 8 PC@ ;`. Add this after ACIA loading. Then, we can load PS/2 -subsystem. You add `411 414 LOADR`. Then, at initialization, you add `PS2$` -after `ACIA$`. You also need to define `PS2_MEM` at the top. You can probably -use `SYSVARS + 0x7a`. - -Rebuild, reflash, should work. For debugging purposes, you might not want to -go straight to plugging PS/2 `(key)` into the system. What I did myself was -to load the PS/2 subsystem *before* ACIA (which overrides with its own `(key)`) -and added a dummy word in between to access PS/2's key. - -Also (and this is a TODO: investigate), I had a problem where the break key I -got from `(ps2kc)` was 0x70 instead of 0xf0 which had the effect of duplicating -all my keystrokes. I added a 0x70 -> 0xf0 replacement in my version of -`(ps2kc)`. Does the trick (at the cost of a non-functional numpad 0). - -[avra]: https://github.com/hsoft/avra diff --git a/recipes/rc2014/sdcard.md b/recipes/rc2014/sdcard.md deleted file mode 100644 index adb02b9..0000000 --- a/recipes/rc2014/sdcard.md +++ /dev/null @@ -1,134 +0,0 @@ -# Accessing a MicroSD card - -SD cards are great because they are accessible directly. No supporting IC is -necessary. The easiest way to access them is through the SPI protocol. - -Due to the way IO works in z80, implementing SPI through it as a bit awkward: -You can't really keep pins high and low on an IO line. You need some kind of -intermediary between z80 IOs and SPI. - -There are many ways to achieve this. This recipe explains how to build your own -hacked off SPI relay for the RC2014. It can then be used with the SD Card -subsystem (B420) to drive a SD card. - -## Gathering parts - -* A RC2014 Classic -* A MicroSD breakout board. I use Adafruit's. -* A proto board + header pins with 39 positions so we can make a RC2014 card. -* Diodes, resistors and stuff -* 40106 (Inverter gates) -* 74xx138 (Decoder) -* 74xx375 (Latches) -* 74xx125 (Buffer) -* 74xx161 (Binary counter) -* 74xx165 (Parallel input shift register) -* 74xx595 (Shift register) - -## Building the SPI relay - -![SPI relay](spirelay.jpg) - -The schematic above works well with the SD Card subsystem (B420). Of course, -it's not the only possible design that works, but I think it's one of the most -straighforwards. - -This relay communicates through the z80 bus with 2 ports, `DATA` and `CTL` and -allows up to 4 devices to be connected to it at once, although only one device -can ever be active at once. This schema only has 2 (and the real prototype I've -built from it), but the '375 has room for 4. In this schema, `DATA` is port 4, -`CTL` is port `5`. - -We activate a device by sending a bitmask to `CTL`, this will end up in the -'375 latches and activate the `SS` pin of one of the device, or deactivate them -all if `0` is sent. - -You then initiate a SPI exchange by sending a byte to send to the `DATA` port. -This byte will end up in the '165 and the '161 counter will be activated, -triggering a clock for the SPI exchange. At each clock, a bit is sent to `MOSI` -from the '161 and received from `MISO` into the '595, which is the byte sent to -the z80 bus when we read from `DATA`. - -When the '161 is wired to the system clock, as it is in the schema, two `NOP`s -are a sufficient delay between your `DATA` write and subsequent `DATA` read. - -However, if you build yourself some kind of clock override and run the '161 at -something slower than the system clock, those 2 `NOP`s will be too quick. That's -where that '125 comes into play. When reading `CTL`, it spits `RUNNING` into -`D0`. This allows you to know when the result of the SPI exchange is ready to be -fetched. Make sure you `AND` away other bits, because they'll be garbage. - -The '138 is to determine our current IORQ mode (`DATA`/`CTL` and `WR/RO`), the -'106 is to provide for those `NOT`s sprinkled around. - -Please note that this design is inspired by [this design][inspiration]. - -Advice 1: Make `SCK` polarity configurable at all 3 endpoints (the 595, the 165 -and SPI connector). Those jumpers will be useful when you need to mess with -polarity in your many tinkering sessions to come. - -Advice 2: Make input `CLK` override-able. SD cards are plenty fast enough for -us to use the system clock, but you might want to interact with devices that -require a slower clock. - -## Building your binary - -The binary built in the base recipe doesn't have SDC drivers. You'll need to -assemble a binary with those drivers. To do so, you'll modify the xcomp unit -of the base recipe. Look at `xcomp.fs`, you'll see that we load a block. That's -our xcomp block (likely, B599). Open it. - -First, we need drivers for the SPI relay. This is done by declaring `SPI_DATA` -and `SPI_CTL`, which are respectively `4` and `5` in our relay design. - -You also need to tell the SDC subsystem which SPI device to activate by defining -the `SDC_DEVID` (1, 2, 4, 8 for device 0, 1, 2 or 3) - -You can then load the driver with `419 LOAD`. This driver provides -`(spix)` and `(spie)` which are then used in the SDC driver. - -The SDC driver is at B420. It gives you a load range. This means that what -you need to insert in `xcomp` will look like: - - 423 436 LOADR ( sdc ) - -You also need to add `BLK$` to the init sequence. - -Build it (run `make pack` in `cvm/` first to ensure an up-to-date blkfs) and -write it to EEPROM. - -## Testing in the emulator - -The RC2014 emulator includes SDC emulation. You can attach a SD card image to -it by invoking it with a second argument: - - ../../../emul/hw/rc2014/classic os.bin ../../../cvm/blkfs - -You will then run with a SD card having the contents from `/blk`. - -## Usage - -First, the SD card needs to be initialized - - SDC$ - -If there is no error message, we're fine. Then, we need to hook `BLK@*` and -`BLK!*` into the SDC driver: - - ' SDC@ BLK@* ! - ' SDC! BLK!* ! - -And thats it! You have full access to disk block mechanism: - - 105 LOAD - BROWSE - -(at this moment, the driver is a bit slow though...) - -## 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`. - -[inspiration]: https://www.ecstaticlyrics.com/electronics/SPI/fast_z80_interface.html diff --git a/recipes/rc2014/selfhost.md b/recipes/rc2014/selfhost.md deleted file mode 100644 index 780c51a..0000000 --- a/recipes/rc2014/selfhost.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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 -B599, 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 B599. 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`. diff --git a/recipes/rc2014/sio.md b/recipes/rc2014/sio.md deleted file mode 100644 index 41d7704..0000000 --- a/recipes/rc2014/sio.md +++ /dev/null @@ -1,35 +0,0 @@ -# Using Zilog's SIO as a console - -The RC2014 has an optional module called the Dual Serial Module SIO/2 which is -built around Zilog's SIO chip. This module is nice because when paired with the -Dual Clock Module and when using port B, it's possible to run a UART with a baud -rate lower than 115200. - -Collapse OS has a driver for it (although for now, only port A is supported by -it). Let's use it. - -## Gathering parts - -* A "classic" RC2014 -* A Dual Serial Module SIO/2 - -## Build the binary - -You'll have to edit the base recipe's xcomp unit like we do in the sdcard -recipe. - -* Locate RC2014 recipe in blkfs -* Locate SIO driver -* The driver main page gives you references for declarations and for code. -* In the base xcomp unit, replace ACIA declataions with SIO's -* Replace ACIA code with SIO's -* At the bottom, replace "ACIA$" with "SIO$". - -You can build with `make`. - -## Setup - -After you've placed the binary on your RC2014's EEPROM, simply replace your -regular Serial Module with the Dual Serial Module and plug yourself into port A. - -You should have a functional console. diff --git a/recipes/sms/README.md b/recipes/sms/README.md deleted file mode 100644 index a2ad8cf..0000000 --- a/recipes/sms/README.md +++ /dev/null @@ -1,89 +0,0 @@ -# Sega Master System - -The Sega Master System was a popular gaming console running on z80. It has a -simple, solid design and, most interestingly of all, its even more popular -successor, the Megadrive (Genesis) had a z80 system for compatibility! - -This makes this platform *very* scavenge-friendly and worth working on. - -[SMS Power][smspower] is an awesome technical resource to develop for this -platform and this is where most of my information comes from. - -This platform is tight on RAM. It has 8k of it. However, if you have extra RAM, -you can put it on your cartridge. - -## Related recipes - -This recipe is for installing a minimal Collapse OS system on the SMS. There -are other recipes related to the SMS: - -* [Interfacing a PS/2 keyboard](kbd.md) - -## Gathering parts - -* A Sega Master System or a MegaDrive (Genesis). -* A Megadrive D-pad controller. -* A way to get an arbitrary ROM to run on the SMS. Either through a writable - ROM cartridge or an [Everdrive][everdrive]. - -## Hacking up a ROM cart - -SMS Power has instructions to transform a ROM cartrige into a battery-backed -SRAM one, which allows you to write to it through another device you'll have -to build. This is all well and good, but if you happen to have an AT28 EEPROM, -things are much simpler! - -Because AT28 EEPROM are SRAM compatible, they are an almost-drop-in replacement -to the ROM you'll pop off your cartridge. AT28 are a bit expensive, but they're -so handy! For SMS-related stuff, I recommend the 32K version instead of the 8K -one because fitting Collapse OS with fonts in 8K is really tight. - - -1. De-solder the ROM -2. Take a 28 pins IC socket -3. Cut off its WE pin (the one just under VCC), leaving a tiny bit of metal. -4. Hard-wire it to VCC so that WE is never enabled. -5. Solder your socket where the ROM was. -6. Insert Collapse OS-filled EEPROM in socket. - -As simple as this! (Note that this has only been tested on a SMS so far. I -haven't explored whether this can run on a megadrive). - -## Build the ROM - -Running `make os.sms` will produce a `os.sms` ROM that can be put as is on a SD -card to the everdrive or flashed as is on a writable ROM cart. Then, just run -the thing! - -To run Collapse OS in a SMS emulator, run `make emul`. - -## Usage - -On boot, you will get a regular Collapse OS BASIC shell. See the rest of the -documentation for shell usage instructions. - -The particularity here is that, unlike with the RC2014, we don't access Collapse -OS through a serial link. Our input is a D-Pad and our output is a TV. The -screen is 32x28 characters. A bit tight, but usable. - -D-Pad is used as follow: - -* There's always an active cursor. On boot, it shows "a". -* Up/Down increase/decrease the value of the cursor. -* Left/Right does the same, by increments of 5. -* A button is backspace. -* B button skips cursor to next "class" (number, lowcase, upcase, symbols). -* C button "enters" cursor character and advance the cursor by one. -* Start button is like pressing Return. - -Of course, that's not a fun way to enter text, but using the D-Pad is the -easiest way to get started which doesn't require soldering. Your next step after -that would be to [build a PS/2 keyboard adapter!](kbd/README.md) - -## Slow initialization in emulation - -When running under the emulator, video initialization is slow, it takes several -seconds. It's the emulator's fault. On real hardware, it's not as slow. - -[smspower]: http://www.smspower.org -[everdrive]: https://krikzz.com diff --git a/recipes/sms/kbd.md b/recipes/sms/kbd.md deleted file mode 100644 index 89e9894..0000000 --- a/recipes/sms/kbd.md +++ /dev/null @@ -1,115 +0,0 @@ -# PS/2 keyboard on the SMS - -Using the shell with a D-pad on the SMS is doable, but not fun at all! We're -going to build an adapter for a PS/2 keyboard to plug as a SMS controller. - -The PS/2 logic will be the same as the [RC2014's PS/2 adapter][rc2014-ps2] but -instead of interfacing directly with the bus, we interface with the SMS' -controller subsystem (that is, what we poke on ports `0x3f` and `0xdc`). - -How will we achieve that? A naive approach would be "let's limit ourselves to -7bit ASCII and put `TH`, `TR` and `TL` as inputs". That could work, except that -the SMS will have no way reliable way (except timers) of knowing whether polling -two identical values is the result of a repeat character or because there is no -new value yet. - -On the AVR side, there's not way to know whether the value has been read, so we -can't to like on the RC2014 and reset the value to zero when a `RO` request is -made. - -We need communication between the SMS and the PS/2 adapter to be bi-directional. -That bring the number of usable pins down to 6, a bit low for a proper character -range. So we'll fetch each character in two 4bit nibbles. `TH` is used to select -which nibble we want. - -`TH` going up also tells the AVR MCU that we're done reading the character and -that the next one can come up. - -As always, the main problem is that the AVR MCU is too slow to keep up with the -rapid z80 polling pace. In the RC2014 adapter, I hooked `CE` directly on the -AVR, but that was a bit tight because the MCU is barely fast enough to handle -this signal properly. I did that because I had no proper IC on hand to build a -SR latch. - -In this recipe, I do have a SR latch on hand, so I'll use it. `TH` triggering -will also trigger that latch, indicating to the MCU that it can load the next -character in the '164. When it's done, we signal the SMS that the next char is -ready by resetting the latch. That means that we have to hook the latch's output -to `TR`. - -Nibble selection on `TH` doesn't involve the AVR at all. All 8 bits are -pre-loaded on the '164. We use a 4-channel multiplexer to make `TH` select -either the low or high bits. - -## Gathering parts - -* A SMS that can run Collapse OS -* A PS/2 keyboard. A USB keyboard + PS/2 adapter should work, but I haven't - tried it yet. -* A PS/2 female connector. Not so readily available, at least not on digikey. I - de-soldered mine from an old motherboard I had laying around. -* A SMS controller you can cannibalize for the DB-9 connection. A stock DB-9 - connector isn't deep enough. -* ATtiny85/45/25 (main MCU for the device) -* 74xx164 (shift register) -* 74xx157 (multiplexer) -* A NOR SR-latch. I used a 4043. -* Proto board, wires, IC sockets, etc. - -## Historical note - -As I was building this prototype, I was wondering how I would debug it. I could -obviously not hope for it to work as a keyboard adapter on the first time, right -on port A, driving the shell. I braced myself mentally for a logic analyzer -session and some kind of arduino-based probe to test bit banging results. - -And then I thought "why not use the genesis?". Sure, driving the shell with the -D-pad isn't fun at all, but it's possible. So I hacked myself a temporary debug -kernel with a "a" command doing a probe on port B. It worked really well! - -It was a bit less precise than logic analyzers and a bit of poking-around and -crossing-fingers was involved, but overall, I think it was much less effort -than creating a full test setup. - -There's a certain satisfaction to debug a device entirely on your target -machine... - -## Building the PS/2 interface - -![Schematic](ps2-to-sms.png) - -The PS/2-to-AVR part is identical to the rc2014/ps2 recipe. Refer to this -recipe. - -We control the '164 from the AVR in a similar way to what we did in rc2014/ps2, -that is, sharing the DATA line with PS/2 (PB1). We clock the '164 with PB3. -Because the '164, unlike the '595, is unbuffered, no need for special RCLK -provisions. - -Most of the wiring is between the '164 and the '157. Place them close. The 4 -outputs on the '157 are hooked to the first 4 lines on the DB-9 (Up, Down, Left, -Right). - -In my prototype, I placed a 1uf decoupling cap next to the AVR. I used a 10K -resistor as a pull-down for the TH line (it's not always driven). - -If you use a 4043, don't forget to wire EN. On the '157, don't forget to wire -~G. - -The code expects a SR-latch that works like a 4043, that is, S and R are -triggered high, S makes Q high, R makes Q low. R is hooked to PB4. S is hooked -to TH (and also the A/B on the '157). Q is hooked to PB0 and TL. - -## Building the binary - -We start with the base recipe and add a few things: - -1. at the top: `SYSVARS 0x72 + CONSTANT PS2_MEM` -2. After VDP load: `621 LOAD : (ps2kc) (ps2kcB) ;` (that binds us to port B) -3. Right after: `411 414 LOADR` (that gives us `(key)`) -4. After `VDP$`: `PS2$`. - -Rebuild, send to SMS, then run with your keyboard interface plugged to PortB. -It should mostly work. There are still a few glitches to iron out... - -[rc2014-ps2]: ../rc2014/ps2 diff --git a/recipes/ti84/README.md b/recipes/ti84/README.md deleted file mode 100644 index 868ab79..0000000 --- a/recipes/ti84/README.md +++ /dev/null @@ -1,135 +0,0 @@ -# TI-84+ - -The TI-84+ is a machine with many advantages, one being that it's very popular. -It also has a lot of flash memory and RAM. - -Its builtin keyboard and screen, however, are hard to use, especially the -screen. With a tiny font, the best we can get is a 24x10 console. - -There is, however, a built-in USB controller that might prove very handy. - -I haven't opened one up yet, but apparently, they have limited scavenging value -because its z80 CPU is packaged in a TI-specific chip. Due to its sturdy design, -and its ample RAM and flash, we could imagine it becoming a valuable piece of -equipment if found intact. - -The best pre-collapse ressource about it is -[WikiTI](http://wikiti.brandonw.net/index.php). - -As it is now, with its tiny screen and cumbersome keyboard, Collapse OS is -not really usable on the TI-84+. One could imagine a scenario where one has a -terminal and uses the TI-84+ through the link for its large amount of flash and -RAM. But using it standalone? Nah, not even post-collapse. - -Therefore, this recipe is more of a "look, I run!" demo. - -## Recipe - -This recipe gets the Collapse OS interpreter to run on the TI-84+, using its LCD -screen as output and its builtin keyboard as input. - -## Gathering parts - -* [zasm][zasm] -* A TI-84+ (TI-83+ compatibility is being worked on. See issue #41) -* A USB cable -* [tilp][tilp] -* [mktiupgrade][mktiupgrade] - -## Build the ROM - -Running `make` will result in `os.rom` being created. - -## Emulate - -Collapse OS has a builtin TI-84+ emulator using XCB for display in `emul/hw/ti`. -You can invoke it with `make emul`. - -You will start with a blank screen, it's normal, you haven't pressed the "ON" -key yet. This key is mapped to tilde (~) in the emulator. Once you press it, the -Collapse OS prompt will appear. See `emul/hw/ti/README.md` for details. - -## Upload to the calculator - -### Background notes - -Getting software to run on it is a bit tricky because it needs to be signed -with TI-issued private keys. Those keys have long been found and are included -in `keys/`. With the help of the -[mktiupgrade](https://github.com/KnightOS/mktiupgrade), an upgrade file can be -prepared and then sent through the USB port with the help of -[tilp](http://lpg.ticalc.org/prj_tilp/). - -That, however, requires a modern computing environment. As of now, there is no -way of installing Collapse OS on a TI-8X+ calculator from another Collapse OS -system. - -Because it is not on the roadmap to implement complex cryptography in Collapse -OS, the plan is to build a series of pre-signed bootloader images. The -bootloader would then receive data through either the Link jack or the USB port -and write that to flash (I haven't verified that yet, but I hope that data -written to flash this way isn't verified cryptographically by the calculator). - -As modern computing fades away, those pre-signed binaries would become opaque, -but at least, would allow bootstrapping from post-modern computers. - -### Instructions - -**WARNING: the instructions below will wipe all the contents of your calculator, -including TI-OS.** - -To send your ROM to the calculator, you'll need two more tools: -[mktiupgrade][mktiupgrade] and [tilp][tilp]. - -Once you have them, you need to place your calculator in "bootloader mode", -that is, in a mode where it's ready to receive a new binary from its USB cable. -To do that you need to: - -1. Shut down the calculator by removing one of the battery. -2. Hold the DEL key -3. But the battery back. -4. A "Waiting... Please install operating system now" message will appear. - -Once this is done, you can plug the USB cable in your computer and run -`make send`. This will create an "upgrade file" with `mktiupgrade` and then -push that upgrade file with `tilp`. `tilp` will prompt you at some point. -Press "1" to continue. - -When this is done, you can press the ON button to see Collapse OS' prompt! - -## Validation errors - -Sometimes, when uploading an upgrade file to your calculator, you'll get a -validation error. You can always try again, but in my own experience, some -specific binaries will simply always be refused by the calculator. Adding -random `nop` or reordering lines (when it makes sense, of course) should fix -the problem. - -I'm not sure whether it's a bug with the calculator or with `mktiupgrade`. - -## Usage - -The shell works like a normal BASIC shell, but with very tight screen space. - -When pressing a "normal" key, it spits the symbol associated to it depending -on the current mode. In normal mode, it spits the digit/symbol. In Alpha mode, -it spits the letter. In Alpha+2nd, it spits the uppercase letter. - -Special keys are Alpha and 2nd. Pressing them toggles the associated mode. -Alpha and 2nd mode don't persist for more than one character. After the -character is spit, mode reset to normal. - -Pressing 2nd then Alpha will toggle the A-Lock mode, which is a persistent mode. -The A-Lock mode makes Alpha enabled all the time. While A-Lock mode is enabled, -you have to enable Alpha to spit a digit/symbol. - -Simultaneous keypresses have undefined behavior. One of the keys will be -registered as pressed. Mode key don't work by simultaneously pressing them with -a "normal" key. The presses must be sequential. - -Keys that aren't a digit, a letter, a symbol that is part of 7-bit ASCII or one -of the two mode key have no effect. - -[zasm]: ../../tools/emul -[mktiupgrade]: https://github.com/KnightOS/mktiupgrade -[tilp]: http://lpg.ticalc.org/prj_tilp/ diff --git a/recipes/trs80/.gitignore b/recipes/trs80/.gitignore deleted file mode 100644 index 9d72a14..0000000 --- a/recipes/trs80/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -/cfsin/user.h -/cfsin/zasm -/cfsin/ed diff --git a/recipes/trs80/README.md b/recipes/trs80/README.md deleted file mode 100644 index c8e049c..0000000 --- a/recipes/trs80/README.md +++ /dev/null @@ -1,278 +0,0 @@ -# TRS-80 Model 4p - -The TRS-80 (models 1, 3 and 4) are among the most popular z80 machines. They're -very nicely designed and I got my hands on a 4p with two floppy disk drives and -a RS-232 port. In this recipe, we're going to get Collapse OS running on it. - -![Collapse OS on a TRS-80 Model 4P](collapseos-on-trs80.jpg) - -## Not entirely standalone - -Collapse OS uses the TRS-80 drivers rather than its own. On most TRS-80 models, -those drivers are on ROM, but in the case of the 4P model, those drivers are on -the TRSDOS disk (well, from what I understand, not all of it, but still, a big -part of it). - -It would be preferable to develop drivers from scratch, but it represents a -significant effort for a modest payout (because it's only actually useful when -you want to use a 4P model that has no TRSDOS disk). - -Maybe those drivers will be developed later, but it's not a priority for now. - -## Floppy or RS-232? - -There are many ways to get Collapse OS to run on it. One would involve writing -it to a floppy. I bought myself old floppy drives for that purpose, but I happen -to not have any functional computer with a floppy port on it. I still have the -motherboard of my old pentium, but I don't seem to have a video card for it any -more. - -Because my 4p has a RS-232 port and because I have equipment to do serial -communication from modern machines (I didn't have a DB-9 to DB-25 adapter -though, I had to buy one), I chose that route. - -## Gathering parts - -* A TRS-80 model 4p with a RS-232 port -* A TRSDOS 6.x disk -* A means to do serial communication. In my case, that meant: - * A USB-to-serial device - * A null modem cable - * A DB-9 gender changer - * A DB-9 to DB-25 adapter - -## Overview - -We need to send sizeable binary programs through the RS-232 port and then run -it. The big challenge here is ensuring data integrity. Sure, serial -communication has parity check, but it has no helpful way of dealing with -parity errors. When parity check is enabled and that a parity error occurs, the -byte is simply dropped on the receiving side. Also, a double bit error could be -missed by those checks. - -What we'll do here is to ping back every received byte back and have the sender -do the comparison and report mismatched data. - -Another problem is ASCII control characters. When those are sent across serial -communication channels, all hell breaks lose. When sending binary data, those -characters have to be avoided. We use `tools/ttysafe` for that. - -Does TRSDOS have a way to receive this binary inside these constraints? Not to -my knowledge. As far as I know, the COMM program doesn't allow this. - -What are we going to do? We're going to punch in a binary program to handle that -kind of reception! You're gonna feel real badass about it too... - -## Keyboard tips - -* `_` is `CLEAR+ENTER`. - -## Building the binary - -You can build the binary to send to the TRS-80 with `make`, which will yield -`os.bin`. You'll need it later. - -## Testing serial communication - -The first step here is ensuring that you have bi-directional serial -communication. To do this, first prepare your TRS-80: - - set *cl to com - setcomm (word=8,parity=no) - -The first line loads the communication driver from the `COM/DRV` file on the -TRSDOS disk and binds it to `*cl`, the name generally used for serial -communication devices. The second line sets communication parameters in line -with what is generally the default on modern machine. Note that I left the -default of 300 bauds as-is. - -Then, you can run `COMM *cl` to start a serial communication console. - -Then, on the modern side, use your favorite serial communication program and set -the tty to 300 baud with option "raw". Make sure you have `-parenb`. - -If your line is good, then what you type on either side should echo on the -other side. If it does not, something's wrong. Debug. - -## Punching in the goodie - -As stated in the overview, we need a program on the TRS-80 that: - -1. Listens to `*cl` -2. Echoes each character back to `*cl` -3. Adjusts `ttysafe` escapes -4. Stores received bytes in memory - -You're in luck: that program has already been written. It's in B502 and B503. -You can compile it with: - - 5 LOAD ( z80 assembler ) - 0x0238 CONSTANT COM_DRV_ADDR - 0x3000 CONSTANT DEST_ADDR - 502 LOAD - 503 LOAD - -Then, you can use `DUMP` to visualize the data you'll need to punch in: - - H@ ORG @ - ORG @ DUMP - -It can run from any offset (all jumps in it are relative), but writes to -`DEST_ADDR`. Make sure you don't place it in a way to be overwritten by its -received data. - -Wondering what is that `COM_DRV_ADDR` constant? That's the DCB handle of your -`*cl` device. You will need to get that address before you continue. Go read -the following section and come back here. - -How will you punch that in? The `debug` program! This very useful piece of -software is supplied in TRSDOS. To invoke it, first run `debug (on)` and then -press the `BREAK` key. You'll get the debug interface which allows you to punch -in any data in any memory address. Let's use `0x5000` which is the offset it's -designed for. - -For reference: to go back to the TRSDOS prompt, it's `o`. - -First, display the `0x5000-0x503f` range with the `d5000` command (I -always press Enter by mistake, but it's space you need to press). Then, you can -begin punching in with `h5000`. This will bring up a visual indicator of -the address being edited. Punch in the stuff with a space in between each byte -and end the edit session with `x`. - -## Getting your DCB address - -In the previous step, you need to set `COM_DRV_ADDR` to your "DCB" address for -`*cl`. That address is your driver "handle". To get it, first get the address -where the driver is loaded in memory. You can get this by running `device -(b=y)`. That address you see next to `*cl`? that's it. But that's not our DCB. - -To get your DBC, go explore that memory area. Right after the part where there's -the `*cl` string, there's the DCB address (little endian). On my setup, the -driver was loaded in `0x0ff4` and the DCB address was 8 bytes after that, with -a value of `0x0238`. Don't forget that z80 is little endian. `38` will come -before `02`. - -## Saving that program for later - -If you want to save yourself typing for later sessions, why not save the -program you've painfully typed to disk? TRSDOS enables that easily. Let's say -that you typed your program at `0x5000` and that you want to save it to -`RECV/CMD` on your second floppy drive, you'd do: - - dump recv/cmd:1 (start=x'5000',end=x'5030',tra='5000') - -A memory range dumped this way will be re-loaded at the same offset through -`load recv/cmd:1`. Even better, `TRA` indicates when to jump after load when -using the `RUN` command. Therefore, you can avoid all this work above in later -sessions by simply typing `recv` in the DOS prompt. - -Note that you might want to turn `debug` off for these commands to run. I'm not -sure why, but when the debugger is on, launching the command triggers the -debugger. - -## Sending binary through the RS-232 port - -Once you're finished punching your program in memory, you can run it with -`g5000` (not space). If you've saved it to disk, run `recv` instead. -Because it's an infinite loop, your screen will freeze. You can start sending -your data. - -To that end, there's the `tools/pingpong` program. It takes a device and a -filename to send. Before you send the binary, make it go through -`tools/ttysafe` first (which just takes input from stdin and spits tty-safe -content to stdout): - - ./ttysafe < stage1.bin > stage1.ttysafe - -On OpenBSD, the invocation can look like: - - doas ./pingpong /dev/ttyU0 os.ttysafe - -You will be prompted for a key before the contents is sent. This is because on -OpenBSD, TTY configuration is lost as soon as the TTY is closed, which means -that you can't just run `stty` before running `pingpong`. So, what you'll do is, -before you press your key, run `doas stty -f /dev/ttyU0 300 raw` and then press -any key on the `pingpong` invocation. - -If everything goes well, the program will send your contents, verifying every -byte echoed back, and then send a null char to indicate to the receiving end -that it's finished sending. This will end the infinite loop on the TRS-80 side -and return. That should bring you back to a refreshed debug display and you -should see your sent content in memory, at the specified address (`0x3000` if -you didn't change it). - -If there was no error during `pingpong`, the content should be exact. -Nevertheless, I recommend that you manually validate a few bytes using TRSDOS -debugger before carrying on. - -*debugging tip*: Sometimes, the communication channel can be a bit stubborn and -always fail, as if some leftover data was consistently blocking the channel. It -would cause a data mismatch at the very beginning of the process, all the time. -What I do in these cases is start a `COMM *cl` session on one side and a screen -session on the other, type a few characters, and try `pingpong` again. - -## Saving to disk - -If everything went well, you could run Collapse OS with `g3000`. -But instead of doing that, why not save it to disk? - - dump cos/cmd:1 (start=x'5000',end=x'7000',tra='5000') - -And there we go! A Collapse OS launchable from floppy! - -## Sending blkfs to floppy - -As it is, your system fully supports reading and writing to floppy drive 1. It -also had `*CL<` to read a char from `*cl` and `*CL>` to emit a char to `*cl`. - -That's all you need to have a full Collapse OS with access to disk blocks. - -First, make sure your floppies are formatted. Collapse OS is currently -hardcoded to single side and single density, which means there's a limit of 100 -blocks per disk. - -You'll need to send those blocks through RS-232. Begin by taking over the -prompt: - - ' *CL> ' EMIT **! - ' *CL< ' KEY **! - -See B80 for details about those RAM offsets. Your serial link now has the -prompt. You will also have to make your newlines CRLF. The TRS-80 wants CR -only, but serial communications (and `blkup`) expect CRLF: - - ' CRLF ' NL **! - -Now, you can use `/tools/blkup` to send a disk's contents. First, -extract the first 100 blocks from blkfs: - - dd if=emul/blkfs bs=1024 count=100 > d1 - -Now, insert your formatted disk in drive 1 and push your blocks: - - tools/blkup /dev/ttyUSB0 0 d1 - -It takes a while, but you will end up having your first 100 blocks on floppy! -Go ahead, `LIST` around. Then, repeat for other disks. - -## Floppy organisation - -Making blkfs span multiple disk is a bit problematic with regards to absolute -block references in the code. You'll need to work a bit to design your very -own Collapse OS floppy set. See Usage guide (B3) for details. - -## Coming back to keyboard - -Once you're done, you will want to go back to local control: - - ' CR ' NL **! - ' (emit) ' EMIT **! - ' (key) ' KEY **! - -## Self-hosting - -As it is, your installment of Collapse OS is self-hosting using instructions -very similar to `recipes/rc2014/selhost`. The difference is that instead of -writing the binary you have in memory to EEPROM, you'll quit to TRSDOS with -`BYE` and use TRSDOS' `DUMP` utility to save to disk like you already did -before. - diff --git a/recipes/trs80/collapseos-on-trs80.jpg b/recipes/trs80/collapseos-on-trs80.jpg deleted file mode 100644 index 867068d..0000000 Binary files a/recipes/trs80/collapseos-on-trs80.jpg and /dev/null differ diff --git a/recipes/z80mbc2/README.md b/recipes/z80mbc2/README.md deleted file mode 100644 index 0290ac7..0000000 --- a/recipes/z80mbc2/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Z80-MBC2 - -The [Z80-MBC2][link] combines a Z80 and an ATMEGA32A to provide a CP/m capable -computing environment. It features a SD card bootloader which makes running -Collapse OS on it rather simple. - -## Recipe - -In this recipe, we're going to run Collapse OS on the Z80-MBC2, interfacing -through its serial port. We're going to use the MBC's API to implement BLK on -the SD card. - -### Gathering parts - -* A Z80-MBC2 computer with its SD card module and a properly flashed "IOS" on - the ATMega32A. -* A FTDI-to-TTL cable to connect to the serial port. - -### Building the binary - -Running `make` will yield `os.bin` which is what we want. - -### Running on the Z80-MBC2 - -Mount the SD card on your modern computer and copy `os.bin` as `autoboot.bin`, -overwriting the binary that was previously there. - -We also have to copy the blkfs over. This is done by using IOS' drive system. -Each `DSxNyy.DSK` file on the card is a drive, each drive has 512 track of 32 -sectors of 512 bytes, so one drive is plenty for our needs. Collapse OS -hardcodes drive 0. - -Each drive is part of a set. IOS theoretically supports up to 10 sets, but the -binary shipped by default only accepts 4. You have to overwrite an existing set. -I used set 3. So, copy `blkfs` to file `DS3N00.DSK`. If you want, you can change -the name of the set by changing the contents of `DS3NAM.DAT`. - -Put back the SD card in the Z80-MBC2 and power it up by connecting the FTDI -adapter to it (red: VCC, black: GND, green: TX, white: RX). - -The FTDI adapter will show up as something like `ttyUSB0` (or `ttyU0` on -OpenBSD). Connect to it with `screen` or `cu` or whatever you like. Baud rate of -the Z80-MBC2 appears to be hardcoded to 115200. - -Then, enable IOS program selection by holding RESET and USER at the same time, -wait 2 seconds, releasing RESET, wait 2 seconds, releasing USER. You should then -be given a 1-8 choice. - -You begin by selecting the proper disk set, which is through choice 8, then you -select the Autoboot binary through choice 4. - -You are now in Collapse OS. - -[link]: https://hackaday.io/project/159973-z80-mbc2-a-4-ics-homebrew-z80-computer