Yearly Archives: 2018

QL-SD demo update

Prompted by a customer request I have extended my QL-SD demo file with a few free QL games, 20 in total, including some that were never available for free before but for which I have the rights to release (basically the Jochen Merz catalog, thanks Jochen!).

I went to great length to try to make it as easy as possible, usually you can just select a game in the boot screen and it will run, everything is pre-configured. Even (Super)GoldCards are slowed down when necessary, still not every game will run properly on every QL configuration. The most compatible configuration is probably a QL with expanden memory but without any GoldCard. 

Microdrive mystery

Martyn Hill, while testing his brand new Tetroid SuperGoldCard clone, has discovered a strange bug where his QL crashed when he was loading a _scr file into the QL’s screen memory. It works fine without the SuperGoldCard. A lot of theories were put forward, like:

  • It’s a problem with the SuperGoldCard: turns out it works fine when QDOS or a very early Minerva version is used instead
  • It’s connected to the memory timing of the screen area: turns out is also happens in fast memory
  • It’s connected to the 68020 processor: turns out is also happens on the 68000 processor
  • The SuperGoldCard patches are wrong: I’ve analyzed all the patches and they all look fine. In fact the patch code is identical to Minerva’s code except for the timing loops. Still, it appeared to work with earlier versions of the patches, which makes it weird again.

Personally I couldn’t care less if Microdrives work or not and the fact that this bug was not discovered for so long strongly implies that most other people also don’t use Microdrives with SGC systems anymore. Still I have trouble resisting a good puzzle so I had a look. And then another one. And then ten more because this was a very elusive bug.

The problem is that not only is the bug located in ROM locations that are hard to debug anyway, the MDV code is so time critical that it’s impossible to step through the code. So how can one debug this? Hardware to the rescue! The SuperGoldCard very conveniently has a parallel port on board that can be accessed very simply by the software. By connecting a logic analyzer to all 8 data lines and sprinkling output commandos throughout the MDV code I can get a live trace of what the code is doing or output the contents of registers byte-by-byte.

In hindsight I should have found the problem much earlier because of the symptoms, but that’s easy to say after you know what’s going wrong. Let’s make a little quiz, here’s the code part with the problem and you can try to spot the bug:

        move.w  #blksize,d0     full block normally (512)
        cmp.b   lstblok(a0),d7  is it the last file block?
        bne.s   not_last        no - copy to end of it
        move.w  lstbyte(a0),d0  get the number of bytes in last block
        lsl.w   #blkbits-1,d7
        add.l   d7,d7           is it the first file block?
        lea     -md_deend(a1,d7.l),a5 where to put data normally
        bne.s   not_frst
        moveq   #md_deend,d1    yes - move on past the file header
        add.l   d1,a4
        add.l   d1,a5
        sub.w   d1,d0           copy fewer bytes
        ror.l   #2,d0           long words, and save odd byte count
        bcc.s   unbf_dbr        carry means there is an odd word to do
        move.w  (a4)+,(a5)+     if so, do it
        bra.s   unbf_dbr
        move.l  (a4)+,(a5)+     move a long word
        dbra    d0,unbf_lop
        add.l   d0,d0           see if there's an odd byte to go
        bpl.s   notabyte
        move.b  (a4)+,(a5)+     if so, do it

Keep in mind that the code is not generally broken, it sometimes works! The problem also appears for the first block, so you can pretty much ignore the special handling of the last block. Found it? I’ll wait…






The “ror.l #2,d0” is a pretty clever way to both divide the register by 4 (because the copy loop does long words) while still remembering the odd bytes that also need to be copied. But it relies on one thing: that bits 16 and 17 of the register are zero. These bits are shifted into the lower 16-bits and are then used by the dbra instruction, which means that if they are set instead of copying 128 long words it will copy at least 16384. Talk about a buffer overflow!

You should now also see why it sometimes works. Remember earlier that I wrote “In fact the [MDV] patch code is identical to Minerva’s code except for the timing loops.”. The timing code in the original Minerva ROM is hidden behind a macro but in the end looks like this:

; For delays 5 to 19µs
        moveq #([us]*15-38)/4,d0        four byte sequence
        ror.l  d0,d0 

; For delays 21 to 309µs
        moveq   #([us]*15-50)/36,d0     six byte sequence
        dbra    d0,*

; ... etc, other variants are similar

For the (S)GC this is exchanged by loops like this:

        move.w  gmt_fgap,d0              ; 2800 us
        dbra    d0,*

I guess everybody can see the difference now, the original code clears the upper word of D0 and the replacement code does not. And as it happens the upper word is $FFFF from an earlier call to md_slave. All in all a very subtle difference, hard to spot by just looking at the code.

The solution I chose is it to exchange the “move.w #blksize,d0” line with “move.l”. That adds two bytes (every byte is precious in Minerva, there are not many left!), but this is the minimum I can get away with without relying on side effects of outside code, which is how this bug was introduced in the first place.

As this is the second fix from me for Minerva 1.98 I will have to think about how to mark these modified Minerva versions as increasing the version number is a no-go unfortunately. 1.99 is the last number we can use in theory before running into extended compatibility problems and I’m not even sure about this, 1.98 is still a safer choice.

Anyway, I hope this was interesting to read, leave a comment if you want. I will soon release a fixed binary version.

(Super)GoldCard boot sequence

The last few days I’ve spent way too much time analyzing the (Super)GoldCard boot ROM. The sources supplied along with SMSQ/E are only sparsely commented disassembly that was basically impossible to read. It irked me to no end that I didn’t understand the code and finally I did something about it. The process had a strange fascination like putting together a 10000 piece puzzle

Anyway, let’s begin. The ROM consists of three parts:

$0000-$7FFFGOLDFLP + RAM + TK2
$8000-$BFFFPATCHPatches + Basic extensions + PAR + network + DEV
$C000-$FFFFBOOTBoot/patch engine


On the Gold Card the memory map on boot looks like this:

$0000-$BFFFQDOS (read), RAM (write)
$C000-$FFFFBOOT section of GC ROM
$18000-$1BFFFQL hardware registers
$1C000-$1C0FFGoldCard hardware registers
$20000-$3FFFF128kb RAM (including VRAM)
$40000-$4FFFFComplete GC ROM

QDOS boots normally, finds 128kb of RAM (because of the ROM) and executes the GC BOOT code at address $C000. This in turn initialises the hardware, copies and patches QDOS to RAM, copies parts of the GC ROM to RAM and finally issues another reset. This is why on the GoldCard the QL always boots two times.

Fun-fact: the GoldCard can boot without any firmware ROM, this makes it somewhat possible to inspect the above memory layout live.

 After boot the memory map looks like this:

$0000-$BFFFPatched QDOS in RAM, write protected
$C000-$FFFFROM port extension
GOLD section of the GC ROM
$18000-$1BFFFQL hardware registers
$1C000-$1C0FFGoldCard hardware registers
$1C100-$1C1FFGoldCard firmware variables
$1C200-$1FFFFPATCH section of GC ROM
$20000-$1FFFFF1920kb RAM (including VRAM)


On the SuperGoldCard the memory map on boot looks a bit differently:

$00000-$0FFFFSGC ROM (read), RAM (write)
$18000-$1BFFFQL hardware registers
$1C000-$1C0FFSuperGoldCard hardware registers
$20000-$3FFFF128kb RAM (including VRAM)
$40000-$4FFFFComplete SGC ROM (again)
$400000-$40FFFFQDOS ROM

In this case the SGC ROM doubles as the boot ROM and gets executed immediately. This is why the SGC does not need to double-boot. Again QDOS is copied and patched and parts of the SGC ROM are copied, too. Unlike with the GC, the copies of the SGC ROM are write protected.

$0000-$BFFFPatched QDOS in RAM, write protected
$C000-$FFFFROM port extension
GOLD section of the GC ROM, write protected
$18000-$1BFFFQL hardware registers
$1C000-$1C0FFSuperGoldCard hardware registers
$1C100-$1C1FFSuperGoldCard firmware variables
$1C200-$1FFFFPATCH section of SGC ROM, write protected
$20000-$27FFFVRAM1, writes are mirrored to QL hardware
$28000-$2FFFFVRAM2, writes are only mirrored if SCR2 is enabled
$400000-$40FFFFQDOS ROM
$4C0000-$4FFFFFExtended I/O area


The (Super)GoldCard does not have any kind of RAM that survives without power but still can store a bit of configuration like if F1 should be automatically pressed on boot. Well, how can this be? This was some mayor kind of “heureka” effect while analyzing the code. The cards contain a realtime clock chip that does not possess any additional RAM either, but it has a register that controls the interrupt line. The interrupt is never used on the golden cards, so the firmware just (ab-)uses the 4-bits available to store the configuration! Really clever.


The topic of what kind of patching the cards do on boot is almost mythical and was basically the reason I started this in the first place. All patches have been decoded and commented and everybody can look at them now (download below). There are a few patches that remove the most common bugs from the original QDOS ROM and a lot more that are applied to every ROM including Minerva. In some cases bugs in Minerva have been patched, but in these cases they have also been fixed in Minerva, so they usually don’t get applied anymore. One huge part is replacement of the MDV, network and I2C code, as these are all very timing critical.

Most remaining patches are exclusive to SGC because of the added code cache handling and the difference in exception frames of the 68020 to the 68000. Also there is an emulator for the “MOVE SR,x” instruction that became privileged on later processors.

The Masterpiece

Quite many of the patches actually alter QDOS for use with a graphics card with more resolution. At first I thought this was somehow connected to the Aurora and wondered why the condition for their activation apparently could never be true. But then I saw that Aurora’s VRAM starts at $4C0000 and the patches are all for VRAM that starts at $4E0000. The only explanation is that this is all for Miracle Systems never release Masterpiece graphics card. They must have been pretty well along the development path if these patches all made their way into the default ROM already. It even goes so far as to patch PTR_GEN after it is loaded.

The interesting thing about this is that the patches could easily be altered to work with the Aurora. As I don’t own an Aurora this is not for me to do, however.

The code

Finally here is the source code for all to see. For this version it was important to me that the result is bit-identical to the original source code, even though I had a strong urge to to change some code along the way… The result is not completely bit-identical to the GC2.49 ROM, but mostly because the utility libraries have changed. I have verified that the patches are exactly the same.

I will also submit the changes to Wolfgang to incorporate back into the SMSQ/E source code.

(Super)GoldCard boot source code

QL-SD teaser

The QL-SD driver seems to be finished (note that it currently doesn’t work with the MiST FPGA board, but there are no more known problems with either the original QL hardware or the MiSTer FPGA machine).

Now the boring part has begun, which means hours of reading tax related stuff (selling stuff internationally is hard!), writing/updating the manual, preparing an order page, preparing shipping labels, etc. I really don’t enjoy this part of the process.

Anyway, as a short teaser, the hardware does exist now in some quantities:

I will probably open the order page publicly starting September, after my holiday.

QDOS: To LRESPR or not

Update: the old code had a bug if the EXE was made resident using the HOT_RES keyword (thanks to Jan Bredenbeek for pointing it out), updated code below.

Today I’ve had a short discussion about creating a QDOS executable that can both be LRESPRed (to install a thing) and EXecuted (to, erm, execute it). One important detail is that LRESPR must only work in the main BASIC, as otherwise the system will crash once the daughter BASIC is terminated. There are several ways to do it, but I’d like to share mine:

base    bra.s   start
        dc.w    $4AFB
        dc.w    4
        dc.b    'Test'

; Trick: on an EXE call a6 must point to either a BRA ($60) or JMP ($4E).
; both have bit 6 set ($40). On Basic a6 points to the MSB of sb_buffb.
; Bit 6 will never be set as long as QLs have less than 1GB of RAM :-)
        btst    #6,(a6)
        beq.s   lrespr                  ; Definitely LRESPR
        cmp.w   #$4afb,6(a6)            ; This check is somewhat optional...
        beq.s   job_start               ; but in case QLs ever have >1GB... :)

        trap    #1
        tst.l   d1                      ; Job ID = main BASIC
        beq.s   basic_start

; LRESPRed from daughter SBASIC/MultiBasic
        moveq   #err.nimp,d0

; LRESPred from main BASIC
;       ...
        moveq   #0,d0

; EXECed as normal job
;       ...

QL-SD, QL-microSD and (S)GC battery


So, a short update on QL-SD, I have spent another few hundred Euros on parts and everything has arrived except the package with the SD-card connectors, which seem to be lost in the mail. These are needed for the double-SD adapters, which I expect will be pretty popular. Instead of waiting for them to show up I have ordered another batch of 100 connectors elsewhere which should hopefully arrive in 1-2 weeks.


Urs was interested in the micro-SD variant that I have hacked together previously and initially I didn’t want to produce them. But then I wanted to try out another CAD package, KiCad, and this project seemed like a good way to start with it. I haven’t obsessed about this as much as I did on the MDV board and again I ordered the whole batch without having a prototype first, so if it works I have lots of microSD adapters to offer and if it doesn’t fit in the end I have not 😉 But again I have a good feeling about this. These boards, too, should arrive in 1-2 weeks. Here’s a sneak preview:

(S)GC battery

Finally, this is apparently something everybody who ever built QL hardware will produce as some point: a replacement for the SAFT 40LF220 battery. In my case I just wanted to test another PCB service as they had a good offer going and as I finally got myself my own SuperGoldCard (donated by Jochen Hassler, thank you soooooo much) I needed a new battery solution anyway. The only difficult thing was my inner perfectionist rebelling against just using some wire for the four contacts, so I actually spent a few hours sourcing perfectly milled pins for them:

These can be ordered along with a QL-SD for a small price when I’m eventually ready for sale.

QL-SD update

Just a slight update before I go on holiday for a week. The design of the MDV adapter board has been finalized and I already have the PCBs here:

The board can be built into four different configurations of which I will probably offer two:

  1. Single slot drive using a ready-made daughter board soldered onto the MDV board:
  2. Double drive where one slot is soldered directly onto the MDV board and the other is on a daughter board stacked on top of it.

    The initial plan was that the upper slot is by default “WIN1” and the lower slot “WIN2”. But turns out the card in the lower slow is difficult to change when the upper slot is occupied, so I think it makes more sense to have a permanent “WIN1” in the lower slot and use the upper slot for data exchange. In any case, there are simple jumpers on the board so the final decision can be made by the user, no soldering necessary.

The other variants are fall-backs that I added in case the two versions above made problems because when ordering 50 boards without having a prototype first it’s good to have some options. Looks like I don’t need them, though.

A few parts are still on their way from China and a few more parts I need to order from the US after my holiday. I have bought 300 LEDs from China and initially I was very happy with them, but compared to brand-name LEDs they are a bit more “spotty” and less diffuse/homogeneous, so I won’t use them after all. Which also means that the colors are not yet defined, if you’ve got anything against amber/red then speak up now or forever hold your peace 😉

Speaking of LEDs, I have added some solder pads where one can connect external LEDs (in one case I wired the original MDV LED to it). This is for the tinkerers and not used by default.

So, the project is still moving along, stay tuned.

Cueshell – The definitive file manager for the QL

24 years ago Albin Hessler released his file manager Cueshell into the world. It was and still is one of the most advanced programs for the Pointer Environment ever written, featuring a Multiple Document Interface (smaller directory windows within the larger application window) and drag&drop file management. Managing large directory trees became incredibly easy and I still use it very frequently. It was truly way ahead of its time and this might have been its problem, as commercially I think it wasn’t as successful as hoped. Some people might remember that we did a special QPC+Cueshell promotion bundle in the early days to help adoption, but I don’t know how well those did.

Some 13 year ago I made a feebly attempt to update it to the new WMAN2 system palette, but because visually it was so advanced and non-standard I never truly managed to do a version that would do it justice, so I still use the 4-colour version. It has aged quite well however:

A few days ago I asked Albin if he could provide me with the latest manuals etc so I could release it for free and he readily agreed. The manual, too, turned out to be very beautiful, with many screen shots and illustrations. So today I present to you the latest version Cueshell v2.14, I hope you take some time to check it out because it really deserves it.

Cueshell 2.14
Cueshell manuals