View source for Sinclair QL

== Sinclair QL ==
The Sinclair QL (for Quantum Leap) is a personal computer launched by Sinclair Research in 1984, as an upper-end counterpart to the ZX Spectrum.
It was aimed at the serious home user and professional and executive users markets from small to medium-sized businesses and higher educational establishments, but failed to achieve commercial success.
The Sinclair QL uses a Motorola 68008.CPU with 32-bit internal data registers, but an 8-bit external data bus.

=== Setting up ===
* Assembler: VASM
* Emulator(s): Q-emulator ( http://www.terdina.net/ql/winql.html )
* Tool(s): Mdvtool (create MDV images)
* Hardware: Sinclair QL machine or Spectrum Next running the QL core

In order to test the final result one can use a floppy-disk replace replacement or Qubide interface to load files from SD card.

=== Loader ===
To load content from a folder or MDV image, you need both the binary and a basic loader, similar to platforms like the ZX Spectrum and CPC, create a file called BOOT in the output folder with the following code:

<syntaxhighlight lang="">
10 PROGRAM=RESPR(512)
15 LBYTES "MDV1_CODE",PROGRAM
20 CALL PROGRAM
</syntaxhighlight>

Now copy your intro code as CODE into the same output folder and Q-Emulator should be able to pick everything up automatically and load the code. You can link the folder directly from the Q-emulator or generate a MDV image using mdvtool for distribution.

=== Memory map ===

<syntaxhighlight lang="">
$00000 	Onboard 48k Rom 	
$0C000 	16K Rom Cartridge 	
$10000 	Onboard I/O 	
$18000 	(R) RTC byte 0 / (W) RTC Reset
$18001 	(R) RTC byte 1 / (W) RTC Step
$18002 	(R) RTC byte 2 / (W) Transmit control
$18003 	(R) RTC byte 3 / (W) IPC link control
$18020 	(R) Microdrive/RS232c status / (W) Microdrive control
$18021 	(R) Interrupt/IPC status / (W) Interrupt control
$18022 	(R) Microdrive Track 1 / (W) Microdrive / RS232C data
$18023 	(R) Microdrive Track 2 / (W) Display control
$18063 	Screen Mode S---C-O- On Colordepth Screenpage
$20000 	Screen 1 	Screen Ram
$28000 	Screen 2 /
System 	system (systemvars*)
$2847C 	System stack pointer*
$28E00 	Base of Common Heap*
$2BC00 	Free area*
$30000 	Running Programs 	Free area
$37200 	Basic area*
$38000 	User Stack pointer*
$38000 	Prog data*
$40000 	Add on ram (up to 512k) 	
$C0000 	Add on peripherals 	
$E0000 	Add on Rom (up to 128k) 	
$FFFFF 	End of address space
</syntaxhighlight>

=== Video display ===
There are two possible screen modes, configured by bit 3 of port $18063

setting a 0 give 4 colors at 512x256 with Black,Red,Green and White
setting a 1 give 8 colors at 256x256 with Black,  R, G B, C, M, Y and White

The Screen is directly memory mapped from $20000-$28000, There is no palette - the colors are fixed.

==== Vsync ====
Port $18021 bit 3 will go high (1) when Vsync starts, then we need to write a 1 to that same bit at the same port to clear the Vsync event.
Therefore, in effect we can write 255 to port $18021, then read from $18021 until it's nonzero to get the Vsync event.

<syntaxhighlight lang="">
 move.b #%11111111, $18021     ; Clear interrupt bits
waitvbl:
 move.b $18021,d0            ; Read in interrupt state
 tst.b d0                    ; Wait for an interrupt
 beq waitvbl
</syntaxhighlight>

==== Before using Screen2 ====
Since the Screen2 area is mapped to the system, we need to add the following code at the start of the program to be able
to make use of it.
<syntaxhighlight lang="">
 trap #0
 ori #0700,sr
</syntaxhighlight>

Or alternatively move the stack manually 
<syntaxhighlight lang="">
 move.l  #$40000-4,sp
</syntaxhighlight>

==== Swapping screens ====
To swap between the two screens via hardware, we need to swap the buffer pointer and set the screen register accordingly.

<syntaxhighlight lang="">
resetScreens:
 move.l  #$20000,screenpointer1
 move.l  #$28000,screenpointer2
 move.b  #8,scr
 move.b  #0,scr+1
 move.b  #8,$18063
 rts

swapscreens: 
 lea  screenpointer1,a0 ; get screen ptr address
 move.l  (a0),d0         ; save it
 move.l  4(a0),(a0)+     ; rotate screenbuffers
 move.l  d0,(a0)         ; write back
 lea     scr,a0          ; get flipbit
 move.b  (a0),$18063     ; write flipbit
 eor.b   #128,(a0)       ; flip the bit
 rts

scr: dc.b    8,0
</syntaxhighlight>

==== Copying and clearing the screen ====
As an alternative to swapping the screenpointers, here is some compact, but slow, code to copy over the contents from screen2 to screen1 and clear the screen2.
<syntaxhighlight lang="">
 lea $28000,a0       ; screen2
 lea $20000,a1       ; screen1	
 move.l a0,a2
 move.w  #256*32,d0
swappage: 
 move.l   (a2),(a1)+
 clr.l   (a2)+
 dbf     d0,swappage
</syntaxhighlight>

==== Plotting to screen ====
While there are a few rom/trap routines that allow you to draw primitives, these are quite expensive to setup and clunky to use.
So its best to draw into the screenmemory directly, using the following plot routines provided by gigabates.

<syntaxhighlight lang="">
; plot pixel
; a0 = screen,  d0 = x, d1 = y, d2 = color index 0-7
plot:
 lsl.w   #6,d1           ; y byte
 moveq   #3,d3           ; x pixel shift
 and.w   d0,d3
 add.w   d3,d3
 asr.w   #2,d0           ; x byte
 add.w   d0,d1           ; total bytes
 add.w   d1,d1           ; to word offset
 lsl.b   #6,d2
 bcc     .noGreen
 add.w   #$8000,d2
.noGreen:
 lsr.w   d3,d2           ; shift scrambled color to px pos
 or.w    d2,(a0,d1)
 rts 
</syntaxhighlight>

=== Sound ===
The Spectrum QL has 2 channels of internal beeped sound, or AY support via an extension board.

Speaker Sound commands have to be passed via the Bios, using the same kind of commands as with the keyboard.
You need to adjust the Pitch settings to change the sound, and you can change the randomness bits to make the sound distorted, It seems it's not possible to change the volume!

<syntaxhighlight lang="">
move.l #$11,d0			; set sound command
lea .sounddata,a3		; load sound message payload pointer to a3
trap #1				; call dosound
</syntaxhighlight>

=== Additional Resources ===
* [https://demozoo.org/productions/?platform=95 Sinclair QL demoscene productions]
* [https://ia600804.us.archive.org/9/items/SinclairQLHomepage/docs/manuals/qltm.pdf QL Technical Guide]
* [https://www.chibiakumas.com/68000/sinclairql.php 68008 Assembly programming for the Sinclair QL]
* [https://dilwyn.qlforum.co.uk/  Sinclair QL Pages]
* [http://www.terdina.net/ql/winql.html Q_emulator]