BOOT COCO3FPGA WITH NITROS-9 EASE OF USE BETA 6.1.0
Overview
Officially, NitrOS-9 Ease of Use Project supports running on:
- A Color Computer 3 (6809 or 6309 MPU, 512K+ RAM, CoCoSDC, including optional GIME-X)
- A Color Computer 3 emulator (VCC, OVCC, MAME, Xroar with 6809 or 6309 MPU, 512K+ RAM, floppy, hard disk)
- A “Matchbox CoCo” (Altera DE-0 Nano board)
- A “Mister CoCo” (Altera DE-10 FPGA board)
But, I wanted to run NitrOS-9 Ease of Use Project Beta 6.1.0 on my “CoCo3FPGA” (Altera DE-1 FPGA board).
This is how I got up and running.
Before You Get Started
Use these instructions at your own risk.
What works for me may not work for you.
If you don't understand a step 100%, do not try it until you do.
This page uses “/dev/sdg” as the path to my USB device to read/write SD cards.
Your device path will likely be different.
Use your device's path instead of /dev/sdg in the steps that follow.
Tools
I run a Debian GNU/Linux desktop equipped with a few tools that really help CoCo cross development:
Toolshed
LWTools
de1flash
USB SDCard reader/writer
NitrOS-9 Distribution
My CoCo3FPGA came supplied with NitrOS-9 version 3.3.0 which includes CoCo3FPGA support, but is built on NitrOS-9 source which can be up to seven years behind NitrOS-9 Ease of Use Project versions.
My approach is to start with the 2014 pieces of NitrOS-9 and move to use as many EoU equivalents as I can.
Get your NitrOS-9 source here: NitrOS-9
NitrOS-9 Ease of Use Distribution
You will also need the Ease of Use Project Beta 6.1.0 binary distribution from:
NitrOS-9 Ease of Use
For the CoCo3FPGA, you will need the 6809 version of Ease of Use Project.
Write the 68SDC.VHD file to a new SD card at least 128MB in size.
On my computer, the USB SD card reader/writer appears as drive “/dev/sdg” and all I needed to get Ease of Use on the SD card:
dd if=68SDC.VHD of=/dev/sdg
Boot ROM
My CoCo3FPGA came pre-installed with Brett Gordon's sdboot ROM image flashed into the CoCo3FPGA's MPI slot 2 to boot from an RBF filesystem image on an SD card.
This was my first chance to see CoCoboot in action and I reallly like it.
Use the de1flash tool linked above and the sdboot source and instructions to put sdboot into your CoCo3FPGA if it's not already there.
SDboot on CoCo3FPGA plays the same role as PC BIOS or UEFI on your PC.
It is “firmware” that has the job of finding and booting from storage.
SDboot will load a CoCoboot kernel module (called CCBKrn) and a custom OS9Boot module file from the CoCo3FPGA SD card.
CCBKrn
This module is new to me with SDBoot and is not present in the Ease of Use Project virtual hard drive image by default.
You can build it from the SDboot repository above, or copy it from an existing CoCo3FPGA disk image (using Toolshed os9).
Use Toolshed's os9 utility to copy the CCBKrn module from SDboot to the top directory of your Ease of Use SD card:
$ sudo os9 copy CCBKrn /dev/sdg,ccbkrn
If you are not a member of the usb group on Debian Linux, you may need to use sudo to run os9 as root to write the sdcard device.
OS9Boot
The heart of the matter to get Ease of Use Project booting on the CoCo3FPGA is the initial bundle of file managers, device drivers, and device descriptors needed for the OS-9 Kernel and its IOman deputy to communicate to and through the devices like storage, keyboard, screen, and serial port.
An OS9Boot file is a single file that contains dozens of merged OS-9 modules loaded as a single set, much like the initial ram disk file loaded by the Linux Kernel at boot to get started.
My goal was an OS9Boot file that supported CoCo3FPGA devices, DriveWire, and Multi-Vue.
So, I took an OS9Boot from the NitrOS-9 v3.3.0 build for the CoCo3FPGA, an OS9Boot from Ease of Use Project Beta 6.1.0, broke them both down into their individual modules, each in their own directory (FPGA and EOU)
There is an OS-9 tool called ModBuster that can break down a file into its component modules.
For Debian, I used an AWK script to split the OS9Boot file into another part each time the $87CD module start signature bytes were found.
$ cat split-os9boot.awk
awk 'BEGIN {RS="\x87\xCD"; FILENUM=-1} {FILENUM++; if (FILENUM == 0) {next}; FILENAME="MOD-"FILENUM; printf "%s",RS$0 > FILENAME;}' OS9Boot
Adapted from https://stackoverflow.com/questions/33930497/how-to-split-binary-delimited-binary-file
One “gotcha” here is that IOMan modules have an $87CD module signature in the middle of them too, presumably where IOMan is scanning for module starts itself.
This means the OS9Boot will split apart, with IOMan in 2 pieces that need to be put back togther.
Run the Toolshed os9 ident utility on each file to find IOMan which will show an error in the ident because of the missing second half.
The next file will fail to ident with Toolshed os9.
Use cat to merge the two pieces back together.
An example from my system (your filenames will vary):
$ cat 03-IOMan 04-module > 03-IOMan-full $ rm 03-IOMan 04-module
Next, I created a BOOTFILES folder and began the pick and choose process of which modules to source from which set.
The os9 ident command showed the Edition and Revision of modules.
However, some modules between FPGA and EOU showed the same Edition and Revision, but different CRCs.
The shasum Linux command was helpful to verify whether or not modules were byte identical when os9 tool showed such.
First, move the EOU OS9Boot out of the way on the SDcard:
$ sudo os9 rename /dev/sdg,OS9Boot OS9Boot.eou
After listing both sets of modules, and idenfying their Editions, Revisions, CRCs, and checksums, I made a pass and listed my unified set of modules to build an OS9Boot with:
| Module | Edition | Source | Rationale | |
|---|---|---|---|---|
| 1 | KrnP2 | 19 | FPGA | EOU's KrnP2 was not fully compatible with CoCo3FPGA |
| 2 | KrnP3 | 3 | EOU | EOU's nice error facility |
| 3 | IOMan | 13 | EOU | Newer IOMan |
| 4 | Init | 1 | EOU | FPGA and EOU were the same checksum |
| 5 | RBF | 37 | EOU | Random Block File - the main storage file manager |
| 6 | rbdw | 4 | FPGA | DriveWire disk block access |
| 7 | dwio | 22 | FPGA | DriveWire low-level I/O |
| 8 | X1 | 82 | FPGA | DriveWire disk descriptor |
| 9 | X2 | 82 | FPGA | DriveWire disk descriptor |
| 10 | X3 | 82 | FPGA | DriveWire disk descriptor |
| 11 | X0 | 82 | FPGA | DriveWire disk descriptor |
| 12 | RBSuper | 2 | FPGA | The SuperDriver for accessing many types of storage |
| 13 | llcoco3fpga | 22 | FPGA | The CoCo3FPGA SDcard over SPI low-level device I/O |
| 14 | SD1 | 82 | FPGA | An additional partition device descriptor for a second SDboot paritiion on the CoCo3FPGA SD card |
| 15 | RAMD | 1 | FPGA | A RAMdisk driver compatible with the CoCo3FPGA 8MB SDRAM |
| 16 | R0 | 82 | FPGA | A RAMdisk device descriptor |
| 17 | DD | 82 | FPGA | The Default Drive device descriptor for Partition 0 on the CoCo3FPGA SD card |
| 18 | SCF | 18 | EOU | Sequential Character File Manager - the main peripherals manager |
| 19 | VTIO | 4 | EOU | Virtual Terminal I/O driver - the Color Computer keyboard and console screen (EOU version contains KeyDrv) |
| 20 | JoyDrv | 9 | EOU | Joystick I/O Driver for VTIO |
| 21 | SndDrv | 4 | EOU | Sound I/O Driver for VTIO (beeps and keyclicks) |
| 22 | CoWin | 2 | EOU | The Windowing System driver |
| 23 | CoVDG | 2 | EOU | The hardware VDG screen driver |
| 24 | Term | EOU | The default Terminal keyboard and console screen device descriptor | |
| 25 | W | EOU | “Next Window” device window descriptor | |
| 26 | W1 | EOU | Device window descriptor | |
| 27 | W2 | EOU | Device window descriptor | |
| 28 | W3 | EOU | Device window descriptor | |
| 29 | W4 | EOU | Device window descriptor | |
| 30 | W5 | EOU | Device window descriptor | |
| 31 | W6 | EOU | Device window descriptor | |
| 32 | W7 | EOU | Device window descriptor | |
| 33 | W8 | EOU | Device window descriptor | |
| 34 | W9 | EOU | Device window descriptor | |
| 35 | W10 | EOU | Device window descriptor | |
| 36 | W11 | EOU | Device window descriptor | |
| 37 | W12 | EOU | Device window descriptor | |
| 38 | W13 | EOU | Device window descriptor | |
| 39 | W14 | EOU | Device window descriptor | |
| 40 | W15 | EOU | Device window descriptor | |
| 41 | Verm | EOU | “Virtual” termin device descriptor | |
| 42 | scdwv | FPGA | DriveWire virtual windows for connections | |
| 43 | N | FPGA | “Next DriveWire Window” device descriptor | |
| 44 | N1 | FPGA | DriveWire device descriptor | |
| 45 | N2 | FPGA | DriveWire device descriptor | |
| 46 | N3 | FPGA | DriveWire device descriptor | |
| 47 | N4 | FPGA | DriveWire device descriptor | |
| 48 | N5 | FPGA | DriveWire device descriptor | |
| 49 | N6 | FPGA | DriveWire device descriptor | |
| 50 | N7 | FPGA | DriveWire device descriptor | |
| 51 | N8 | FPGA | DriveWire device descriptor | |
| 52 | N9 | FPGA | DriveWire device descriptor | |
| 53 | N10 | FPGA | DriveWire device descriptor | |
| 54 | N11 | FPGA | DriveWire device descriptor | |
| 55 | N12 | FPGA | DriveWire device descriptor | |
| 56 | N13 | FPGA | DriveWire device descriptor | |
| 57 | MIDI | FPGA | DriveWire MIDI device descriptor | |
| 58 | Z1 | FPGA | DriveWire device descriptor | |
| 59 | Z2 | FPGA | DriveWire device descriptor | |
| 60 | Z3 | FPGA | DriveWire device descriptor | |
| 61 | Z4 | FPGA | DriveWire device descriptor | |
| 62 | Z5 | FPGA | DriveWire device descriptor | |
| 63 | Z6 | FPGA | DriveWire device descriptor | |
| 64 | Z7 | FPGA | DriveWire device descriptor | |
| 65 | scdwp | FPGA | DriveWire printer driver | |
| 66 | p | FPGA | DriveWire printer device descriptor | |
| 67 | VRN | EOU | VRQ/RAM/Nil device driver | |
| 68 | Nil | EOU | OS-9 Level II Nil device backwards-compatibility device descriptor | |
| 69 | VI | EOU | Kings Quest 3 / Leisure Suit Larry backwards-compatibility device descriptor | |
| 70 | FTDD | EOU | Flight Sim II backwards-compatibility device descriptor | |
| 71 | PipeMan | EOU | The Pipe Manager | |
| 72 | Piper | EOU | The Pipe device driver | |
| 73 | Pipe | EOU | The Pipe device descriptor | |
| 74 | Clock | FPGA | The kernel clock interface | |
| 75 | Clock2 | FPGA | The DriveWire clock I/O |
Each chosen module was copied from FPGA or EOU folder into BOOTFILES folder in numeric order listed in the table.
Once all of the modules were in place, building the OS9Boot file to test was a simple “cat”:
$ cat BOOTFILES/[0-9]* > OS9Boot
Then the OS9Boot to test was copied to the SDcard:
$ sudo os9 copy OS9Boot /dev/sdg,OS9Boot
And set permissions
$ sudo os9 attr -npr /dev/sdg,OS9Boot $ sudo os9 attr -npr /dev/sdg,ccbkrn
Building the right “set” of modules took a bit of trial and error.
/DD/SysGo
Booting with the stock EoU 6.1.0 SysGo will hang at the “Detecting CoCoSDC” stage.
You can assemble an updated SysGo from:
https://github.com/n6il/sysgo
This repository builds a disk image with updated SysGo source.
Boot into Ease of Use, attach the floppy image, and run make to use Ease of Use to build your new SysGo.
Use the Toolshed os9 utility to copy the new SysGo out of the build image and into your SD card.
/DD/SYS/env.file
Replace the default /D0, /D1, /H0 devices in the env.file.
Copy the env.file out of your Ease of Use SD card:
$ sudo os9 copy /dev/sdg,SYS/env.file env.file
OS-9 uses just a Carriage Return (CR) for end of line in text files.
UNIX and Linux use just a Line Feed (LF) for end of line.
To convert the OS-9 format to be easily edited on Linux:
$ mac2unix env.file
Edit the file to change the RBFDEVS= line to remove /D0 and /H0 and add your new CoCo3FPGA storage devices.
You can have up to 5, but Ease of Use recommends at most 4, to allow one “slot” in Multi-Vue to use for changing to other devices.
For my env.file, I used
RBFDEV=/DD, /R0, /X0, /X1
There are a number of other settings you might want to change described in the Ease of Use Project documentation such as default screen modes such as 80 column as well as starting colors and palette choices.
Once you are done customizing, convert env.file back to OS-9 format:
$ unix2mac env.file
Remove your stock env.file from the SD card:
$ sudo os9 del /dev/sdg,SYS/env.file
Copy your modified env.file to the SD card into place instead:
$ sudo os9 copy env.file /dev/sdg,SYS/env.file
/DD/startup
If you use DriveWire like I do, then you can comment out the call to setime in the startup file to avoid an annoying error message.
The same copy from SD card, convert line endings, edit, and copy back to SD card procedure above can be used here.
Boot Time
And with those changes (ccbkrn, OS9Boot, SysGo, env.file, and startup) you're ready to try a boot.
The Ease of Use Project documentation on NitrOS-9 Boot Process is your helpful friend here.
It may take several rounds of debugging each step if there is a crash stop or hang during boot.
Persevere and you will be rewarded.
Double-check each step above as needed to get each stage of boot working in sequence.
Discuss
If you would like to discuss this page:
Join the Color Computer Discord and post your comments to the #nitros9eou channel within the Operating Systems channel category
or to the CoCo3FPGA group on groups.io.
RESOURCES
Toolshed
LWTools
de1flash
NitrOS-9
NitrOS-9 Ease of Use
https://github.com/beretta42/sdboot
https://github.com/n6il/sysgo