Category Archives: NitrOS9

My old Space Invaders game running on an arcade cabinet!

A few years back, Color Computer community member Rietveld Rietveld took an Arcade1Up Rampage cabinet and converted it so I could run other software — such as emulators. Images have been shown of it running the Color Computer emulator and software.

Now, with the official 1.0 release of the NitrOS9 “Ease of Use”, that has been installed on this arcade machine and, by request, my OS-9 game Invaders09 has been ran on it.

I never imagined that my “arcade” game would eventually be running on a (sorta) arcade machine. Thanks, Rietveld!

I found hidden stuff in my own game.

On August 21, 1994 I began writing a space invaders game for the Radio Shack TRS-80 Color Computer. The game was written in 6809 assembly language, and ran under the Microware OS-9 operating sytem as opposed to the ROM-based Disk Extended Color BASIC.

It did not initially start out as an OS-9 game. It started out as a NitrOS9 game. NitrOS9 was (and still is) a greatly optimized and enhanced version of the stock OS-9 for the Color Computer. It was initially a set of patches that took advantage of the hidden features of the Hitatchi 6309 chip. Many of us did CPU swaps in our CoCo 3s specifically to be able to run this faster version of OS-9. Years later, NitrOS-9 was backported to run on a stock 6809 and the project continues today with the Ease of Use edition where it comes ready to run and bundled with all kinds of utilities, applications, and games. (I think my game is even on there.)

But I digress.

The reason I chose to write a game was after learning about a new system call that NitrOS9 added. It allowed mapping in graphics screen memory so a program could directly access it — just like from BASIC. With that in mind, I wrote a simple demo that had a peace-sign space ship that could move left and right and fire (multishots!), as well as a scrolling star background.

I believe my game demo source might have been published in The International OS-9 Underground magazine at some point.

As soon as I figure out how to make WordPress allow uploading a .asm source file, I’ll share it here.

But I digress. Again.

Invaders09 Secrets

Version 1.00 was completed on September 24, 1994. It was first sold at the 1994 Atlanta CoCoFest. I don’t remember how many copies the game sold over its lifetime, but I do know it was not enough to retire on. :)

On December 26, 1994, version 1.01 was released. This contained code by Robert Gault that allowed the game to work on machines with more than 512K memory. (Robert was also responsible for code that allowed the game to work on stock OS-9, as well.)

A big update happened on January 29, 1995, when the game was upgraded from a 4-color screen to glorious 16 colors.

1.03 was completed on February 4, 1995 and included bug fixes.

Almost twenty years later, to the day, I did a 1.04 update. The title screen text removed my old P.O. Box from Texas, and replaced it with an e-mail address. I also added the “secret” command line option to the help screen, so it would no longer be secret. There had also been a bug that caused the fonts to sometimes fail to load, which I found and fixed. There were also some bad bits in the graphics I had never noticed (but could see clearly on a modern monitor) which were corrected.

Something old. Something new?

I pulled up this source code today and was looking at it to see what all I’d have to do to convert it to run under Disk Extended Color BASIC. I’d have to learn about keyboard and joystick reading in assembly, as well as how to map in graphics screens. I’d also have to take care of the blips and boops, and create my own graphical text engine for displaying game and title screen messages.

I don’t know how to do any of that, yet.

But I did discover something I have no recollection of… The game contains its own font data, which it loads when the game first runs. (Note to self: Better check and make sure the game cleans that font up and deallocates it when the game exits.)

The font data is a series of fcb byte entries like these:

* 91 [
 fcb 126, 64, 64, 96, 96, 96, 126, 0
* 92 \
 fcb 64,64,32,24,12,6,6,0
* 93 ]
 fcb 126, 2, 2, 6, 6, 6, 126, 0
* 94 up arrow
 fcb 24,52,98,0,0,0,0,0
* 95 _
 fcb 0, 0, 0, 0, 0, 0, 0, 255
* 96 `
 fcb 96, 48, 0, 0, 0, 0, 0, 0
* 97 a
 fcb 0, 0, 62, 2, 126, 98, 126, 0

The fonts are 8×8 pixels in size, so each entry has 8 bytes to represent the character.

At the top of the font data was a comment that caught my attention:

* hidden stuff in the font! :)

Hidden stuff? What did I hide? It appears there was repeating data in the first 32 font characters before the SPACE at 32:

 fcb $05,$00,$08,$00,$08,$04,$00 <- GPBufLoad Stuff
 fcb 0,87,81,119,20,23,0,0  * hidden stuff in the font! :)
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
 fcb 0,87,81,119,20,23,0,0
* 32 (space)
 fcb 0, 0, 0, 0, 0, 0, 0, 0

I was curious what that was, so I searched to see if I could find an only bitmap font editor. Sure enough, someone has one for doing Commodore fonts:

I went there, and was able to recreate this “hidden stuff” in the font:

I had hidden a teeny tiny “42” in the font character set… Something no one would ever see, and that I had forgotten about.

Sub-Etha Software had other hidden 42s in other programs we distributed. I bet I’ve forgotten about some of them, as well…

But wait, there’s more … BASIC!

I took the code I wrote to display VIC-20 font data on a CoCo and updated it a bit, with this font data.

Invaders09 font data displayed on PMODE 0 under Extended Color BASIC.

You can adjust the WD variable in line 10 based on what PMODE you want to see it in. Change that to 32 and PMODE 4 and you get it in the size it would be on a CoCo 32-column screen. Use 16 and that will work with PMODE 0 or PMODE 2. (PMODE 1 and 3 are color modes and just look weird since they take the 8 bits and turn them in to four 2-bit color pixels).


10 WD=16 '16=PMODE 0/2, 32=4
30 L=1536+2048:C=0
40 FOR R=0 TO 7:READ D:IF D=-1 THEN 999
60 L=L+1:C=C+1:IF C>=WD THEN C=0:L=L+(WD*8)
70 GOTO 40
999 GOTO 999
1000 ' hidden stuff in the font! :)
1010 DATA 0,87,81,119,20,23,0,0
1020 DATA 0,87,81,119,20,23,0,0
1030 DATA 0,87,81,119,20,23,0,0
1040 DATA 0,87,81,119,20,23,0,0
1050 DATA 0,87,81,119,20,23,0,0
1060 DATA 0,87,81,119,20,23,0,0
1070 DATA 0,87,81,119,20,23,0,0
1080 DATA 0,87,81,119,20,23,0,0
1090 DATA 0,87,81,119,20,23,0,0
1100 DATA 0,87,81,119,20,23,0,0
1110 DATA 0,87,81,119,20,23,0,0
1120 DATA 0,87,81,119,20,23,0,0
1130 DATA 0,87,81,119,20,23,0,0
1140 DATA 0,87,81,119,20,23,0,0
1150 DATA 0,87,81,119,20,23,0,0
1160 DATA 0,87,81,119,20,23,0,0
1170 DATA 0,87,81,119,20,23,0,0
1180 DATA 0,87,81,119,20,23,0,0
1190 DATA 0,87,81,119,20,23,0,0
1200 DATA 0,87,81,119,20,23,0,0
1210 DATA 0,87,81,119,20,23,0,0
1220 DATA 0,87,81,119,20,23,0,0
1230 DATA 0,87,81,119,20,23,0,0
1240 DATA 0,87,81,119,20,23,0,0
1250 DATA 0,87,81,119,20,23,0,0
1260 DATA 0,87,81,119,20,23,0,0
1270 DATA 0,87,81,119,20,23,0,0
1280 DATA 0,87,81,119,20,23,0,0
1290 DATA 0,87,81,119,20,23,0,0
1300 DATA 0,87,81,119,20,23,0,0
1310 DATA 0,87,81,119,20,23,0,0
1320 DATA 0,87,81,119,20,23,0,0
1330 ' 32 (space)
1340 DATA 0, 0, 0, 0, 0, 0, 0, 0
1350 DATA 16, 16, 24, 24, 24, 0, 24, 0
1360 DATA 102, 102, 204, 0, 0, 0, 0, 0
1370 DATA 68, 68, 255, 68, 255, 102, 102, 0
1380 DATA 24, 126, 64, 126, 6, 126, 24, 0
1390 DATA 98, 68, 8, 16, 49, 99, 0, 0
1400 DATA 62, 32, 34, 127, 98, 98, 126, 0
1410 DATA 56, 56, 24, 48, 0, 0, 0, 0
1420 DATA 12, 24, 48, 48, 56, 28, 12, 0
1430 DATA 48, 56, 28, 12, 12, 24, 48, 0
1440 DATA 0, 24, 36, 90, 36, 24, 0, 0
1450 DATA 0, 24, 24, 124, 16, 16, 0, 0
1460 DATA 0, 0, 0, 0, 0, 48, 48, 96
1470 DATA 0, 0, 0, 126, 0, 0, 0, 0
1480 DATA 0, 0, 0, 0, 0, 48, 48, 0
1490 ' 47 /
1500 DATA 2, 2, 4, 24, 48, 96, 96, 0
1510 DATA 126, 66, 66, 70, 70, 70, 126, 0
1520 DATA 8, 8, 8, 24, 24, 24, 24, 0
1530 DATA 126, 66, 2, 126, 96, 98, 126, 0
1540 DATA 124, 68, 4, 62, 6, 70, 126, 0
1550 DATA 124, 68, 68, 68, 126, 12, 12, 0
1560 DATA 126, 64, 64, 126, 6, 70, 126, 0
1570 DATA 126, 66, 64, 126, 70, 70, 126, 0
1580 DATA 62, 2, 2, 6, 6, 6, 6, 0
1590 DATA 60, 36, 36, 126, 70, 70, 126, 0
1600 DATA 126, 66, 66, 126, 6, 6, 6, 0
1610 DATA 0, 24, 24, 0, 24, 24, 0, 0
1620 DATA 0, 24, 24, 0, 24, 24, 48, 0
1630 DATA 6, 12, 24, 48, 28, 14, 7, 0
1640 DATA 0, 0, 126, 0, 126, 0, 0, 0
1650 DATA 112, 56, 28, 6, 12, 24, 48, 0
1660 DATA 126, 6, 6, 126, 96, 0, 96, 0
1670 ' 64
1680 DATA 60, 66, 74, 78, 76, 64, 62, 0
1690 DATA 60, 36, 36, 126, 98, 98, 98, 0
1700 DATA 124, 68, 68, 126, 98, 98, 126, 0
1710 DATA 126, 66, 64, 96, 96, 98, 126, 0
1720 DATA 124, 66, 66, 98, 98, 98, 124, 0
1730 DATA 126, 64, 64, 124, 96, 96, 126, 0
1740 DATA 126, 64, 64, 124, 96, 96, 96, 0
1750 DATA 126, 66, 64, 102, 98, 98, 126, 0
1760 DATA 66, 66, 66, 126, 98, 98, 98, 0
1770 DATA 16, 16, 16, 24, 24, 24, 24, 0
1780 DATA 4, 4, 4, 6, 6, 70, 126, 0
1790 DATA 68, 68, 68, 126, 98, 98, 98, 0
1800 DATA 64, 64, 64, 96, 96, 96, 124, 0
1810 DATA 127, 73, 73, 109, 109, 109, 109, 0
1820 DATA 126, 66, 66, 98, 98, 98, 98, 0
1830 DATA 126, 66, 66, 98, 98, 98, 126, 0
1840 DATA 126, 66, 66, 126, 96, 96, 96, 0
1850 DATA 126, 66, 66, 66, 66, 78, 126, 0
1860 DATA 124, 68, 68, 126, 98, 98, 98, 0
1870 DATA 126, 66, 64, 126, 6, 70, 126, 0
1880 DATA 126, 16, 16, 24, 24, 24, 24, 0
1890 DATA 66, 66, 66, 98, 98, 98, 126, 0
1900 DATA 98, 98, 98, 102, 36, 36, 60, 0
1910 DATA 74, 74, 74, 106, 106, 106, 126, 0
1920 DATA 66, 66, 66, 60, 98, 98, 98, 0
1930 DATA 66, 66, 66, 126, 24, 24, 24, 0
1940 DATA 126, 66, 6, 24, 96, 98, 126, 0
1950 ' 91 [
1960 DATA 126, 64, 64, 96, 96, 96, 126, 0
1970 ' 92 \
1980 DATA 64,64,32,24,12,6,6,0
1990 ' 93 ]
2000 DATA 126, 2, 2, 6, 6, 6, 126, 0
2010 ' 94 up arrow
2020 DATA 24,52,98,0,0,0,0,0
2030 ' 95 _
2040 DATA 0, 0, 0, 0, 0, 0, 0, 255
2050 ' 96 `
2060 DATA 96, 48, 0, 0, 0, 0, 0, 0
2070 ' 97 a
2080 DATA 0, 0, 62, 2, 126, 98, 126, 0
2090 DATA 64, 64, 126, 70, 70, 70, 126, 0
2100 DATA 0, 0, 126, 66, 96, 98, 126, 0
2110 DATA 2, 2, 126, 66, 70, 70, 126, 0
2120 DATA 0, 0, 124, 68, 124, 98, 126, 0
2130 DATA 62, 34, 32, 120, 48, 48, 48, 0
2140 DATA 0, 0, 126, 66, 98, 126, 2, 62
2150 DATA 64, 64, 126, 66, 98, 98, 98, 0
2160 DATA 16, 0, 16, 16, 24, 24, 24, 0
2170 DATA 0, 2, 0, 2, 2, 2, 98, 126
2180 DATA 96, 96, 100, 68, 126, 70, 70, 0
2190 DATA 16, 16, 16, 16, 24, 24, 24, 0
2200 DATA 0, 0, 98, 126, 74, 106, 106, 0
2210 DATA 0, 0, 126, 66, 98, 98, 98, 0
2220 DATA 0, 0, 126, 66, 98, 98, 126, 0
2230 DATA 0, 0, 126, 66, 66, 126, 96, 96
2240 DATA 0, 0, 126, 66, 78, 126, 2, 2
2250 DATA 0, 0, 124, 96, 96, 96, 96, 0
2260 DATA 0, 0, 126, 64, 126, 6, 126, 0
2270 DATA 16, 16, 126, 16, 24, 24, 24, 0
2280 DATA 0, 0, 66, 66, 98, 98, 126, 0
2290 DATA 0, 0, 98, 98, 98, 36, 24, 0
2300 DATA 0, 0, 66, 74, 106, 126, 36, 0
2310 DATA 0, 0, 98, 126, 24, 126, 98, 0
2320 DATA 0, 0, 98, 98, 98, 36, 24, 112
2330 DATA 0, 0, 126, 108, 24, 50, 126, 0
2340 DATA 14, 24, 24, 112, 24, 24, 14, 0
2350 DATA 24, 24, 24, 0, 24, 24, 24, 0
2360 DATA 112, 24, 24, 14, 24, 24, 112, 0
2370 DATA 50, 126, 76, 0, 0, 0, 0, 0
2380 DATA 102, 51, 153, 204, 102, 51, 153, 204
2390 DATA 102, 51, 153, 204, 102, 51, 153, 204
2400 DATA -1

Until next time…

Building KenTon/LR-Tech SCSI drivers for NitrOS-9

While the NitrOS-9 project does contain drivers for the KenTon and LR-Tech hard drive interfaces, they are not built or included by default. I wanted to document the steps I took to build and use the KenTon interface under the current NitrOS-9.

Basically, you will be modifying a few makefiles to enable the building of the low level booter, device drivers and device descriptors. If I recall, the changes are the same for each of these makefiles, but you only need to make them for the one you are using. If you are only using the KenTon drivers under NitrOS-9 Level 2 on a CoCo 3, just do that makefile.

  • nitros9/level1/coco1/modules/makefile
  • nitros9/level2/coco3/modules/makefile
  • nitros9/level3/coco3/modules/makefile

Step 1 – Add “KTLRFLAGS”.

These generate the define used inside the generic SCSI source code so it knows which code to build.


Step 2 – Add “boot_ktlr” to the BOOTER list.

This makes it a dependency so make will look for it and try to build it. I added it in the middle of the list so when you get updates, it will be easier for the “diff” tool to see what has changed.

BOOTERS = boot_1773_6ms boot_1773_30ms \
 boot_burke boot_rampak boot_wd1002 boot_dw \
 boot_tc3 boot_ide boot_rom boot_dw_becker \
 boot_ktlr \
 boot_dw_arduino boot_dw_38400 boot_sdc

Step 3 – Add the modules to the RBF list.

RBF = \
 rbdw.dr \
 rb1773.dr rb1773_scii_ff74.dr rb1773_scii_ff58.dr \
 ddd0_35s.dd d0_35s.dd d1_35s.dd d2_35s.dd d3_35s.dd \
 ddd0_40d.dd d0_40d.dd d1_40d.dd d2_40d.dd \
 ddd0_80d.dd d0_80d.dd d1_80d.dd d2_80d.dd \
 ddx0.dd x0.dd x1.dd x2.dd x3.dd \
 rbsuper.dr lltc3.dr llide.dr llcocosdc.dr \
 llktlr.dr \
 dds0_ktlr.dd s0_ktlr.dd s1_ktlr.dd s2_ktlr.dd s3_ktlr.dd s4_ktlr.dd \
     s5_ktlr.dd s6_ktlr.dd sh_ktlr.dd \
 ddi0_ide.dd i0_ide.dd i1_ide.dd ih_ide.dd \
 dds0_tc3.dd s0_tc3.dd s1_tc3.dd s2_tc3.dd s3_tc3.dd s4_tc3.dd \
     s5_tc3.dd s6_tc3.dd sh_tc3.dd \
 ddsd0_cocosdc.dd sd0_cocosdc.dd sd1_cocosdc.dd

Step 4 – Add the dependency to build the driver:

# TC^3 SCSI Booter
boot_tc3: boot_scsi.asm
 $(AS) $(ASOUT)$@ $< $(TC3FLAGS)

# KenTon/LR-Tech SCSI Booter
boot_ktlr: boot_scsi.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS)
# SuperIDE/Glenside IDE Booter
boot_ide: boot_ide.asm
 $(AS) $(ASOUT)$@ $< $(IDEFLAGS)

Step 5 – Add the dependencies for building each descriptor. I put mine after the existing TC3 SCSI driver stuff:

sh_tc3.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(TC3FLAGS) $(HDBDOS)

# KenTon/LR-Tech SCSI Descriptors
dds0_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID0) -DDD=1

s0_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID0) $(SCSI_HD)

s1_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID1) $(SCSI_HD)

s2_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID2) $(SCSI_HD)

s3_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID3) $(SCSI_HD)

s4_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID4) $(SCSI_HD)

s5_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID5) $(SCSI_HD)

s6_ktlr.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(KTLRFLAGS) $(ID6) $(SCSI_HD)

sh_ktlr.dd: superdesc.asm

# IDE Descriptors
ddi0_ide.dd: superdesc.asm
 $(AS) $(ASOUT)$@ $< $(IDEFLAGS) $(MASTER) -DDD=1

Now those modules should be built and made available for including in your bootfile. You could do this by editing the bootlist you are using:

  • nitros9/level1/coco1/bootlists/
  • nitros9/level2/coco3/bootlists/
  • nitros9/level3/coco3/bootlists/

Or you could use a bootfile editor like ezgen to add them to your current bootfile. Or, if you were just doing something temporary (like I was, to pull data from hard drives), you could just merge the needed modules together and dynamically load them when you need to use the SCSI drive.

Hopefully this will be helpful to someone else.

Creating a RaspberryPi DriveWire server

  • 2016/05/12  This is a work-in-progress article I originally wrote on February 8, 2015, but never completed. The other night I was trying to look up my notes to help Curtis B. with a NitrOS-9 boot disk and I realized I never completed this. I will try to finish it when I have a moment.


To get DriveWire 4 server running on a Raspberry Pi, you will do the following:

  1. Download the DriveWire server to the Pi and unzip it:
  2. Edit the config.xml file to default to your serial port on your Pi in <deviceType> and <serialDevice>. (i.e., “serial” and “/dev/ttyUSB0“)
  3. Run the server with no user interface:
    java -jar DW4UI.jar -noui
  4. On the CoCo, load the needed DriveWire modules from NITROS9/6x08L2/MODULES/RBF:, rbdw.dr, x0.dd up to x3.dd
  5. Use the “dw” command to test things by creating a blank disk image:
    dw disk create 0 /home/pi/test.dsk
    format /x0
    dir /x0
  6. Customize your boot disk to include the modules you want and read the documentation to learn how to use all the cool virtual terminals, MIDI and other neat features.

And now, the long version…

Materials Needed

  1. Raspberry Pi B (or B+, or probably the Pi 2 B). I did all these steps on a B.
  2. USB keyboard (a mouse makes things easier, but I do not have one so all of these tips will just use a Pi, keyboard and HDMI TV/monitor).
  3. Compatible* 8GB SD card (or larger).
  4. Ethernet cable to hook the Pi to the Internet. (Required if you plan to do the network install of NOOBS LITE).
  5. WiFi (with a supported USB dongle) or Ethernet is needed later for downloading the DriveWire software and updates, but there are ways to do all of this without any Internet access if you start with the full NOOBs installer.
  6. Compatible* USB serial adapter (or TTL->RS232 converter for use with the built in UART pins of the Pi).

Preparation on Windows/Mac/Linux

  1. Download the “NOOBS” installation for Raspberry Pi (currently 1.3.12). You can get the full NOOBS (780MB, just unzip and copy to the SD card and boot), or the NOOBS LITE (22.8MB) version.
    • NOOBS LITE can also be used. It is a much smaller download, but requires the Pi to be hooked up to the internet via Ethernet to download the rest of the OS files which is about 2355MB.
  2. Unzip the files, then copy them over to a freshly formatted SD card.

Preparation on the Raspberry Pi

  1. Boot the Pi using this card. You will see a menu of operating systems you can install. Choose “Raspbian [RECOMMENDED]” at the top by using the arrow keys and SPACE to select. You may also wish to hit “l” for Language and set it to “English (US)” or your preference, and “9” for Keyboard and select yours. Once Raspbian is selected, press “I” for install. It will ask if you are sure you wish to overwrite the SD card. Select “Y” for yes.
    • NOOBS LITE: The Pi will then download the Raspbian image (2.3GB), then install.
    • NOOBS: The Pi will then install.
  2. The Pi will (eventually) reboot and after a bit, you get a DOS-like screen for the raspi-config utility. Arrow over to Finish and press ENTER. You will not be at the Pi shell prompt.
    pi@raspberrypi ~ $
  3. At this point, I like to do a full reboot to make sure everything is working properly:
    sudo reboot
  4. On a reboot, you won’t go directly to a shell prompt. You will get a login prompt. The default account is:
    username: pi
    password: rasbperry.
    Log in and you will get back to the shell prompt. You will be in the home directory for user “pi”.
  5. Now we need to download the DriveWire 4 software. Note the filename will change when DriveWire is updated, so check the official site if this does not work.
  6. After the zip file is download, you can extract it by typing:
  7. DriveWire 4 is set up to run with a nice GUI with mouse control. This requires a keyboard and mouse, and the Pi to be set up with X-Windows running. Since I do not have a mouse, and plan to run the Pi headless with nothing hooked up to it but power and the CoCo, this is not an option for me. Instead, I need to manually edit the configuration file to tell it what Linux serial port I will be using.
    cd DriveWire4_4.3.3
    copy config.xml (always keep a backup!)
    pico config.xml

    The editor will open, and you want to look for a few entries:<instance category=”instance” desc=”Autocreated 2013-03-24 23:57:53.831″ name=”TCP connection via TCP“>

    <DeviceType category=”device” list=”serial,tcp-server,tcp-client,dummy” type=”list”>tcp-server</DeviceType>

    <SerialDevice category=”device” type=”serialdev”>COM14</SerialDevice>The first entry is just the name of the connection. You could change that to “Serial Connection” or whatever. The second “tcp-“server” should be changed to “serial”, and the “COM14” entry should be changed to your serial port device. On my Pi, when I plug in a single USB RS232 adapter, it shows up as /dev/ttyUSB0 so that is what I use.
  8. Save your changes back to the file (Ctrl-X, Y) and now you are ready to run the server without a user interface. (Getting the user interface to run requires installed two more additional packages, and I will make a tutorial for that soon, if anyone wants me to.)
    java -jar DW4UI.jar -noui
  9. After a bit, Java will load and the DriveWire 4 server will start. Java is big, and the Pi is small, so it can be quite sluggish. Now, with the USB cable connected between the Pi and the CoCo, you can start testing.

Preparation on NitrOS-9

This tutorial is being written for someone who already has an active NitrOS-9 system and wants to add DriveWire support to it. If you have no customized

If you are using one of the default NitrOS-9 disk images for you system, it should have a NITROS9 directory, and inside of it will be various device drivers and descriptors, including the ones used by DriveWire. Ultimately, you would want to make a custom boot disk that includes these modules, but here is a simple way to merge them together and just load them when you want to use them. From OS-9:

  1. If you are running a stock CoCo 3 with the standard 6809 processor, go here:
    cd /dd/NITROS9/6809L2/MODULES

    …and if you have upgraded your CPU with a Hitachi 6309, go here:
    cd /dd/NITROS9/6309L2/MODULES
  2. The modules you want depend on what you plan to do. Here is the list:
    • – this module handles all communication with the DriveWire server.
    • rbdw.dr – RBF device driver that uses DriveWire for disk access instead of disk hardware
      • ddx0.dd, x0.dd, x1.dd, x2.dd, x3.dd – device descriptors for the DriveWire disk drives (/x0 to /x3, with ddx0.dd being a /dd descriptor for DriveWire).
    • scdwp.dr – printer driver
      • p_scdwp.dd – device descriptor /p for scdwp.dr
    • scdwv.dr – virtual serial port driver
      • n_scdwv.dd, n1_scdwv.dd to n13_scdwv.dd – serial port descriptors. /n is the “next available” descriptor, similar to /w for windows. /n devices may also be used for MIDI.
      • midi_scdwv.dd – this is n14 but named /midi for MIDI programs that are hard coded to look for that name.
      • term_z_scdwv.dt, z1_scdwv.dd to z7_scdwv.dd – (??? not in the doc wiki)
  3. For my example, I am only concerned about the disk drives, so I would merge the following modules together:
    chd RBF
    merge rbdw.dr x0.dd x1.dd x2.dd x3.dd >/dd/dw
    This gives me a single file called “dw” I can load to get DW support instantly. First, I need to set the attributes to allow that:
    attr /dd/dw e
    …then I can just load it when I want to use DriveWire:
    load /dd/dw
  4. If this worked, you should now be able to use the DriveWire command, “dw”, to communicate with the server. Type “dw” and it should report back a list of commands:
    config  disk  log  midi  net  port  server
    …and you can then type “dw config” or “dw disk” to see what all it can do.

Using DriveWire

Here is an example of creating an empty disk image and formatting it:

dw create 0 /home/pi/test.dsk
format /x0
dir /x0

If you look on the Pi, you will see a new file “test.dsk” there. You can now use this disk like any other OS-9 disk. In my test, I copied my NITROS9 directory over to it just for fun:

chd /dd/NITROS9
dsave /x0 ! shell

DriveWire’s performance is not as good as you’d get from a No Halt floppy controller like the Disto Super Controller 2 or a hard drive interface like the Cloud-9 SuperIDE or KenTon SCSI. As disk activity is going on, interrupts are masked while data is blasted out of the bitbanger port. Still, it did a remarkable job keeping up with my typing. Quite impressive for a cheap cable and a $35 computer with a serial port.


  1. Make the DriveWire 4 server auto-start.
  2. Update the DriveWire 4 software from the command line (is this even possible?).
  3. Update the Raspberry Pi software.


One issue I immediately ran in to was a bunch of ERROR #207 (Memory Full) errors. mfree still showed 352K free, and it wasn’t the #237 (RAM Full) that happens when there isn’t enough room left in the main 64K memory map.

Building NitrOS-9 on Mac OS X


Since I have to relearn all the steps, I thought I would post them as I go through them. The NitrOS-9 website has a tutorial on building it, but here are my steps with some specifically for Mac OS X:

  1. Install the Command Line Tools for Mac OS X.
    We need the command line versions of the Mac OS X compiler so we can build the tools that are then used to build NitrOS-9. If you have XCODE installed, you may already have them. An easy way to do this is from a Terminal prompt:
    xcode-select --install

    That will launch the Apple Mac App Store installer and get the tools for you. Cool.

Installing the Mac OS X command line tools.
Installing the Mac OS X command line tools.
  • Download Mercurial.
    The NitrOS-9 repository uses Mercurial as version control. You will need to download Mercurial. I had 3.2 the last time I did this, and currently it looks like 3.8 is available. There are several ways to download it using various package managers (Fink, MacPorts, etc.) but I don’t have this installed so I am just using the standalone installer:
    Depending on your Mac OS X security settings, it may complain that this is from an unknown developer and refuse to run. If you get this message, go in to your System Preferences “Security & Privacy” control panel and tell it to allow the installer to run:
    Screenshot 2016-05-01 17.26.21(Strange. The last time I did this, “Open Anyway” would let me bypass the security settings I am using. This time, it refused, and I had to temporarily allow “Anywhere.” Not sure what’s up with that.) After the install, you will have the “hg” command available.
  • Download LWTools. These are the cross-compiler tools used to build 6809 source code from Mac/Windows/Linux systems. From a Terminal prompt, find a directory you want to download the lwtools to. I chose a poor location — “CoCo” inside my Downloads folder:
    alsmbpro:lwtools allenh$ pwd

    From this directory, use the “hg” command to obtain and build the tools. It will build the directory you specify from the command line (“lwtools”):

    hg clone lwtools
    cd lwtools
    sudo make install
    cd ..
  • Build Toolshed.
    Next we want to build Toolshed. This is a series of command-line utilities that operate on CoCo/OS-9 disk images (like those used with emulators and the CoCoSDC interface). Once again, I do these steps from my “Downloads/CoCo” directory:
    hg clone toolshed
    cd toolshed
    sudo make -C build/unix install
    cd ..

    (Note: I had to use “sudo make…” here to get it to build on my system.) The different build/make process shows the different styles of the various developers that made these tools. (Note: Mine seems to fail looking for a command “markdown” at the very end. Not sure what this is, but it seems to be building HTML documentation or something.)

  • Build NitrOS-9.
    Now we are ready to download and build NitrOS-9. Once again, I start in my “Downloads/CoCo” directory, and issue the following hg commands to download all the NitrOS-9 stuff:
    hg clone nitros9
    cd nitros9
    make dsk
    This will build absolutely everything, including tons of ports and disk images you likely do not want. (i.e., if you are only interested in a CoCo 3 6809 setup, why build all the CoCo 1/2 and Dragon versions, or any of the 6309 stuff?). I always build everything, but you can also specify to build just a specific port. For my CoCo 3/6309 build, I could do this instead:
    make dsk PORTS=coco3_6309

    After this, you will have all the sources, and have built all (or some) of the sample disk images for various types of hardware (CoCo 1/2, CoCo 3, 6809 or 6309, CoCoSDC controller versus floppy or IDE hard drive, etc.).

  • Updating NitrOS-9 and the Tools.
    Later, if you want to update your sources, you can use this comment from the “nitros9” directory:
    hg pull
    hg update
    make dsk

    I do this occasionally to get the “latest and greatest.” You can do this for the other tools, too, by changing in to their directory then issuing the “pull” and “update”, then the appropriate make command.
    If you get a merge conflict because you changed something locally, you might see this:

    alsmbpro:nitros9 allenh$ hg update
    abort: outstanding merge conflicts

    You can use this command to see what files have been changed on your local repository that conflict with the master files. This happens if, for instance, you tweak a makefile or build list or source code:

    alsmbpro:nitros9 allenh$ hg resolve -l
    U 3rdparty/utils/tlindner/sdir.asm

    This reminded me that I already Tim’s “sdir” source code (for CoCoSDC) so enable built in help and such. I have to revert those changes if I want to update, or learn how to use the merge too… I forgot!

  • These steps should get you everything you need to begin playing with NitrOS-9 on a real CoCo with the CoCoSDC interface, or an emulator. If you plan to use real floppies, you can use toolshed utilities to format and then copy disk image .DSK files over to the physical floppy, but I don’t have any way to hook a 360K Floppy drive to my Mac so I have never done this. CoCoSDC is the way to go there ($40!).

    More to come…

    Invaders09 updated to 1.04

    Invaders09 1.04 title screen.
    Invaders09 1.04 title screen.

    Sub-Etha Software has released another update to our Color Computer 3 OS-9 space invaders-style game, Invaders09. Version 1.04 is now available and is a recommended upgrade for all users. It supplants previous February 1995 release of 1.03. As with all Sub-Etha Software products, bug fixes and maintenance releases are free upgrades.

    You may download the 1.04 update as a self-booting .DSK image from our update server:

    The INVADE09.DSK image includes a fully bootable version of NitrOS-9 v3.3.0 and may be ran directly on a real Color Computer 3 or emulator just by mounting the image and typing “DOS”. You may also copy the invaders1.04.txt documentation file and CMDS/invaders1.04 binary to your existing OS-9 Level 2 or NitrOS-9 6309 or 6809 system.


    • Updated title screen (website, new message).
    • Added “secret” options to help screen.
    • Fixed bug that made font not always load.
    • Fixed shield and border graphics, palette cleanup.


    • After 20 years, the game still doesn’t have an “attract mode” or “high score” listing. Maybe 1.05 will be out by 2025 to fix this. (Sorry about that, Bob Devries!)
    • The documentation refers to the binary as being called “invaders” but it is really “invaders1.04” on this release. Maybe the author won’t be so lazy next time and will name the binary correctly.


    File:  INVADERS.TXT - Revision 1.2 (2/7/2015) - By Allen C. Huffman
    |   I    NNNNN  VV  V   AAA   DDDD   EEEEE  RRRR   SSSSS   |
    |   I    N   N  VV  V   A A   D   D  E      R  R   S       |
    |   II   NN  N  VV VV  AAAAA  DD  D  EEEE   RRRRR  SSSSS   |
    |   II   NN  N   V V   AA  A  DD  D  EE     RR  R     SS   |
    |   II   NN  N    V    AA  A  DDDD   EEEEE  RR  R  SSSSS   |
    The Invasion Begins!
    By Allen C. Huffman
    Copyright (C) 1994,1995,2015 by Sub-Etha Software
         For years, determined scientists have probed the endless boundries of the
    universe for extra-terrestrial signals.  Countless satellites have been
    launched, radio signals transmitted, and theories formulated...all without
    results.  Until now...
         Far out in the eastern spiral arm of the galaxy, something was listening.
    And this something didn't like what it heard.  Soon outposts around the planet
    were picking up masses moving towards the Earth.  The planet was preparing for
    first contact, but no signals came from the void.
         The scientists prepared their welcome speeches.  The government, of
    course, prepared defense actions.  The tabloids prepared headlines about the
    end of the world.  The invasion began.
         Without warning, waves of disc shaped ships filled the skies.  Blasts of
    energy were fired on unsuspecting buildings, knocking out military
    installations before any retaliation strikes could be launched.  The Earth was
    defenseless except...of course...for one last hope.
         The E.T.H.A. (Extra Terrestrial Hope Association) had planned for the
    worst when the big day of contact would arrive.  Along with an endless supply
    of peaceful translation equipment they possessed an experimental plasma cannon.
     This would be Earth's only chance for survival.
         You, my friend, are the control operator of this cannon.  Good luck.
         Invaders09 is a self contained executable called "Invaders".  Copy it to
    your CMDS directory.  Usage is as follows:
         Invaders 1.04 by Allen Huffman (
         Copyright (C) 1994,95,2015 by Sub-Etha Software.
         Syntax: Invaders [-opts]
         Usage : LEFT/RIGHT to Move, SPACE to Fire, P to Pause, Q to Quit.
         Opts  : -? = display this message.
                 -m = monochrome colors (for 'montype m' displays).
                 -z = secret option if you think it is too slow.
                 -* = secret cheat mode (press * to skip level).
         At the title screen, joystick users should press "J" or the fire button to
    start the game.  [Note:  The joystick must be plugged into the left joystick
    port.]  For keyboard control, press "K".  "Q" will quit back to OS-9.
         The game will begin and the playfield will appear.  The object is simply
    to move your cannon (at the bottom of the screen) left and right to shoot at
    the bad guys.  Direct hits are required as any side shots will be absorbed
    harmlessly by the invaders.  Also, equipment limitations prevent your plasma
    cannon from moving and firing at the same time.  Readouts at the bottom of the
    screen display your current score, round, power rating, and lives remaining.
         Scoring:  Each invader you hit earns you 10 points.  Occassionally, a
    mother ship ufo will pass across the top of the playfied.  Destroying it is
    worth 100 points.
         Rounds:  After clearing out all fifty invaders, a new round will begin. 
    The invaders will start closer to the ground.
         Power:  This determines how many shots your cannon can fire at a time. 
    Each round gives you an extra shot up to the maximum of "J" (10 shots).  Each
    time you lose a life your power goes down by one to the minimum of "B" (two
         Lives:  You start with three cannons.  Use them wisely.  Without them the
    dreaded "Game Over" message will appear.
         Pause:  During game play, press "P" to pause the game.
         Quit:  Pressing "Q" during a game will quit.
         You have three shields to hide under.  Be warned:  They do not protect you
    from bombs dropped by the mothership.  Also, when the invaders get low enough
    your shields will disappear.  Be warned again.
         As with all classic arcade games, the enemies are never ending.  Each
    level causes the enemies to start closer and closer to the ground and they get
    faster and faster.  Good luck!
         Special thanks to YOU for helping support the future of the CoCo and OS-9
    by supporting vendors such as ourselves.  Without you, our hobby would have
    died years ago.
         Thanks to Bob Devries, Robert Gault, Colin McKay, Alan DeKok and the late
    Alex Forrest for helping beta test this product and get it to this stage.
    Programming on Invaders09 began on 8/21/94 and it debuted at the 1994 Atlanta
    * 1.00 09/24/94 - Release version for 1994 Atlanta CoCoFest!
    * 1.01 10/26/94 - Robert Gault patch for >512K systems
    *                 Since NitrOS9 call does not work for >512K, call removed
    * 1.02 01/29/95 - Converting to 16-color gfx screen (whew!)
    * 1.03 02/04/95 - Added test for valid screen BEFORE mapping it into MEM R.G.
    *                 Moved hiscore and packet (=enemies) to dp. A.H.
    * 1.04 02/07/15 - Updated title screen (website, new message).
    *                 Added "secret" options to help screen.
    *                 Fixed bug that made font not always load.
    *                 Fixed shield and border graphics, palette cleanup.

    Manually making a bootable NitrOS9 hard drive image – part 3

    See also: part 1, part 2 and part 3.

    • 2016/04/26 – I had a HUGE mistake in STEP 5 about what to put in LSN0 for the os9boot file size. (It’s sectors, not bytes – oops!) Thanks to Travis Poppe for helping me figure out what was wrong in my instructions. I have marked the updates in red. I will do some testing soon to make sure it is correct now.
    • 2016/05/01 – A minor correction to the instructions, and I added links to DSK images of the BASIC and OS-9 programs in this article, as well as a link to the full 128MB NitrOS-9 image, ready for you to start customizing.
    • 2017/02/05 – Well, this is confusing. Ignore my first correction. LSN 0 needs file size in bytes, not sectors. Correcting again.

    As promised in Part 1, and teased in Part 2, I finally present some simple steps to making a bootable OS-9 disk without using “cobbler” or “os9gen”. If I had understood this more back in the early 90s when I was using CoCo OS-9 Level 2 full-time, I don’t think I would have seen nearly as many BOOT FAILED messages :)

    Step 0 – Creating a 128MB disk image.

    This doesn’t have anything to do with the rest of the article, but it’s good to know. CoCoSDC creates disk images, by default as 35-track single sided images. As you write data past the end of those 35 tracks, the image expands. This can lead to fragmentation and performance issues as the CoCoSDC firmware has to juggle more bits and bytes. Instead, designer Darren Atkinson sent me a simple BASIC program that will create a .DSK image and expand it automatically to the size (in megabytes) you specify. I called mine SDCMAKE.DSK (download the SDCMAKE.DSK disk image here).

    20 DRIVE 1,DN$,NEW
    30 INPUT"SIZE MB";MB:IF MB>128 THEN 30
    40 A=&HFF48:SC=INT(MB*4096)-1
    50 B1=INT(SC/65536):B2=INT((SC-B1*65536)/256):B3=SC-B1*65536-B2*256
    60 POKE &HFF40,67:POKE A+1,B1:POKE A+2,B2
    70 POKE A+3,B3:POKE A,&HA1:POKE A+2,0
    80 IF (PEEK(A) AND 2)=0 THEN 80
    90 FOR I=1 TO 128:POKE A+3,0:NEXT
    100 IF PEEK(A) AND 1 THEN 100
    110 POKE &HFF40,0

    You can run that from BASIC and make a fresh “128MB.DSK” file to experiment on under OS-9.

    Step 1 – Format the hard drive for the 128MB.

    To do this, we must configure the /sd1 device descriptor so it provides 524,280 clusters – the most we can have (65535 bytes in the DAM, multiplied by 8 bits per = 524280). I use 65535 ($FFFF) cylinders, 8 sides, and 1 sector-per-track which works out to 524280 exactly.

    dmode /sd1 cyl=ffff sid=8 sct=1 t0s=1
    format /sd1

    NOTE: There may be more values that need to be set. I tried this tonight (2/5/2017) on an old SyQuest EZ135 SCSI drive (128MB as well) and format showed some real weird stuff. I think there were some other options in my SCSI descriptor (clusters, etc.) that I needed to override.

    Format should report “Disk capacity: 524280 sectors (134,215,680 bytes)” and you should see “Sectors/track” and “Track zero sect/trk” both at 1 (sct and t0s in the dmode command), and “Total physical cylinders” at 65,535 (cyl in the dmode command). Do not to a PHYSICAL format, and there is no need to Verify unless you just have some time to kill.

    Format Note: During the research for this article, I realized that not only is cobbler and os9gen broken in regards to hard drive images, but it appears format is as well. There is a byte in LSN 0 that indicates the type/format (DD.FMT) of the disk. It has bits that are associated with various floppy disk formats, with one representing single-sided or double-sided. It appears that, by default, format will set that side bit if sides > 1. By formatting a hard drive like I suggested (with sid=8), the double-sided bit will be set, and that throws off cobbler and os9gen. If you format using the “1” option, for singled sided, it will NOT set that bit (thus, single-sided) BUT it will override the sid=8 settings (or whatever is in the descriptor). What we really need are versions of these commands that have a “it’s a HARD DRIVE, darnit!” option that will not set those floppy drive bits. I expect this was done long ago when hard drives started getting affordable, but reinventing the wheel is fun so maybe that will be another article…

    Step 2 – Copy the kernel track from a bootable disk on sectors $264-$275 to sectors $264-$275 on /sd1.

    I did this using a brute-force BASIC09 program: (Download the KERCOPY.DSK disk image here.)

    PROCEDURE kercopy
    DIM in,out:BYTE
    DIM srcDev,dstDev:STRING
    DIM sectorNum:REAL
    DIM sectorData(256):BYTE
    INPUT "Source drive with kernel:",srcDev
    INPUT "Destination drive       :",dstDev
    OPEN #in,srcDev+"@":READ
    OPEN #out,dstDev+"@":UPDATE
    FOR sectorNum=$0264 TO $0275
    PRINT "Copying sector "; sectorNum; " from "; srcDev; " to "; dstDev
    ; "..."
    SEEK #in,sectorNum*256
    GET #in,sectorData
    SEEK #out,sectorNum*256
    PUT #out,sectorData
    NEXT sectorNum
    CLOSE #out
    CLOSE #in

    Please note that this program does no error checking. When you run it, you would type in “/sd0” for the source disk (if that is the one with your kernel boot track) and “/sd1” for the destination. It will then simply read all the boot track sectors from /sd0 and write them to the same place on /sd1.

    Given a bit more time, I need to make that program take care of this next step so it does not have to be done manually… At that point, it would be a nice replacement for cobbler, almost.

    Step 3 – Mark sectors $264-$275 as used to prevent files from overwriting the “hidden” kernel track.

    I use dEd to edit the hard drive in raw mode (/sd1@)  and then just find the 18 appropriate bits in the DAM (disk allocation bitmap) that represent the 18 sectors of the kernel track and set them.

    The boot track is located on sectors $264-$275 in the DAM (disk allocation bitmap). The DAM starts at LSN 1. You basically want to set the 18 bits that represent sectors $264-$275. They reside in bytes $14C, $14D and $1FE:

    • offset $14C = $0F (00001111)
    • offset $14D = $FF (11111111)
    • offset $14E = $FC (11111100)
    ded /sd1@
    CMD: s 1 [ENTER] (skip to LSN=$01 one)
    CMD: e (edit mode)
    Cursor over to row 04, column C and change that to $0F
    Cursor over to row 04, column D and change that to $FF
    Cursor over to row 04, column E and change that to $FC
    [ENTER] to exit edit mode
    CMD: w (to write sector)
    Are you sure? y (yes, you are sure)

    Step 4 – Copy your OS9Boot file over to /sd1. If this disk is freshly formatted, it should copy as a contiguous (non-fragmented) file.

    copy /sd0/OS9Boot /sd1/OS9Boot

    Step 5 – Mark the location and size of the bootfile in logical sector 0. This is how the booter knows where to find OS9Boot.

    To do this, I do a “dir -e /sd1” and note the “Sector” and “Bytecount” (size) fields. In my example, dir reports OS9Boot is at Sector 109 and has a Bytecount (size) of $5EDD. The sector reported is NOT the one we want to use. That sector is where the File ID sector is for OS9Boot. File ID is what contains the attributes, owner, creation date, etc. as well as the segment list. For a fragmented file, the File ID sector may contain up to 48 entries of different file segments.

    Using “ded /sd1@” again, first we want to verify where OS9Boot is. Open dEd, and skip to the sector that was shown in the “dir -e /sd1” output:

    ded /sd1@
    s 109 [ENTER] (skip to sector shown in the dir -e display)

    That sector should have some data on the first row (00), and a few entries on the second row (10). The second row is what we really want. The first three bytes (offsets $10-$12) are the starting sector for the segment (where OS9Boot really begins), and the next two bytes (offsets $13-$14) are the size in sectors.

    On a freshly formatted disk, the starting sector should be one higher than what “dir -e” showed. On my system, it is “00 01 0A” ($10A is the sector after the directory entry at $109).

    Just to make sure you have the correct starting sector, in dEd you can skip to that sector (“s 10a [ENTER]”) to look at it and see if it is the kernel. On the top line of the ASCII display on the right you should see the module name embedded in there. In this case, “KrnP2”. That confirms sector $10A is indeed the kernel.

    From the NitrOS-9 Technical Reference manual “Identification Sector (LSN 0)” on page 57:

    Name    Rel.  Size  Use
            Addr  (Bytes)
    DD.TOT  $00   3     Number of sectors on disk
    DD.TKS  $03   1     Track size (in sectors)
    DD.MAP  $04   2     Number of bytes in the allocation bit map
    DD.BIT  $06   2     Number of sectors per cluster
    DD.DIR  $08   3     Starting sector of the root directory
    DD.OWN  $0B   2     Owner’s user number
    DD.ATT  $0D   1     Disk attributes
    DD.DSK  $0E   2     Disk identification (for internal use)
    DD.FMT  $10   1     Disk format, density, number of sides
    DD.SPT  $11   2     Number of sectors per track
    DD.RES  $13   2     Reserved for future use
    DD.BT   $15   3     Starting sector of the bootstrap file
    DD.BSZ  $18   2     Size of the bootstrap file (in bytes)
    DD.DAT  $1A   5     Time of creation (Y:M:D:H:M)
    DD.NAM  $1F   32    Volume name in which the last character has the most significant bit set
    DD.OPT  $3F         Path descriptor options

    We will want to put the starting sector (that we got from dEd) as three bytes at offset $15 of LSN 0. We will want to put the byte count (that we got from dir) as two bytes at offset $18 of LSN0.

    Now just skip back to LSN 0 and type in the starting sector for the OS9Boot module and it’s size. These go at offset $15-$17 (starting sector) and $18-19 (size in bytes). Basically, you want to edit $15-$19 to be the three bytes that were at $10-$12 in the files’ ID sector, and the two byte size (from dir). In my case, I put in “00 01 0A FE DD” to match the start of my boot file ($00010A) and it’s file size ($FEDD).

    s 0 [ENTER]  (skip to Logical Sector 0)
    e (to enter edit mode)
    Cursor over to row 10, column 5. Change three bytes to the start LSN:
    00 01 0A (for me)
    Cursor over to row 10, column 8. Change two bytes to the os9boot size:
    5E DD (for me)
    [ENTER] to exit edit mode
    CMD: w (to write sector)
    Are you sure? y (yes, you are sure)

    Now the kernel track is where the “DOS” command will find it, and its sectors are marked as used to other files will not overwrite it.

    OS9Boot has been copied over (and must be contiguous) and LSN0 has been updated to point to where the file starts and how big it is.

    Step 6 – The only thing left to do is copy over the other needed files, which at a minimum should be “shell”, “grfdrv” and “sysgo”:

    makdir /sd1/CMDS
    copy /sd0/CMDS/shell /sd1/CMDS/shell
    copy /sd0/CMDS/grfdrv /sd1/CMDS/grfdrv
    copy /sd0/sysgo /sd1/sysgo

    At this point, you now have a minimally bootable OS-9 hard drive (though it has no commands or anything useful on it yet). You might want to also include utilspak1 (common commands) and the base startup file (which will load them):

    copy /sd0/CMDS/utilpak1 /sd1/CMDS/utilpak1
    copy /sd0/startup /sd1/startup

    I hope this walkthrough demystifies the OS-9 booting process. In a future article, maybe I can present code in BASIC09, C or assembly (or maybe all three versions) that does all of this for you.

    2016/5/1: You can download a 128MB disk image here that is the results of me performing this steps tonight.

    Until then … tips are always welcome :)

    Manually making a bootable NitrOS9 hard drive image – part 2

    See also: part 1, part 2 and part 3.


    • 2016/05/02 – Added link to David Ladd’s experiment.

    In the first installment, I discussed a bit about how the Radio Shack Color Computer boots OS-9 using the Disk BASIC “DOS” command. I ended the article by mentioning David Ladd’s exciting experiment to place the OS-9 boot track in ROM on a CoCoSDC interface. The advantages of this would be:

    1. No need to write out the kernel boot track to a boot floppy (or virtual floppy).
    2. A whole extra track of disk space on any boot disk.
    3. Faster booting, since copying from ROM would be faster than loading the 18 boot sectors from a floppy drive.

    Number 2 is not a huge deal on a hard drive since 4.5K isn’t much space. Neither is number 3 since reading 18 sectors from a virtual floppy on the CoCoSDC is blazing fast. I can already do a complete OS-9 boot to a shell prompt in about 3 seconds. But, faster is faster. It’s number 1 I want to focus on.

    The Problem With Cobbler

    The OS-9 utilities cobbler and os9gen were written to work on floppy disks. historically, that’s all anyone has ever used them on — even if the floppy was a virtual one contained on an RGB-DOS/HDB-DOS hard drive partition, or .DSK image file across Drivewire.

    CoCoSDC allows you to create .DSK image files and mount them as if they are a floppy disk. The CoCoSDC decides what to do with them based on the size of the .DSK file. See the “Disk Geometry Table for DSK Images (without header)” table on the CoCoSDC blog. Basically, any .DSK file with more than 2880 sectors (as many as an 80 track quad density floppy could have) will be treated as a hard drive image.

    I’m not quite sure what this implies, since if you mount such an image, Disk BASIC will still see and use the first part of it as a 35-track single sided floppy disk*. To Disk BASIC, all it knows it Tracks 0-34 each contain Sectors 1-8 and each sector is 256-bytes. If you mount such a large .DSK image and then type “DOS”, Disk BASIC will go out to Track 34, Sector 1 and start loading things in to memory at $2600, same as if it was a real floppy disk.

    * Is this true? It seems to be. If it’s not, what I am about to describe shouldn’t be working.

    Track 34, Sector 1 is sector number 612 (34 tracks * 18 sectors per track = 612). As long as a kernel boot track is found there, you should be able to attach a 128MB .DSK image, type “DOS” and boot in to OS-9 (assuming the boot track has the proper OS-9 booter on it for the CoCoSDC hardware, and there is a OS9Boot file properly set up, too).

    This is exactly how the NitrOS9 CoCoSDC sample .dsk image works. Mount it, type “DOS”, and in seconds you are at a NitrOS9 shell prompt. The NitrOS9 makefiles create the .dsk image using the Toolshed tool “os9”. Toolshed supports formatting a .DSK image for OS-9, os9gen-ing a bootfile on to it, and dsave-ing files and directories over to it. You end up with a large bootable .DSK file that is formatted for OS-9, has a “track 34” boot track, and the OS9Boot file linked in at sector 0. Magic.

    You would think you could do the same thing via OS-9, but you would be wrong. os9gen and cobbler will not work because they were never written for anything but a physical floppy drive. In a moment, I will explain why this may be an incorrect statement.

    If you mounted an OS-9 boot .dsk image in DRIVE 0, and a formatted 128MB OS-9 hard drive .dsk image in DRIVE 1:

    DRIVE 1,"128MBHD.DSK"

    …and then you boot in to OS-9 and try to “cobbler /sd1”, bad things happen. cobbler and os9gen will try to place the kernel boot track at track 34, sector 1. If this was a physical floppy interface, seeking to Track 34 and Sector 1 would work, but to OS-9, there is no such thing as physical tracks or sides. Every disk device is just a bunch of logical sectors, and it’s the device drivers job to translate whatever the hardware has to a series of logical sectors. The cobbler and os9gen utilities use something called “math” to figure out what logical sector corresponds to Track 34, Sector 1. It does this with a simple forumla:

    logical_sector = 34 * 1 * sectors_per_track * sides (see side note)

    Side Note: Sides is used because on a double sided floppy, tracks are interleaved between the two sides of the disk. On a single sided 40-track floppy, there are 720 sectors which make up the top side of the disk. On a double sided 40-track floppy, there are 1440 sectors. The first track’s worth of sectors (sectors 0-17) is written to the first track of the top side, then the next track’s worth (sectors 18-35) is written to the first track of the bottom side of the disk. The job of an OS-9 disk driver is to translate the logical sectors OS-9 uses to whatever format the hardware uses. In the case of floppy disks, it turns 1440 logical sectors of a double sided 40-track disk in to two sides of a physical floppy. On modern hard drives, the drive controller speaks sectors, so the only thing the OS-9 driver has to do is deal with the 512-sector size issue on modern drives, but that’s a topic for another series of articles.

    If the hard drive is configured with a different number of sectors per track than the 18 used by a floppy disk, the math will be wrong. cobbler/os9gen will multiply the drive’s sct (sectors per track) setting by 18 (hard coded assumption) and either 1 or 2 sides (see note below) and try to write the kernel track at that location. The end result is a file being written in the wrong place on the .DSK image than where the “DOS” command expects it to be.

    Side Note 2: For sides, cobbler and os9gen aren’t using the actual sides field — they are using a bit in the DD.TYP field that indicates if the device is single or double sided. For a proper OS-9 hard drive descriptor, the hard drive bit is set and the sides bit is clear, so cobbler and os9gen should see a hard drive as a huge single sided floppy disk.)

    But wait! It gets worse…

    While OS-9/6809 can theoretically support a 4GB hard drive, it could only do so by using a large cluster size (having multiple sectors representing one cluster). For me, I am using the largest size possible when each cluster represents one sector. Below, when I mention “cluster” or “sector”, they effectively mean the same thing for me since I am using a cluster size of one sector. Get it? Good.

    On my system, in order to get the largest 1 sector cluster hard drive possible (128MB, see note below), I configure my hard drive descriptor to be 65,535 tracks (cyl=$ffff), 8 sides (sid=$8) and 1 sector per track (sct=$1). This (65535 * 8 * 1) gives me 524,280 sectors, which is as large as we can get.

    As part of the file system, a series of bits is used to represent which clusters are used or are free. This is called the DAM (disk allocation map) and it serves the same purpose as the FAT table does on a PC. The largest the DAM can be is 65,535 ($FFFF) bytes and since each byte represents 8 clusters. The more clusters, the larger the DAM must be.

    DAM Note: Since there are only $FFFF (65535) bytes in the DAM table, with each byte representing eight clusters, the largest amount of  clusters OS-9/6809 can handle is 524280 (65535 * 8). 524280 * 256 bytes per sector is 134,215,680 which is just shy of 128MB (using 1024 bytes of a K). If only we had one more byte in the FAT, then we could fully use the 128MB. By using a larger cluster size, where each DAM bit represented 2, 4, 8, or 16 sectors, the total size of the hard drive can as much as 4GB. The 4GB limit is because OS-9 can only access up to 16,777,215 ($FFFFFF) logical sectors.

    Sector Note: If you are clever, you might be thinking “oh, that’s with a 256-byte sector drive, so on an IDE drive where every sector is 512-bytes, we should be able to access 8GB!”. Very clever, but that would only be the case if OS-9 was not using deblocking drivers that split each physical 512-byte sector in to two logical 256-byte sectors. The max sector value that OS-9 can read is $FFFFFF 256-byte logical sectors. If those just happen to be half of each 512-byte sector on an IDE drive, then sure, it’s accessing an 8GB drive, but wasting half of each sector since OS-9 still only sees it as $FFFFFF 256-byte sectors. Now stop being clever so I can finish this article.

    Where was I? Oh, right. Trying to use the largest hard drive I can…

    If I ran cobbler or os9gen on this 128MB drive, it would multiple the number of tracks (cyl=$ffff) by 34 and then try to write the kernel boot track starting at sector 2,228,190. DOS will be looking for it at sector 612, so this clearly won’t work.

    Theoretically, if I had made my hard drive use 29,126 tracks (cyl=$0x71C6), 18 sectors per track (sct=$12), and one side (sid=$1) like a simple floppy disk, I might be able to get this to work. cobbler and os9gen would do the math (track 34 * 18 sectors per track) and end up at sector 612 like it is supposed to and all would be well in the world. Except it isn’t.

    First, that only gives a hard drive size of 524,268 sectors, which is 12 sectors shy of our max. I wouldn’t sleep well at night knowing I could be using 12 more sectors just by using more optimum settings. But that’s not the real issue. The real issue is that cobbler and os9gen were never written to work on hard drives. Taking a peek inside the cobbler source code, I find this:

     * Request memory for the FAT buffer + 256 bytes for stack space R.G.
     ldd <DD.MAP
     addd #size+256
     os9 F$Mem

    First, the D register is loaded with the DD.MAP field from logical sector 0. That field holds the size of the DAM bitmap which, on a 128MB hard drive image, is $FFFF.

    Next, it adds 256 to this value which, on a 16-bit register, rolls over and D ends up being 255.

    Finally, it allocates memory which is will use for stuff. Instead of getting $FFFF+256 bytes, it’s really only getting 256 bytes and “bad things can happen.” This is a bug. Cobbler was not written to be used on a disk with that many clusters.

    ERROR #244

    Maybe that is why cobbler exits with an ERROR #244 when you try it on a hard drive configured that way. At least it does on mine.

    As-written, cobbler and os9gen will fail here. They need to be updated to handle things differently, or at the very least, exit with an error if the drive is too large. And honestly, the easiest fix might be to do it like the Toolshed os9 utility does and just seek to sector 612 in the file (or 1224 in the case of a double sided disk). That’s really the only math we need for the boot track.

    Up next: Finally, the original promise of this article… How to manually make a NitrOS9 hard drive bootable using only a disk editor, the copy command, and some duct tape.