FLEX - nealcrook/multicomp6809 GitHub Wiki
This page describes how to get FLEX working on Multicomp6809. It assumes that:
- 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 the mk2 memory mapping unit (though strictly speaking this is not needed for running FLEX nor is it necessary to use it to disable the boot ROM)
If any of these assumptions are false, you should follow porting FLEX from first principles instead.
If you want to play along but without hardware you can run FLEX on exec09
The system disk image multicomp09_flex.dsk in the repository should work with no modification. You need to create an SDcard image and transfer it to an SDcard, using the instructions in creating an SDcard for FLEX.
Slot the SDcard into your multicomp and power-up. You should get the CamelForth start-up banner. Type FLEX and press . The screen should look like this:
6809 CamelForth v1.0 25 Apr 95
FLEX FLEX......................
FLEX 9.0
DATE (MM,DD,YY)?
The only thing that you typed was the first "FLEX". Even though you pressed , the computer did not echo it.
You should be able to enter a date, press and get to the FLEX prompt ("+++"). Now read FLEX hints and kinks to get the terminal settings correct for the VDU.
If things didn't go so smoothly, here are some tips to inspect the system and fault-find the problem. Even if it did all work, you might want to read on just to learn about the FLEX boot process.
Use flex_disk_manip to identify the location of the system files on your disk image:
$ flex_disk_manip multicomp09_flex.dsk -info -dir
Locate these two lines:
FLEX.COR t37,s65 - t38,s14 ( 22 sectors) 06-27-97
FLEX.SYS t39,s32 - t39,s55 ( 24 sectors) 05-31-79
This tells us that FLEX.COR is 22 sectors in size and starts at track 37, sector 65 and that FLEX.SYS is 24 sectors in size and starts at track 39, sector 55. Keep a note of those numbers as we will be checking them later (the latest version of the image may have different track/sector values for these files).
When you issue the command FLEX from CamelForth, it loads the boot sector from the FLEX system disk (which is part of your SDcard image) into memory, and jumps to it. The boot sector is the first 256 bytes of the first block of the system disk image. It is loaded to memory at address $C800 and then FORTH branches to $C800 and never comes back. The source code for this is in multicomp09_flex_loader.asm.
The first thing that the boot sector code does is to print the word FLEX. Therefore, if you see this output, you can be certain that the FLEX system disk image at least //starts// at the right place on the SDcard and that the SDcard interface is working well enough to allow a read.
Encoded into a data area in the boot sector code is a link: a track/sector value identifying the start sector for the file FLEX.SYS, which contains the whole OS. This is a clever shortcut that saves the boot sector code from having to deal with the complexity of reading the directory on the disk. In every 256-byte sector, the first two bytes hold a link (track/sector value) for the next sector. Both bytes are 0 for the last sector.
That link (2 bytes in the boot sector) was initialised from within FLEX by issuing the LINK command. The LINK command looks up (in the disk's directory) the file FLEX.SYS and find it's start track/sector, and then patches those values into the boot sector. This is a one-time operation that you need to perform each time you create a new system disk. Also, if you re-generate your FLEX.SYS you must run LINK again otherwise the next time you boot the disk it will attempt to load from the first sector of the old* FLEX.SYS (which will probably be part of the list of deleted sectors!).
When the code in the boot sector executes, it reads sectors in turn, following the links in turn until it reaches the end (0,0). First, a sector is read into a 256-byte buffer starting at address $C300. Then a dot (.) is printed to show progress, then the buffer is parsed (binary files are made up of multiple records that can contain address, data and execution information) and data is copied from the buffer into memory.
Earlier, we inspected FLEX.SYS and saw how many sectors it occupied. When it is loaded, you should see one dot printed for each sector of the image -- 24 for the example shown above. If you see the wrong number that suggests the load process has gone wrong. Perhaps your disk image is corrupt or has not been prepared correctly.
If you get the correct number but FLEX does not start, that could also be caused by image corruption.
Now we will follow the boot process in detail. Here is the FORTH definition of FLEX:
: FLEX \ 512 bytes (256 used) from SD at 0x2.2000
MMUMAP
2 SDLBA2 2000 C100 1 SDRDn 0 SDLBA2
C100 PIVOT ; ( entry point of loader)
We can execute it step by step from within CamelForth. Remember, this FORTH is case-sensitive. If you make a mistake you almost certainly can just retype that particular line, no need to reset and start again.
\\ this is a comment that you do not need to type
HEX MMUMAP \\ set up the paging unit
2 SDLBA2 \\ high byte of the SDcard block address
2000 C100 1 SDRDn \\ load 1 block from sdcard at block 02.2000 to memory at C100
That read the boot sector off the disk image and into memory. Let's take a look:
C100 200 DUMP \\ dump 512 ($200) bytes starting at address $c100
C100 20 0A 02 20 00 27 20 00 C1 00 00 00 10 CE C0 7F .. .'9.........
C110 86 46 8D 4D 86 4C 8D 49 86 45 8D 45 86 58 8D 41 .F.M.L.I.E.E.X.A
C120 FC C1 05 FD C3 00 10 8E C4 00 8D 44 81 02 27 10 ...........D..'.
C130 81 16 26 F6 8D 3A B7 C1 08 8D 35 B7 C1 09 20 EA ..&..:....5... .
C140 8D 2E B7 C1 0A 8D 29 B7 C1 0B 8D 24 1F 89 4D 27 ......)....$..M'
C150 D9 BE C1 0A 34 14 8D 18 35 14 A7 80 5A 26 F5 20 ....4...5...Z&.
C160 C9 34 04 F6 FF D0 C5 02 27 F9 B7 FF D1 35 04 39 .4......'....5.9
C170 10 8C C4 00 26 0F 8E C3 00 EC 84 27 0B 8D 0D 26 ....&......'...&
C180 8B 10 8E C3 04 A6 A0 39 6E 9F C1 08 C0 01 FB C1 .......9n.......
C190 04 E7 80 C6 00 F9 C1 03 E7 80 C6 00 F9 C1 02 E7 ................
C1A0 84 30 1E C6 48 3D EB 80 F7 FF DA A9 80 B7 FF DB .0..H=..........
C1B0 86 00 A9 84 B7 FF DC 30 1E 4F B7 FF D9 5F B6 FF .......0.O..._..
C1C0 D9 81 E0 26 F9 B6 FF D8 A7 80 5A 26 F1 5F B6 FF ...&......Z&._..
C1D0 D9 81 E0 26 F9 B6 FF D8 5A 26 F3 86 2E 8D 82 4F ...&....Z&.....O
C1E0 39 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 9...............
C1F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
C200 20 0A 02 20 00 27 39 00 C1 00 00 00 10 CE C0 7F .. .'9.........
C210 86 46 8D 4D 86 4C 8D 49 86 45 8D 45 86 58 8D 41 .F.M.L.I.E.E.X.A
C220 FC C1 05 FD C3 00 10 8E C4 00 8D 44 81 02 27 10 ...........D..'.
C230 81 16 26 F6 8D 3A B7 C1 08 8D 35 B7 C1 09 20 EA ..&..:....5... .
C240 8D 2E B7 C1 0A 8D 29 B7 C1 0B 8D 24 1F 89 4D 27 ......)....$..M'
C250 D9 BE C1 0A 34 14 8D 18 35 14 A7 80 5A 26 F5 20 ....4...5...Z&.
C260 C9 34 04 F6 FF D0 C5 02 27 F9 B7 FF D1 35 04 39 .4......'....5.9
C270 10 8C C4 00 26 0F 8E C3 00 EC 84 27 0B 8D 0D 26 ....&......'...&
C280 8B 10 8E C3 04 A6 A0 39 6E 9F C1 08 C0 01 FB C1 .......9n.......
C290 04 E7 80 C6 00 F9 C1 03 E7 80 C6 00 F9 C1 02 E7 ................
C2A0 84 30 1E C6 48 3D EB 80 F7 FF DA A9 80 B7 FF DB .0..H=..........
C2B0 86 00 A9 84 B7 FF DC 30 1E 4F B7 FF D9 5F B6 FF .......0.O..._..
C2C0 D9 81 E0 26 F9 B6 FF D8 A7 80 5A 26 F1 5F B6 FF ...&......Z&._..
C2D0 D9 81 E0 26 F9 B6 FF D8 5A 26 F3 86 2E 8D 82 4F ...&....Z&.....O
C2E0 39 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 9...............
C2F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
Observe:
- The 256 bytes of data at $C200 is a repeat of the 256 bytes of data at $C100). The reason for this is that FLEX sectors are 256 bytes but SDcard blocks are 512 bytes. The easiest thing to do was to waste half of each block. In fact, the flex_disk_manip program, and the FLEX device driver, saves the same data twice on a write, and reads the first copy on a read (I had some vague idea I could use this later for a data integrity check or error recovery or something).
- This is 6809 executable code. You can see where the letters F L E X are coded (this code was generated from multicomp09_flex_loader.asm).
- The first 2 bytes are a BRA and the next 3 are the block address on the SDCARD where this disk image starts (which we already know was $02.2000) and the next 2 are the track/sector address where FLEX.SYS lives. The values shown, $27 $20 are 39 32 in decimal -- which matches the values we extracted earlier.
- If you don't see data like this (for example, you don't see the letters F L E X) you have not transferred the multicomp09_flex.dsk file to the SDcard correctly.
- If you see F L E X but don't see the data duplicated, you failed to run flex_disk_manip on the multicomp09_flex.dsk file before transferring it to the SDcard.
- If the track, sector values match the values for FLEX.COR instead of FLEX.SYS, the LINK command has not been run on the disk image (in which case you will also have seen the wrong number of dots printed during boot). If this is the case, you need to read porting FLEX from first principles and follow the section "The final steps".
Take a look a few blocks on, where the directory starts:
2004 1000 1 SDRDn \\ load 1 block from SDcard at block 02.2004 to memory at 1000
1000 200 DUMP \\ and dump it
1000 00 06 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
1010 46 4C 45 58 00 00 00 00 43 4F 52 00 00 25 41 26 FLEX....COR..%A&
1020 0E 00 16 00 00 06 1B 61 53 44 00 00 00 00 00 00 .......aSD......
1030 42 49 4E 00 00 27 1E 27 1E 00 01 00 00 05 1F 4F BIN..'.'.......O
1040 43 4F 4E 53 00 00 00 00 42 49 4E 00 00 27 1F 27 CONS....BIN..'.'
1050 1F 00 01 00 00 05 1F 4F 57 49 4E 44 52 56 00 00 .......OWINDRV..
1060 43 4D 44 00 00 01 1F 01 20 00 02 00 00 06 1B 61 CMD..... ......a
1070 41 53 4E 00 00 00 00 00 43 4D 44 00 00 01 21 01 ASN.....CMD...!.
1080 21 00 01 00 00 06 1B 61 54 49 4D 45 52 4F 4E 00 !......aTIMERON.
1090 43 4D 44 00 00 01 22 01 22 00 01 00 00 06 1B 61 CMD..."."......a
10A0 54 54 59 53 45 54 00 00 43 4D 44 00 00 01 23 01 TTYSET..CMD...#.
10B0 24 00 02 00 00 06 1B 61 44 41 54 45 00 00 00 00 $......aDATE....
10C0 43 4D 44 00 00 01 25 01 26 00 02 00 00 06 1B 61 CMD...%.&......a
10D0 45 52 52 4F 52 53 00 00 53 59 53 00 00 01 27 01 ERRORS..SYS...'.
10E0 47 00 21 02 00 06 1B 61 54 49 4D 45 00 00 00 00 G.!....aTIME....
10F0 43 4D 44 00 00 01 48 02 01 00 02 00 00 06 1B 61 CMD...H........a
1100 00 06 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
1110 46 4C 45 58 00 00 00 00 43 4F 52 00 00 25 41 26 FLEX....COR..%A&
1120 0E 00 16 00 00 06 1B 61 53 44 00 00 00 00 00 00 .......aSD......
1130 42 49 4E 00 00 27 1E 27 1E 00 01 00 00 05 1F 4F BIN..'.'.......O
1140 43 4F 4E 53 00 00 00 00 42 49 4E 00 00 27 1F 27 CONS....BIN..'.'
1150 1F 00 01 00 00 05 1F 4F 57 49 4E 44 52 56 00 00 .......OWINDRV..
1160 43 4D 44 00 00 01 1F 01 20 00 02 00 00 06 1B 61 CMD..... ......a
1170 41 53 4E 00 00 00 00 00 43 4D 44 00 00 01 21 01 ASN.....CMD...!.
1180 21 00 01 00 00 06 1B 61 54 49 4D 45 52 4F 4E 00 !......aTIMERON.
1190 43 4D 44 00 00 01 22 01 22 00 01 00 00 06 1B 61 CMD..."."......a
11A0 54 54 59 53 45 54 00 00 43 4D 44 00 00 01 23 01 TTYSET..CMD...#.
11B0 24 00 02 00 00 06 1B 61 44 41 54 45 00 00 00 00 $......aDATE....
11C0 43 4D 44 00 00 01 25 01 26 00 02 00 00 06 1B 61 CMD...%.&......a
11D0 45 52 52 4F 52 53 00 00 53 59 53 00 00 01 27 01 ERRORS..SYS...'.
11E0 47 00 21 02 00 06 1B 61 54 49 4D 45 00 00 00 00 G.!....aTIME....
11F0 43 4D 44 00 00 01 48 02 01 00 02 00 00 06 1B 61 CMD...H........a
Observe:
- You should see some file names in the ASCII dump at the right.
- Everything is duplicated as before.
If all that looks good it should be possible to execute the loader that is still in memory at $C100:
C100 PIVOT \\ pivot goes there via a bit of code in RAM that disables the ROM
You should see:
FLEX........................
FLEX 9.0
DATE (MM,DD,YY)?
Back to software overview.