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.

Sunday, 7 January 2018


I thought it would be nice to re-cap the year 2017, addressing some topics that did not quite make it into blog posts. Still, keeping to the theme of the blog, I won't flood this with personal notes and work-related stuff.

I'm usually able to maintain the twice a month pace with my blog. The most viewed posts are still the ZX sprites article years back, blog posts detailing Schneider EuroPC and Orel BK-08, and strangely enough, the piece about spaghetti western guns.

Although C64 and ZX Spectrum received most of my attention, Sinclair QL has re-emerged as another favorite, although a very challenging platform. I guess I'll be continuing with more detailed notes about QL in near future.

I'm also trying to expand the blog format with platform-specific pages, starting from a QL overview  that binds together relevant blog posts. I'm envisioning a kind of personal encyclopedia, but time will tell how this might develop.

Releases, coding, events

At the beginning of 2017, I revised my Multipaint paint program and released it as the Metal Edition. It's now beginning to be a usable software and I'm glad to see others have created great images with it.

I've received far more comments and queries about the software over the year than before. Most times I try to accommodate, but occasionally people ask for image formats that in my mind are out of the scope or spirit of the software (such as more modern RGB modes). The development continues and a new version can be expected in Spring 2018.

In addition I've created a few pics myself.

Earlier in the year, I contributed to Desire's Don't Mess with Texas TI/99-4A demo with a single picture. It was an interesting experience to make something with a "megagroup". Co-operating through a Slack channel and Facebook messenger, I found that the huge amount of comments, suggestions and discussions can be both a blessing and a bit of distraction. All in all it turned out good, but also reminded me how desperately Multipaint needs an aspect ratio switch...

The bottom is empty as it's the play area
The most recent work is the above half-image for the International Karate graphics competition at CSDb. I chose to do the Helsinki Cathedral in spirit of the original game graphics. The perspective is problematic as here the fight would take place on the stairs, and the bottom/top half joining cannot be resolved so well. I'll see if I still have time to make another piccy...

Similarly, I continued to create text art in the form of PETSCII images, all the time using Marq's PETSCII editor.

Although the logo for Hokuto Force's Sliced Blue is from late 2016, I'll mention it here.

2017 was the first time I made C64 "dir art" and pure C64 BBS graphics, which brought some more limitations to the PETSCII format. BBS graphics work with control codes and generally use a lower-case variant of the set, with black background.

With this experience I realized a BBS pic doesn't need to have the ASCII/ANSI/2x2 aesthetic I often associate with BBS art.

BBS graphics for the Rapidfire BBS, possibly a WIP image
One more addition was the graphics part of the tiny Vammala Party C64 intro called Nothing but Pet Ski. This animloop was fun to make, and PETSCII editor supports this kind of animation creation rather effortlessly.

I also co-edited a journal issue with the theme of Text Art with Marq, including PETSCII, ASCII, teletext, typewriter art and boundary crossings between "high" & "low" art, history and the present.

As another PETSCII/Text Art related thing, I rewrote some of my 2016 Fort Django code on the C64 and released a 1.1 version with a complete new map and soundtrack. (Ooh, another firstie: a published C64 SID track!)

I'm sitting on another near-finished Commodore 64 game, but I could not release it in 2017. I'll try to look for a suitable outlet for it. Expect even more lo-fi and PETSCII aesthetics and crappy SID tunes.

Zoo Party 2017 was one of the scene/retro highlights of the year, and I wrote a bit about it too. All in all I managed to contribute to many small compos, either online or remote, which I won't mention here.

During 2017, I observed that my 8-bit assembler (6502 and Z80) coding has advanced to the point I no longer need to rely so much on c bits to structure my programs, as certain coding practices and a good assembler facilitates most of the necessary things anyway. Releases are still scarce, as finishing projects tends to be far more difficult than starting them!

In a more modern track, I've continued with with Javascript web coding, adding some threejs webGL to the mix. Browser-based code is becoming more potent all the time, so you don't have to be a coding guru to make nice interactive stuff. One could even say HTML+JS is the "BASIC" of our time.

I also made first time PHP code, which was a lot more straightforward than I thought. Certain needs also forced me to write a few Python scripts, which I also found quite amusing.

Games, Films, Books, etc.

I'll be quick with games, as I don't play that much. I probably spent most time with Larn at, and Clive Townsend's Saboteur 2 remake was also a very welcome diversion. I occasionally play through Ultima IV and this also happened last summer.

This year, I've watched less westerns than before, and even those were not that memorable. I'd say re-watching Dead Man was one of the highlights. On the western front, I'd rather revisit the classics than continue scraping the bottom of the barrel, although that will probably go on too. I tried to read a few western books but to be honest they didn't quite grab me.

The one stand-out fictional work of 2017 for me was Twin Peaks: The Return 18-part TV series.  Lynch/Frost et al. managed to create something emotionally so devastating, that the imagery and mood of the series lingered in memory weeks after it had finished. It simply made any other TV work seem stale and formulaic in comparison. The somewhat tough pre-requisite was the watching of the original series and the Fire Walk With Me film.

Time and Time again
Doctor Who continues to be one of my favorite series, although it might be said the last season was a bit overstaying its welcome. A few years back Peter Capaldi's more mature doctor (well, in appearance anyway) was a welcome turn for the series, but now the writing has struggled a bit and the showrunner/writer Steven Moffat has perhaps used up his box of tricks. Then again, as far as I know the ratings have been suffering for a few years and the problems may have resulted from trying to revitalize the series' popularity. With the oncoming 2018 season, I'm now expecting at least season 5 scale reboot, on with the new doctor!

At the movies. Valerian was a bit better than I expected. The world-view and the plethora of alien races are whimsical and Valerian-like, and the theme of technological/institutional/corruption versus "natural" harmony is also present. Casting wasn't as awful as I envisaged, but the characters have been rewritten as silly jerks and the charming dynamics between them in the original comics, has been lost. Also, a lot of time is spent on chaotic action scenes and awkwardly falling through floors / walls etc.

Blade Runner 2049 was stylistically interesting, but story-wise it felt a bit empty. With Interstellar/Arrival-style production and Hans Zimmer soundtrack, they were maybe playing it a bit safe. It was still quite gorgeous experience at the cinema, I'll admit that. Harrison Ford's involvement and the appearance of certain character from the original film could have been scrapped in my opinion. Unlike in the 1982 film, the bad guys were a bit poor show.

Coincidentally or not, I've been re-reading Philip K. Dick. Do Androids Dream of Electric Sheep?  was a much forceful work than I had remembered, and although the story lacks some of the film's crowning moments it also has some superb material that the film rejects. What motivated Deckard to have such a dangerous job? Well, he wanted to buy an expensive animal for himself. Although some aspects of the new film may have been influenced by the book, I am surprised they did not mine the original more for ideas. Oh, and the book mentions 3D-photographs :)

I read Frank Herbert's Dune for the first time, one of the last really major sci-fi works I had not experienced before. Sure, I've played the Amiga game a bit and seen the Lynch film years and years back so I kind of know what it's about. I enjoyed the world-building aspects of it, and can easily see how some themes found their way to Star Wars. Yet the story has quite silly bad guys, and some of it reads like a teenagers wish fulfillment fantasy, of how special and world-changing an individual can discover himself to be.

We put a dune in your dune so you can.... nevermind
Speaking of Star Wars, I also saw Last Jedi. Count me in with the "meh" crowd. The new film attempts at undermining of the Star Wars and Jedi mythos, without necessarily giving anything substantial in return. An enjoyable ride nonetheless.

Instead of the common criticisms, I'm more worried about the haphazard structuring of the new films and a general disregard towards the coherence of the originals. Characters simply appear as force ghosts, holograms, disembodied presences and whatnot. Whatever character the creators want to bring in, can be brought to the screen at any moment by some contrived device. The distinct, simple physical spatiality of the original Star Wars universe seems to be gone.

2018? More of the same I think!