Wednesday, 24 January 2018

QL assembler

Lately I've turned into a bit of a QL-nut, and now I wanted to try coding assembler on it. Most of the files and initial info are from Dilwyn Jones's comprehensive QL web pages, particularly the assembler and archiver pages.

Although vasmm68k on Linux is very useful, there are limits to what kind of code can be run on an emulator. It's not easy to find an emulator that a) works on Linux, has b) cycle-exact scanline video emulation, has c) flexible transfer between it's own filesystem and the PC and is d) free. UQLX is nice to have, but as far as I know it does not do screen flipping/vsync in the way a real hardware does.

So I went the route of compiling 68000 code on the QL hardware platform itself. After all, it is a semi-16-bit architecture with 800K of memory. With modern media, it should not be excessively painful to code on this system.

First I tried a tiny assembler called Adder, but only on my unexpanded QL it goes past the initial screen, so I moved to the larger Qmac assembler/linker package. This is a bit of an overkill for the things I want to try out, but at least it is convenient and does what one would expect from a full assembler.

I also tested asm20 at some point, but after a promising start it seemed a bit too incomplete. I failed to find a way to include binaries, and as I could not turn off the listing (opt nolist does not work) it becomes quite slow for even small sources.

I'm wondering why a quick editor/assembler/monitor setup like Asm-one or K-Seka on the Amiga/Atari ST does not exist for QL, or if it does, where is it hidden?


So, over to the Qmac/Qlink package. Installing is not too hard once you get the hang of transmitting files over to the QL. Just unzip the qmac package on your Sinclair QL drive.

It should be remembered that QL archives need to be unzipped on the QL filesystem, as PC/Linux extraction tends to mess with QL executable file headers. To get around this, there's an already-unzipped version of unzip, and a BASIC file that repairs the header for that file.

After this has been achieved,

exec_w flp1_unzip;'flp1_archive_zip' 

will start storing the files from the archive_zip to flp1_, if they are on that drive.

After the qmac file is unarchived, it is a good idea to copy the assembler, the linker and the source to a ram disk, if you have the memory to spare, as it should always be faster than any drive.

Afterwards, the executables can be run directly from the ram drive:

exec_w ram1_qmac;'ram1_source'

where 'source' is the assembler source text file with the name source_asm, here assuming it is in ram.

exec_w ram1_qlink;'ram1_source'

and this would result in a source_bin file.

Running the binary:

a=respr(size): lbytes ram1_source_bin,a: call a

For a relocatable code file, this would then reserve some unused memory space, load the file and call it. The size must be enough to contain the binary size. For non-relocatable code, the code should be loaded to a "safe" address and called from there, such as 196608 on an unexpanded QL.

ALCHP and LRESPR might be more handy but I tend to avoid running the Toolkit 2 extension unless I need it, as it's a few seconds more boot time :)

The commands above also show how to pass parameters to executable files. Note that EXEC_W executes the file and exits, whereas EXEC would run it as a job.

Running QED text editor

QED is a nice little text editor for writing the assembler sources. Loading QED, the file definition has to be a bit more explicit:

exec_w flp1_qed_exe;'flp1_source_asm'

Use F3 to enter the command mode in QED. X saves & exits the editor, Q exits.

By the way, with a television monitor the QED window size may need changing. Be sure to download a QED version that includes the BASIC configuration file. This config program brutally overwrites the QED binary with your chosen parameters, which is handy in that the QED can then always be copied as one file.

The configuring program may complain of a missing variable, as the window size function calls are part of yet another non-universal extension package. Insert something like this at the beginning:

10 SCR_XLIM=512: SCR_YLIM=256

Boot files

The above won't go very far in establishing an effortless edit/compile cycle.

But with boot files and the superBASIC procedures, much more can be done. Besides, creating useful boot files on Sinclair QL is somehow more fun than scripting on modern computers.  Use colors, graphics, whatever you like. Hey, it's BASIC - but with procedures!

My boot file will copy the assembler, linker and my current working source and related binaries to a ram disk. From there they run almost instantly.

They could be copied from the HxC Floppy Emulator disk image, but the QL-SD sdc1_ drive is much faster than the HxC, so the files are copied from there.

20 print "Copying to RAM..."
30 copy sdc1_qed_exe to ram1_qed
40 copy sdc1_qlink to ram1_qlink
50 copy sdc1_qmac to ram1_qmac
60 copy sdc1_source_asm to ram1_source_asm
70 copy sdc1_datafile to ram1_data_bin

Obviously these can be made into it's own function that gives on-screen information as the files move.

In absence of a real makefile, I have a defined procedure called MAKE, just to have a similar compiler command on QL as on my Linux:

100 def proc make
110 exec_w ram1_qmac;'ram1_source'
120 exec_w ram1_qlink;'ram1_source'
130 end def

After all this, MAKE will assemble and link the file source_asm, and as a result there will be ram1_source_bin.

Executing the result can be made into a procedure too, just remember to reserve enough memory to fit the binary, otherwise it will behave erratically=likely crash.

I called this procedure SYS to have it short and as a nod to the Commodore computers.

10 a=respr(8192)
200 def proc sys
210 lbytes ram1_source_bin,a
220 call a
230 end def

If the code is to be loaded to a fixed address, the LBYTES should load it directly and no RESPR is needed.

Also bear in mind that apparently plain BASIC is not able to free the memory taken up with RESPR. So the memory should be reserved once in the boot file, not inside the procedure. As long as you don't re-run or load another basic program (and you don't need to) the variable is kept in memory.

Some extensions have commands for allocating/deallocating memory from BASIC, such as the ALCHP mentioned above.

A procedure for launching QED with the current source is also desirable, as a sort of alias for the long command line.

250 def proc qed
260 exec_w ram1_qed_exe;'ram1_source_asm'
270 end def

Development environment options

So, after the boot file has been run, I can type QED to edit my current source file, MAKE to compile it, SYS to run the code. More shortcuts can be created for producing disc backups out of the RAM files, etc. Instead of command procedures I could also create a key-press based environment.

As Sinclair QL is a multitasking system, the QED text editor can also be run as a parallel job with EXEC instead of EXEC_W, flipping between QED and the BASIC prompt using CTRL+C. This has the advantage I don't have to exit QED so the cursor position is not forgotten. The self-defined BASIC procedures remain in effect. Also, I can view and edit the source as the compilation runs in the background.

Whenever screen update happens on another job, the QED screen gets messed, and there is no screen refresh when you switch a job. In QED, F5 key at least redraws the screen.

Dual QL setup

With the above setup, if the code returns to BASIC neatly, it's possible to go on modifying the source without having to boot up the QL after every code test. Obviously, if the program crashes the system has to be rebooted, but having all the current materials auto-copied at least reduces the chore.

The crashes and re-boots resulting from wrong code can be alleviated by having two Sinclair QLs connected with a net cable, one as the compiler and the other as the target. Although this is probably more trouble than it's worth, I had to try.

One approach might be to assign NET values to each of the QLs and use LBYTES neti_2,address type commands for loading in the resulting binary data.

It gets crowded in here...
But, after fixing my EPROM cartridge with an FSERVE-enabled Toolkit II, I can also finally enable a file server between the Minerva-equipped QL and the unexpanded QL with a TKII cartridge. (The fileserver does not work from a RAM-based toolkit.)

With the file server, it becomes possible to access files from drives connected to the first QL, referring it with n1_ or n2_, for example. Commands can take the form of EXEC_W n2_flp1_qed_exe

The file server works if you remember it's not all-powerful - trying to do complex things such as compiling across the server and editing text at the same time may result in the computer getting stuck. Trying to poll a file every few seconds over the server was not such a great idea either. Even if I managed to get the QL stuck, in most of the cases the actual server job survives, so files may be recoverable.

So, instead of the LBYTES neti_ - SBYTES neto_ approach I can use the file server to load and run the binary off the ram disk of the other QL.

The second QL does add some unwanted physical complexity to the setup, and obviously the crashing target QL needs to be re-booted too.

Another thing is the other QL does not have Minerva so my page-flipping routines need a different approach and the code can't simply return back to BASIC. But more of that some other time.

68008 assembler

A few snippets of my early code. I'm only here interested in plain QL coding, and my code likely won't work in the later variants.

Still, I try to be nice-ish, and make relocatable code, mostly because it's useful to have the code return to BASIC intact for further editing (see the setup above). But I've not loaded the screen address using the QDOS call and neither do I care about potential graphics screen variants.

The following code will fill the usual screen area and return to BASIC without an error message:

    MOVE.L #$20000,A0   ; starting from 131072
    MOVE.L #$3FFF,D0    ; $4000 words = $8000 bytes
    MOVE.W #$AA00,(A0)+ ; bit pattern
    DBRA D0,LOOP        ; loop until d0 is 0

    MOVEQ #$0,D0        ; return to basic

The Qmac likes to have SECTION and END.

Note that using + with MOVE.W will "hop" the A0 address in 2-byte steps. With MOVE.L it would be 4.

Next thing to ponder is why the following code might be faster than the previous:

    MOVE.L #$20000,A0
    MOVE.L #$7FF,D0
    MOVE.L #$AA00AA00,D7
    MOVE.L D7,(A0)+
    MOVE.L D7,(A0)+
    MOVE.L D7,(A0)+
    MOVE.L D7,(A0)+

    MOVEQ #$0,D0

With 68008, I'm told it would be wise to have as much as possible done through the registers, as the speed issues (versus 68000) are not such a huge problem.

Some have gone as far as to say the QL is "really 8-bit", but as the opcodes are equal to 68000 and much more than 65536 bytes of memory can be accessed without writing any paging routines, I'd say it's a true 16-bit world for the coder.

The verdict

I'm surprised it's still possible to get accustomed with coding on the QL itself. Today's card readers and the memory expansion are very helpful in this. The largest problem is that the Qmac is not that fast, especially as the source begins to grow, but it has been useful in getting to know 68000 and the QL.

The QED text editor block copy/paste functions are a bit primitive compared to modern editors, but overall the typing experience is not that bad. Sinclair keyboards are a bit of an acquired taste, but I've found I can live with the QL keys.

It's been a long and rocky road to get the Sinclair QL make these things. But it has also been quite rewarding. I've been working with a sprite routine, something I'll come back to later.

No comments:

Post a Comment