A noob's guide to QL machine code

[TMD2003]

Long time, no see, but I'm going to have to make this brief return.

I have decided that my opening salvo for the 2025 CSSCGC - just to give the new host a warm welcome - will be a QL conversion of a Spectrum game from an old type-in listing. The Spectrum BASIC program is barely more than 2K, and uses a few UDGs, which are... not common in QL-land. But, now that I've moved onto the Next* and started using sprites, I saw no reason why I could not do something similar on the QL.

Recently, I've written a couple of SuperBASIC routines to plot points accurately on the screen in both MODE 4 and MODE 8, by poking directly to the screen memory with a bit of logical operation to leave the pixels I'm not plotting alone, and just change the pixel I want to the colour I want. It works, but it's SLOW, especially on a regular-speed QL, and the CSSCGC host will likely only be using an unregistered QemuLator where the original-speed QL is all that's available.

Using this plot routine I've at least managed to draw my sprites which I am now reproducing on screen with a series of POKE_W commands (I couldn't get POKE_L to work - the numbers involved were too big!). This is faster, but still too slow. Not to worry... I'll use machine code. After all, I've done it before...

...and I have completely forgotten how I did it. I had some Z80 code that I managed to translate into 68K - but I have no record of how that was then assembled to work on the QL. I don't ever remember using an assembler, so I must have hand-assembled it. This was, for all intents and purposes, three years ago - and now that I have found the resources I used at the time, I cannot for the life of me work out how I could have done it and made it work.

I had Andrew Pennell's "Assembly Language: Programming The Sinclair QL", which has a convenient list of all the opcodes I'd ever need, but the information (page 69 onwards) is presented in a way that is so dense and difficult to read, mark, learn and inwardly digest that I can't possibly have read it and managed to get anything right. For instance, it is not at all obvious if ADD.B D0,A0 is a legitimate instruction, and if it is, what bytes I should poke in order to achieve it. (Though I see elsewhere that I should use ADDA.B D0,A0 anyway...)

If I'm making Z80 code, which I'm getting half-decent at now, I'd use an assembler. (SPIN, usually, because it has one built in and I can assemble, save snapshot, run, reload if necessary, adjust, assemble, run again in a few seconds). I have left notes implying that I used GWASL last time, but I can't get it to work ("bad parameter" on QemuLator and "invalid parameter" on QPC2 whether I use EXEC or EXEC_W to start it, although neither of these is accessed from FLP1 as in the instructions... because I never have a virtual disc drive attached to either emulator, it's MDV1 on QemuLator or DOS1 on QPC2).

Daniele Terdina's recently-released assembler looks interesting... except that I have zero chance of compiling it from source, so that's not a viable option. And even though it's apparently not complete, it'll surely do the basics, but it's all academic.

Are there any other assemblers out there that are easy to use, before I attempt to type in a very long SuperBASIC listing from a QL machine code book I bought at Crash Live for peanuts, that'll take longer to type in and debug than it will to write the entire rest of the program?

I need this done by the end of the month, machine code and all, at the absolute latest, so time is of the essence. I don't need much machine code - the barest of bare basics. If it was Z80 it'd be little more than a string of LDs and a RET.


* Who was it who said something about a potential QL core for the Next, three or four years ago? It's finally happened, and was revealed at Crash Live. I'm going to get that up and running at some stage.

[TMD2003]

...because without an assembler to at least have an idea of what's going on, indirect addressing is doing my head in when it shouldn't. All I need is the equivalent of:

Code: Select all

LD A,value (where "value" can be more than one byte in this case)
LD (HL),A

...which is then the equivalent of a POKE (or POKE_W, POKE_L) in SuperBASIC.

Here's what I'm trying to achieve - for now, this is the start of the routine that will print an apple sprite on screen. I should be able to POKE_L the screen address into the first line from SuperBASIC (and it'll be obvious where to do so as the byte sequence for the value will be 0,0,2,0).

Code: Select all

MOVE.L #131072,A0		; loads A0 (four bytes) with the start of screen address memory (00020000h)
					; shouldn't need to be an LEA as the screen address never changes...
MOVE.B #126,D1		; a constant held in D1 to increase the value held in A0 by 126
					; i.e. move the screen memory to the start of the next line

; row 1
MOVE.W #43094,D0		; use D0 as the general data transfer register ("A" on Z80 but more than one byte)
					; load it with the value to transfer to the address held in A0 (equivalent of "HL")
MOVE.W D0,(A0)+		; drop the value held in D0 into the address held in A0 and increase A0 by 2... right?
					; there is no obvious indication that this is a legitimate opcode, only an implication that it works...
MOVE.W #43605,D0		; load D0 with the value to transfer to the address held in A0
MOVE.W D0,(A0)		; drop the value held in D0 into the address held in A0, this time with no increase...
ADDA.B D1,A0			; increase A0 by 126 to move it to the start of the next row of the sprite

...and so on.

Until I can get the syntax of this routine right, I can go no further. And then I've got to work out how to do loops...

[t0nyt]

There's various assemblers available for download https://dilwyn.theqlforum.com/asm/index.html if that helps at all

[bwinkel67]

Check this page out:

viewtopic.php?t=4530

These QL Holiday cards are all written in BASIC with a sprite implementation which was created by Andrei Tenu of this forum. I copied the technique to create the Grinch one. Andrew has also written several BASIC-based games using this technique:

QStar 1 - viewtopic.php?t=4809&hilit=QSTAR
QStar 2 - viewtopic.php?t=4821&hilit=QSTAR

You'll also see how I created my own sprites for QStar 1 and changed them to ones for Asterix & Obelix. In any case, these software sprites integrate really well into BASIC and might make your life easier. You can draw them in Windows and convert them over to the QL via Paint.net on Windows and Photon on the QL. Here's a video of my Asterix sprite conversion of Andrew's QStar 1.

https://www.youtube.com/watch?v=AG_2QzEd8yM

[Mark Swift]

Hi

When assembling on the QL I use QMAC, however I usually assemble elsewhere using VASM.
I keep my sources compatible with QMAC to give me the option to assemble on the QL too.

The download page for VASM includes Windows versions but not MacOS (Darwin) or Linux so I include my binaries here.
You could also download the source and compile your own version for whatever platform you use.

VASM-linux.zip

(1.23 MiB) Downloaded 34 times

These are the assembler options I use for VASM.

vasmm68k_mot -no-opt -ldots -Fvobj SOURCE1_asm -o BINARY1.out -L LOG1.log
vasmm68k_mot -no-opt -ldots -Fvobj SOURCE2_asm -o BINARY2.out -L LOG2.log
vlink -s -brawbin1 BINARY1.out BINARY2.out -o BINARY_exe

Until I can get the syntax of this routine right, I can go no further. And then I've got to work out how to do loops...

I think VASM will let you quickly knock something together in order to check your syntax.

[TMD2003]

There's various assemblers available for download https://dilwyn.theqlforum.com/asm/index.html if that helps at all

Well, it might. I already had Computer One assembler, but now that I've managed to get it to work, it won't assemble any code - doesn't matter whether I write it in capitals or lowercase, on its own editor or in an external text editor, it flags everything as an error and certainly isn't going to tell me the correct way of doing it. The dot in the middle of the first MOVE.L shouldn't be there, apparently.

This is particularly frustrating as I have a load of test files from the last time I experimented with machine code and made it work - it's full of _asm, _cde and _lst files with the strong implication that I used Computer One assembler and made it work, so what could the problem possibly be now?

...oh, wait... got it. I have to put a space at the beginning of each line or it thinks I'm trying to type a label, rather than an opcode.

Any of you familiar with Tony Hancock's "The Radio Ham"? This is a bit like trying to talk to Yokosuji in Tokyo. It is are raining not here also.

When assembling on the QL I use QMAC, however I usually assemble elsewhere using VASM.
I keep my sources compatible with QMAC to give me the option to assemble on the QL too.

The download page for VASM includes Windows versions but not MacOS (Darwin) or Linux so I include my binaries here.
You could also download the source and compile your own version for whatever platform you use.

For now, I will keep on battling with Computer One - but I'll keep this one in mind. If I want to do any more serious QL machine code, this might well be the solution I was looking for.

Compiling source code, as I said, is a non-starter. The most I've ever compiled was the LAME command line for Ubuntu 7.10 - everything I ever tried that was more complicated than that spat out error messages that I didn't understand and had no hope of fixing, even when I followed the compiler instructions to the absolute letter. It has soured me on self-compilation for 17 years and counting.

[Martin_Head]

I always liked the Talent/Quanta Assembler Workbench. Combined Assembler and machine code monitor. See the three 'talent' downloads in the above link to Dilwyn's website.

In your machine code above, ADDA.B is not a valid instruction size. ADDA.W and ADDA.L are.

It looks like you are trying to do a POKE_L 131072,$A856AA55 is that right? as you talk about a 0,0,2,0

Also you could just MOVE.W #$A856,(A0)+ and MOVE.W #$AA55(A0)

If you used the Assembler Workbench, you could assemble the program, then single step through the program to test it and see where it goes wrong. All in the same package.

[pjw]

I used to use Computer One's assembler and excellent symbolic debugger, but they fell behind, so now its all Qmac/Qlink with Qmake as the glue. Those programs were made for the QL by some of the people who made the QL, so I see no reason to use any other. Theyre not pretending to be the little brother of some tool on some other system. Qmac is also used to assemble SMSQ/E. GWASS isnt bad either.
Qmon/Jmon is a very competent debugger. I dont know of any other, apart from the old C1 suit, which, BTW, may still work well for Qdos on QL hardware.

Occasionally I use Easy68k, a Windows program (possibly Linux and others) to try out small bits of code or to see how single instructions work exactly. Easy68k is like a 68k interpreter, so its easy and fun to use.

[TMD2003]

I always liked the Talent/Quanta Assembler Workbench. Combined Assembler and machine code monitor. See the three 'talent' downloads in the above link to Dilwyn's website.

I must have tried that one as well, previously, but found it as easy as the UNIX command line. (I can do some things on the command line, but not many. GREP and SED I could just about handle on a good day, but AWK finished me off... and that was 21 years ago.)

In your machine code above, ADDA.B is not a valid instruction size. ADDA.W and ADDA.L are.

Worked that out soon enough. It's all turned to ADDA.W now. I had my first crash getting MOVE.L and MOVE.W confused...

Also you could just MOVE.W #$A856,(A0)+ and MOVE.W #$AA55(A0)

I didn't think that would work. That could compact the code down a bit (not that I really need to). Also, three MOVE.Ws have been compacted into one MOVE.L and one MOVE.W - I'm keeping tabs on the values with a spreadsheet.
EDIT: that's 90 bytes I've saved over all the code so far.

Anyway... I am now rocketing through this job, and I've made my first loop that works. Didn't need two nested loops, either, which might be a pain.

[spkr]

People willing to learn writing assembly, how awesome! I can only praise you for this effort, and Im more than willing to help your laerning curve!

I would recommend using vasm or rmac. They are widely used, supported and actively developed assemblers for the motorola 68k. The reason why I suggest these, is that they also provide some, lets say, additional sugar; for example:

- allows the use for "add.w" as a general use case to omit specifics like "addi.w", "adda.w"
- allow for tsome explicit tests when assembling that all your code is pc-relative (you may need this when writing OS compatible QL code)

For the allowed operations, I still use this document that contains all 68000 opcode/instructions:
https://frummel.org/~weedz/atari/docs/S ... %20Set.pdf
For the cycle timing, I generally use the user manual:
https://frummel.org/~weedz/atari/docs/MC68000UM.pdf - chapter 7

Im willing and able to give some handson approach if that would help your cause, the QLForum discord community is active, and direct support could be provided over there~

If there still speciifc unanswered questions, hollar!

Kind regards,
Wietze