Sinclair QL emulator

Press Power on. The QL runs a memory test, shows Minerva’s start-up screen and answers the F1/F2 question for you (F1, the monitor: mode 4, 512 × 256 in four colours — change it in the toolbar), then sits at the SuperBASIC cursor. Click the screen to give it the keyboard and type PRINT "Hello".

The SuperBASIC tab has example listings — windows and colours, mode 8 graphics, the turtle, procedures and functions, BEEP, and a game loop that reads the keyboard matrix with KEYROW. Type in & RUN types NEW, the listing and RUN into the QL through its keyboard, key by key, so you can edit the listing (or paste your own) and run it again. Dropping a .bas or text file on the screen types it in the same way.

How it works

CPU. The QL’s Motorola 68008 is a 68000 with an 8-bit data bus. The 68000 core (m68k-cpu.js) passes 99.5 % of the 820,000 non-address-error cases of the SingleStepTests 68000 suite, with exact cycle counts for 99.9 % of those; it counts time per bus access, so the QL runs it with word accesses costing 8 clock periods (two byte cycles) instead of 4.
ZX8301. Mode 4 (512 × 256, black/red/green/white, each word eight pixels: green bits then red) and mode 8 (256 × 256 in eight colours with a flash bit), the second screen at $28000, blanking, and the ULA’s claim on the lower 128K of RAM: during the 256 visible lines the CPU can only start a RAM access at the start of a 12-cycle slot, which slows programs in that RAM as on a real QL.
ZX8302. The real-time clock (seconds since 1961, set from your computer’s clock), the interrupt register (frame, gap, transmit), microdrive selection, the transmit register and the two-wire link to the IPC.
IPC. The 8049 that reads the keyboard and makes sound is emulated at the level of its commands: the ROM talks to it bit by bit through $18003/$18020 exactly as on a QL, and gets keystrokes (with SHIFT/CTRL/ALT), KEYROW rows, status and random numbers back. `BEEP’s eight parameters — duration, two pitches, the step interval and size, wrap, fuzzy and random — drive a square-wave synthesiser that follows the IPC’s behaviour.
Microdrives. Two drives play 174,930-byte .mdv images (the QLAY / Q-emuLator / sQLux format) as a moving tape: sector headers and data blocks with their preambles, gaps that raise the gap interrupt, 40 µs per byte. The ROM’s own microdrive code reads and writes them, so DIR, LOAD, SAVE, LRUN, EXEC and even FORMAT behave as on a QL (a fresh cartridge formats to about 222 sectors). With Turbo loads on, the emulator runs flat out while a drive is spinning, while it boots and while it types.

Microdrives

On the Microdrives tab: insert a .mdv image, start a blank cartridge (then FORMAT mdv1_name on the QL) or an empty formatted one, see what is on each cartridge, and download single files or the whole image. Everything a program saves stays in your browser (IndexedDB) and is back next time.

Add a file… writes a file from your computer onto a cartridge without the QL’s help: a SuperBASIC listing (.bas, which becomes name_bas for LRUN), data, or a QL program. QL executables need their job type and data space, which plain files lose on other systems; files that carry them in an XTcc trailer (cross-compilers, sQLux) or a Q-emuLator header keep them. Dropping a program file on the screen adds it to mdv2_ and types EXEC for you.

There is no win1_ or ram1_ device: the QL has no such hardware, and Minerva has no RAM disk. Files from your computer go onto a cartridge instead.

Assembler and debugger

The Assembler & debugger tab assembles 68000 code with the site’s 68000 assembler and runs it on the QL:

Ordinary code is put in 16K reserved for it with RESPR (typed for you once per reset), assembled for that address and started with CALL; end it with moveq #0,d0 / rts. The examples open a window and print through QDOS traps, write colour bars straight into mode 8 screen memory, make a sound through MT.IPCOM (the call BEEP uses), and move a block with the cursor keys read from the keyboard matrix.
Code that starts with a QDOS job header (bra.s start, dc.l 0, dc.w $4afb, name) is position independent: it is saved on mdv2_ as an executable file and `EXEC`ed.

The debugger beside the editor stops at breakpoints (click a line of the listing or the code view, or type an address or label), steps one instruction (F11), steps over a JSR, BSR or TRAP (F10) and steps out (Shift+F11). It shows and edits the registers and flags, and shows the code around the PC (disassembled), the stack and any memory. The 68000 cycle counter gives instruction times; on the QL’s 68008 add 4 clock periods for every word moved.

Keys

Your keyboard types the same characters on the QL whatever its layout; Backspace is CTRL+← and Delete CTRL+→ (the QL’s own delete keys); CTRL+Space stops a BASIC program. The Keyboard button shows a QL keyboard for phones and tablets.

Limits

The serial ports and the network only go as far as the registers: nothing is received, and bytes sent to ser1 are dropped. No Toolkit II, no disk interfaces.
The IPC is emulated from its documented commands, not by running the 8049’s own ROM, so software that talks to the 8049 in undocumented ways may not work.
Only PAL timing (50 Hz).

ROM

The ROM is Minerva 1.98a1, the replacement QDOS and SuperBASIC by Laurence Reeves, released under the GNU GPL (version 2) and maintained at github.com/MarcelKilgus/Minerva; the image, its licence and where its source is are in /tools/ql/NOTICE.txt.

The original Sinclair ROMs are not included. Amstrad’s 1999 permission to pass on its Sinclair ROMs covers the Spectrum, ZX80 and ZX81; asked about the QL, Amstrad’s spokesman said the rights may have been sold on, and the QL ROMs are described as released for use in Europe with the North American rights held by others — not a clear permission to share them. The ROM tab loads a ROM you own instead (it stays in your browser).

Privacy

Nothing leaves your browser. The ROM is loaded from this site; cartridges, a ROM you load and your listings are kept in your browser’s storage.