porting FLEX from first principles - nealcrook/multicomp6809 GitHub Wiki
I decided to port FLEX using the original porting guide provided by the manufacturer. You can use this as a guide to porting FLEX to your own hardware, or you can just follow along for fun with hardware that is exactly the same as mine. If you follow along without making any modifications to the code, the assumption is that your hardware is like this:
- You are using CamelForth as your boot ROM
- You have at least 64Kbytes of RAM (ie, external RAM)
- You have a VGA VDU, PS/2 keyboard and SDcard
- You have my mk2 memory mapping unit - though strictly speaking, none of its capabilities are needed
If your system does match mine, you might want to try creating an SDcard for FLEX before trying the steps here.
If you want to play along but without hardware you can run FLEX on exec09
- FLEX Adaption guide. You can find this at several places on the web, including the FLEX user group, or as part of the FLEX emulator bundle at http://www.evenson-consulting.com/swtpc/
- as9 assembler. Get it from http://home.hccnet.nl/a.w.m.van.der.horst/m6809.html
- f9dasm disassembler. Get it from http://www.hermannseib.com/english/opensource.htm or get an enhanced version from https://github.com/gordonjcp/f9dasm
- a checkout of this github repository
To perform the port there are 4 distinct chunks of code that need to be written. The versions here can be used exactly as-is or modified to suit your requirements.
Review the I/O and SD-card device drivers in the files multicomp09_flex_io.asm and multicomp09_flex_sd.asm respectively. Assemble them and generate a binary for each (see building code). In the process of investigating a bug in the SD-card drivers I discovered a bug in the Adaption Guide: it states that the DRIVE subroutine need not preserve X. That is not true! Examination of the FLEX source code shows that X must be preserved by this routine.
The Adaption Guide has sample code for a bootstrap tool named QLOAD. The source code of the multicomp port is in multicomp09_flex_qload.asm. Review it and make any changes, then assemble it and generate a binary.
The Adaption Guide describes a 2-stage boot process. The first stage is ROM-resident. For multicomp we will use low-level commands in CamelForth to perform all the actions of the first stage.
The second stage is resident in the first sector of the disk image. Again, the Adaption Guide has sample code for this and the source code of the multicomp port is in multicomp_flex_loader.asm. Review it and make any changes, then assemble it and generate a binary. This code needs to fit into 256 bytes (if your version does not, review the advice in the Adaption Guide and make appropriate changes to the instructions that follow).
The Adaption Guide places a lot of emphasis on the creation of a utility named NEWDISK, the purpose of which is to format and create FLEX-related data structures on a new floppy. For multicomp this utility is not needed: it's possible to create an empty disk by cloning an existing disk and then deleting all the files on it. Alternatively, you can use the flex_vfs script described here.
The loader needs to be inserted at the track=0 sector=1 position of the system disk image. The system disk image and the other binaries need to be put into an image that can be transferred to an SD card.
Start with the disk image multicomp09_flex.dsk from the repository.
The bootstrap loader binary is exactly 256 bytes (I padded it with 00 bytes to keep it tidy). It needs to go in the first 256 bytes of the disk image:
$ dd if=multicomp09_flex_loader.bin of=multicomp09_flex.dsk conv=notrunc
Use the PERL script flex_disk_manip to identify the location of FLEX.COR on the system disk image like this:
flex_disk_manip multicomp09_flex.dsk -info -dir
Locate the line that describes FLEX.COR:
FLEX.COR t37,s65 - t38,s14 ( 22 sectors) 06-27-97
Alternatively, use the PERL script flex_vfs like this:
$ flex_vfs
flex_vfs: mount 0 ../../multicomp09_flex.dsk
flex_vfs: dir 0.FLEX.COR
NAME ATTR START END SIZE DATE
FLEX.COR t37,s65 - t38,s14 22 sectors 06-27-97
flex_vfs: exit
$
Whichever method you use, the result is the same: we see the the file FLEX.COR starts at track 37, sector 65. Check multicomp09_qload.asm to ensure that the start track/sector values defined at the start of that file match the location of FLEX.COR in the system disk image.
Follow the instructions for creating an SDcard for FLEX, using the modified multicomp09_flex.dsk image and the binaries for the drivers and for qload.
With the SDcard loaded up with the binaries of the drivers and of qload and an image of the system disk, the final sequence is straightforward. First, boot FORTH and load the device drivers and qload image in to memory. Each of them is less than one sector in size. The text in braces is comments and need not be typed:
HEX ( ALL NUMBERS ARE IN HEX.)
2 SDLBA2 ( ALL IMAGES ARE AT BLOCK ADDRESSES 20.XXXX ON THE SD CARD)
1800 C100 SDRD ( LOAD QLOAD INTO MEMORY AT C100)
1A00 D370 SDRD ( LOAD IO DRIVERS INTO MEMORY AT D370)
1C00 DE00 SDRD ( LOAD SD DRIVERS INTO MEMORY AT DE00)
When the QLOAD image is started it should load the binary image FLEX.COR from the FLEX system disk and start it. That image has no device drivers and requires them to already be in memory at the correct place, which they are. Next, start the QLOAD image:
C100 EXECUTE
You should be greeted by the FLEX start-up message and a request to set the date. Once you have done that, you should be at the FLEX prompt, "+++". There are a couple of problems:
- The backspace key doesn't echo on the screen
- Each line is indented by 4 characters.
We'll fix both of those in a moment. First, we will create a system image by performing the following instructions from the Adaption Guide:
- Save the device drivers to memory.
- Append the drivers to FLEX.COR to create FLEX.SYS
- Patch the primary boot loader with the location on disk of FLEX.SYS
Here we go:
+++ SAVE SD,DE00,DEF2
+++ SAVE CONS,D370,D3FC,CDOO
+++ APPEND FLEX.COR,SD.BIN,CONS.BIN,FLEX.SYS
+++ LINK FLEX.SYS
The third argument to each SAVE command is the end address of the driver. You can find this by inspecting the listing files multicomp09_flex_sd.lst and multicomp09_io.lst respectively. The fourth argument to the second SAVE is the entry address for the final image file. This is always CD00 (the entry point for FLEX). Don't omit it!!
Next we will used FIX to patch the FLEX.SYS file to fix the backspace and indent problem (the details are described here). Finally, we need to LINK the patched image:
+++FIX FLEX.SYS <return>
M: CC05 00 <return>
M: CC07 08 <return>
E <return>
+++LINK FLEX.SYS <return>
- You need to type both digits of the data values (00 and 08) - if you simply type 0 and 8 the values get ignored.
- If you omit the LINK step, you will end up booting your system from the deleted sectors of the old FLEX.SYS - in case it's not obvious, that would be bad (and I mean bad in a bad way!)
That's it! Reboot the system (which will return you to CamelForth). To start FLEX we need to load the primary boot loader from the disk and execute it. We can do that directly from CamelForth using the command FLEX:
FLEX
The screen should look like this (the first FLEX is what you typed, the second is printed by the primary boot loader):
FLEX FLEX......................
FLEX 9.0
DATE (MM,DD,YY)?
The command to start FLEX from CamelForth is coded in FORTH and looks like this:
: FLEX \ 512 bytes (256 used) from SD at 0x2.2000
MMUMAP
2 SDLBA2 2000 C100 SDRD 0 SDLBA2
C100 PIVOT ; ( entry point of loader)
If something went wrong, re-read the instructions carefully to see if you missed a step. Also, check the debugging notes here
If you have included Grant's BASIC ROM image in your SDcard image you can start it up from CamelForth by typing BASIC. Likewise, you can type CUBIX or NITROS9 or BUGGY to load and start up those images from the SDcard.