Welcome to Jadiam.org
Jadiam's Freeware WebSite
07/24/2014
Jadiam.org
Select your language : Franšais English Espa˝ol

This page was accessed: 27928 times.





QLAY2 Usage Documentation, updated 2004-11-7




(0) Contents


Introduction - what is QLAY2 and who is it for?

Files - available packages and their contents

Setting up - configuring QLAY2 for use

Usage - how to use QLAY2

Performance - benchmarks and tuning tips

Inner workings - inside the emulator

Limitations and plans - known bugs and the future

FAQ - Frequently Asked and Answered Questions

References - where you can find out more





(1) Introduction


QLAY2 is a Sinclair QL Emulator. It's an update of QLAY (for MSDOS) and QLAYW (for Windows 3) which were originally developed by Jan A Venema in the Netherlands. The Sinclair QL - short for Quantum Leap - was a ground-breaking multi-tasking computer system introduced by Cambridge, UK company Sinclair Research in 1984.

This specific release has been made for everyone that wants to get a stable emulation of a regular Sinclair QL system on a 32 bit Windows platform, quickly and for free. The focus is on compatibility with the original Sinclair QL, though with the option of extra speed and storage. It is not intended to be used with systems derived from QDOS, such as SMS/Q, but it does work well with the enhanced QL-compatible ROM Minerva. As source files are provided, anyone can use QLAY2 source code to add new features.

QLAY2 is an open source version of QL2K, an earlier and potentially more extensible port of QLAY to the Win32 platform, which was not strictly copyleft software in that users were required to register. So unlike QL2K, QLAY2 is released under the GPL (Gnu Public Licence). Follow this link for more details of the differences and how they came about.

QLAY2's 68000 processor emulation engine is based on that written by Bernd Schmidt for UAE (the Commodore Amiga emulator), also used in Basilisk (the Apple Macintosh emulator written by Christian Bauer). Like them, QLAY2 is released under the Gnu Public Licence or GPL, so its source code is freely available and users are obliged to share all changes they make, for the benefit of others.

This specific release of this Sinclair QL Emulator is designed to work optimally on Windows 2000 and Windows XP. As there are no calls to specific Windows NT technology, it may also be used under Windows 98 and Windows Millennium (ME), and Windows 95 and Windows NT 4.0 with Microsoft`s current standard system patches, without any need of add-ons, version-specific runtime code, or any kind of special compatibility library.





(2) Files and their purpose


There are two distributions of QLAY2 :

  • QLAY2.zip [181 Kb (185 646 bytes)] This provides only ready-to-run programs and documents. Get this one if you wish to use QLAY2 but have no interest in details of the code that implements the emulator.
  • QLAY2-Full.zip [1,51 Mb (1 593 422 bytes)] This package provides program binaries, documents and full source code, organised in a Visual Studio 6.0 Workspace, to make it easy to work with. This package is a superset of the QLAY2.zip archive.

You will also find the contents of qltoolsq.zip and qlayt.zip useful if you wish to transfer files to QLAY2 from a real QL or another emulator. These are command-line utilities developed for use with earlier versions of QLAY, but they are also applicable to QLAY2.


QLAY2.zip: Windows 2000/Windows XP Binary distribution


Files provided :

  1. Qlay2.exe: This is the main QLAY2 program. You start this executable in order to use the emulator.

    Qlay2.htm The document you are reading now.

    qlay2.ini QLAY2 configuration file. All emulator settings are within this file.

    Minerva198.rom: The latest Minerva ROM release.

    NFA.rom: Native File Access ROM. This ROM gives you access to WINx_ drives.

    readme.txt: Jan A Venema's original readme file, with some comments prefixed by >


  2. MDV Directory contains:
    1. Mdv1.mdv : A microdrive cartridge image that can be used as drive MDV1_
  3. WIN1 Directory contains:
    1. qlay.dir: A special file that contains current Qdos directory metadata in order to provide it to the NFA driver.
    2. Qsbb_bas: A widely-used SuperBASIC benchmark program.
    3. FT_bas: A small utility that helps you to find the correct speed settings for your emulation.

QLAY2-Full.zip: Windows 2000/Windows XP Source and Binary distribution:


In this distribution you will find all the files listed above, plus supplementary directories:

  1. QLAY2-Src This directory contains all you need to develop and compile QLAY2 source codes with Microsoft Visual C++ 6, or any compatible development systems. Just double click on QLAY2.dsw to launch the Visual Studio project.
  2. Original This directory contain all the original files from Jan A Venema's website. These were the starting point for this project.




(3) Configuration


Memory size:

The original QL shipped with 128 Kb of memory (131072 bytes, when typical business computers had half that), expandible to 640 Kb by design (like the original IBM PC) and up to 896 Kb by reallocating space intended for other hardware expansion. QLAY extends the address space of the QL's 68008 chip to allow up to 64 times the original amount of memory. Permitted values are:

  • 128 Kb
  • 640 Kb
  • 1Mb
  • 2Mb
  • 4Mb
  • 8Mb

QLAY2 will make use of virtual memory if there is not enough physical memory to satisfy this setting and the needs of the emulation itself (around 1.5Mb), but this may make the emulation rather slow and erratic, so it's wise to use a setting that can be fully accommodated by the physical memory free on your PC.


Screen Size: ((misleading? rename to window size?))

Sets the width and height of the emulated screen, in units of pixels on the host screen. Possible values are:

  1. 512 x 256
  2. 512 x 341
  3. 768 x 512
  4. 1024 x 683
  5. 1024 x 512
  6. 1024 x 768
  7. 1280 x 640
  8. 1280 x 1024

Whichever you select, the QL system will use its normal resolution of 512 y 256 pixels in MODE 4 and 256x256 in MODE 8. The difference is that QLAY2 may allocate more than one host pixel for each emulated pixel to fill the screen and preserve the proportions of the original display.

It recommended that you use a smaller resolution than your screen resolution, i.e: if your resolution is 640*480, use 512*256 for QLAY2, or if your resolution is 1280*1024, use 1024*768 for QLAY2. This leaves room on the screen for other windows, icons and the toolbar.


Keyboard country :

You can select the local Keyboard type for QL Emulation, so if you use a French keyboard select FR (the default as QLAY2 was developed in France ;)

Possible choices are:

  • US The original QWERTY PC keyboard layout, closest to that of the original QL).
  • UK Similar to US but with # and " symbols relocated to make room for the ú currency sign).
  • FR The French keyboard layout (AZERTY plus support for accents).
  • GE The German QWERTZ keyboard layout with added umlauts and Y and Z transposed.
  • IT The Italian keyboard layout.

Timing:

This tunes the emulation's internal timing. It was formerly known as 'Speed' but this was misleading as it does not change the emulation speed, but it sets the ratio of the emulated QL speed to that of an original QL so that processor-timed operations like key repeat are user-friendly on all the wide range of Windows hosts. The SuperBASIC date and time functions are not affected, as QLAY uses the PC's clock for those.

Internally this option controls the number of 68K instructions that should be emulated between internal 'ticks' every millisecond. It should be a relatively low value on a slow PC and high on a fast one. The exact value depends upon many details of the host system, but may be around 500 on a vintage 486 and 10,000 or more on a recent Pentium,

QLAY conducts all timing-sensitive functions with this tick, such as the frame blanking interrupt, mouse sensitivity, MDV timing and some internal housekeeping. The effect is easily seen: watch the cursor flash rate and compare that to a real QL.. If it`s too fast, increase this setting. If it`s too slow (a real QL blinks the cursor on and off again a couple of times a second) decrease this setting.

To help you find the right setting for your system, LOAD the mdv1_FT_bas utility and RUN it from inside the QLAY2 emulator. The program will tell you how much to multiply or divide the current value by.


Delay:

Emulation delay. This attempts to slow the emulator down to contend with programs, typically games written for the original hardware, that otherwise go too fast. Higher values slow down the emulation. It is quite difficult to set it correctly.

For example on a 1 GHz Pentium 3 you might set this Delay to 100 and Timing to 1200; those settings should give something near the speed of original QL. A setting of 0 means no delay; this may make the keyboard hard to use, because of runaway autorepeat, unless you have already set the Timing value correctly.

In some cases you may find games run too fast whatever the Delay setting. This is because the game derives its timing from original processor activity (which cannot be emulated exactly) rather than external interactions such as interrupts or key polling. See limitations.


ROMS:

The QL operating system QDOS was supplied in 48K of Read Only Memory (ROM) chips addressed at the start of QL memory, with provision for extra ROMs to extend Qdos and control add-on devices at later addresses. These add-on ROMs included floppy and hard disk control code, SuperBASIC toolkits (typically SuperToolkit2, sold by QJump and included in some disk system ROMs), compiler language extensions (for ProPascal, Metacomco C, etc) and Qdos accelerators like Speedscreen and Lightning.

If you have such a ROM in a cartridge that plugs into the back of a QL you can transfer the contents to QLAY by copying it to a floppy disk with:

SBYTES FLP1_MY_ROM,49152,16384

then copy that file to your PC hard drive with QLAYT (see Files) and specify it as one of the QLAY ROMs.

BOOT: is the main operating system, for example: MINVERVA198.ROM

ROM1: generally TK2.ROM at 0c000 (hex, 49152 decimal)

ROM2: generally NFA.ROM at 10000 (hex, 65536 decimal)

Original QL ROM cartridges were mapped at address 0c000; while most are relocatable, a few expect to load at just this address, so the load addresses are shown in the QLAY2 configuration window. If the ROM1 slot is empty please set the NFA.ROM to address 10000 (hex) in the ROM1 slot.


QL drives and device drivers

There's no point running the ROM for a QL disk controller (e.g. Miracle, CST or Rebel) without the relevant hardware, but it would be needlessly restrictive to have to use nothing but emulated microdrives and temporary RAM disks in QLAY2, so the emulator comes with its own host device access extensions, NFA (short for Native File Access) in a file predictably called NFA.ROM, which diverts attempts to access QL serial ports to the PC hardware, adds a PAR device for output to parallel printers, and a WIN device for access to up to eight simulated Winchester hard disk drives (WIN1_ to WIN8_).

Files saved from within the emulation to WIN drives are stored in PC subdirectories,, selected from the QLAY2 configuration window. Since QL directories contain extra information about file types (e.g. task carapaces) that Microsoft directories have no space for, an additional file 'qlay.dir' in each WIN subdirectory contains the extra Qdos directory information. Use the QLAYT support program to add files to 'qlay.dir' from outside the emulation (see Usage and files).

Microdrive emulation works differently. Each microdrive cartridge is emulated with a 128K file that contains all the information that would be on a real microdrive tape, in 256 half-K sectors (the maximum allowed by the microdrive format - real tapes had a somewhat lower capacity of around 200 to 220 sectors). There is no need for a separate directory file - the information is packed, with all the QL files, inside the .MDV file - but again you need the QLAYT utility (see Usage and files) if you want to read or write individual files inside the .MDV image without using the emulator. Again you can configure up to eight microdrives, MDV1_ to MDV8_, in the QLAY2 configuration window.


No mouse :

Unchecked by default, I'm still not sure on how to use it properly as I don't have any QL application to test it. Mouse hiding is toggled by pressing F12 while the emulator runs.


No ALT Key : (Recommended value is checked ).

This tick box is checked by default. As the AltGr key on the right of the PC keyboard space bar always emulates the QL ALT key you will not normally need the other ALT key under emulation, and this setting allows Windows to interpret ALT shortcuts. Press AltGr for QL ALT key functionality, or un-check this control to give thee emulated QL exclusive use of ALT as well, at the expense of Windows shortcuts.


GDI Full screen :

Let you use the emulator in a full-screen mode. This can slow down the emulation (though not much on a modern PC) and it lets you use the most screen space for the emulator.


MDV WIN:

This button opens a dialog box to configure the emulated WIN and MDV drive locations. QLAY2 now lets you use paths which contain space characters.


SAVE button:

This very useful button saves all your configuration settings in the QLAY2.INI file.


CANCEL button:

Cancels your most recent modifications to settings or cancels execution of QLAY2 if emulation is not yet running,


OK button:

This validates any modifications to your settings, and starts the emulation (unless it is already running).





(4) Usage


Launch the emulator by clicking on the QLAY2 icon in Windows. Check the settings and click on OK when you`re happy with them. A window will appear containing the same display that a real QL with your chose configuration would show. Press F1 to start in high resolution (QL Monitor) mode, or F2 for TV mode witth more colours but fewer, larger pixels. You can now type commands just as you would on a real QL.

DIR MDV1_ will show you the contents of the first microdrive. If there is a program called BOOT there it will run automatically after you presss F1 or F2. This is not the place to explain all of SuperBASIC - you will find copious documentation on-line.

Menus

QLAY2 has menus above the Qdos display which allow you to set the language for interface messages (in Windows, not inside the emulator), scale the Qdos display to a different preset size on the fly, call up the configuration screen, reset or quit the emulator. The menus can also call up help from the internet, and let you update the record of the contents of the QL's drives, for when another Windows program has changed them from outside the emulator.


How to quit

If the emulation is running you can quit QLAY2 by pressing the ALT+F4 keys, or from the menu by clicking on QL/Quit. To reset the emulated QL, as if you'd pressed the button on the right side of a real QL behind the microdrives, select Commands/Reset.


File transfers with QLAYT

QLAYT is one of the QLAY support tools.

This command-line utility provides a set of tools and general support functions for the QL emulator. The tools are needed because the QL and it's operating system QDOS have some peculiarities that do not mesh well with Windows. Most obvious difference is that QDOS files consist of two parts: a header block and the actual data file. To allow transparent access from the emulator program to the native file system it's necessary that the file header be stored separately. The QLAYT program takes care of inserting into or extracting files from a 'qlay.dir' directory file. It knows about QL file types and dataspace fields. It will also import and export files from other QDOS compatible systems and QLAY's MDV file format.

If you copy any file into a microdrive image or WIN directory, or delete one, while the emulator is running you should select the Commands/Disk change menu item to flush the emulated QL`s record of the contents of its drives, so that the change is recognised inside the emulator.

Read more about QLAYT in the file 'qlayt.man', which is part of the original qlayt.zip archive (see links).

Another option is to use the special QLAY version of QLTOOLS, a portable utility intended to convert files to and from Qdos floppy format. QLTOOLSQ is a modified version of the earlier QLTOOLS that allows you to copy all files from a QL floppy in a PC directory. The files can then be used in QLAY directly. Read more about QLTOOLS in the manual files in the qltoolsq.zip archive.




(5) Performance


Emulation speed depends on many factors. CPU performance has the biggest impact, but the special needs of QDOS are also important; for instance memory access to the emulated screen is slower than normal memory access. Short loops in the 68000 code are executed much faster than large code segments; this due to the level 1 and level 2 caches that the CPU of the PC has. A simple SuperBASIC benchmark (QSBB_BAS) shows how many print, function and string manipulation loops can be executed within 20 seconds. Higher numbers indicate faster emulation.

Native 68k computers

System/CPU      print  function  string    Configuration

QL original       980     840     1100     128k, JS-ROM
SandyQL          1080    1040     1360     512k, Floppy, Par. Port
GoldCard         2580    4280     5680     16 MHz 68000 QL accelerator
Super GoldCard   5680   10260    13820     24 MHz 68020 QL accelerator
Amiga 68040/25   9480   16540    23000     AmigaQDOS (JS/3.24)
QXL-20          14300   27900    70640     Running SMSQ not QDOS!
Amiga 68060/50  10480   48750    73880     AmigaQdos 3.24 Beta (Blitter)

Older 68K emulators

System/CPU      print  function  string    Configuration/Emulator

486/DX2-66        660     980     1300     QLAY081 -d2 (MSDOS)
486/DX2-66       1080    1360     1820     QLAY082-d2 (MSDOS)
486/DX2-66        920    1440     1840     QLAY083 -d2 (Linux)
Amiga A1200      2500    1800     2000     060/50 (UAE emulating 68K!)
Pentium/150      2360    3680     4960     QLAY082 (MSDOS)
PentiumPro/200   6000    8000    11000     QLAY082 -f2900 (MSDOS)
Pentium/200      5260    9340    12660     QLAYW087 size 1, 16k cols
Pentium/150      7120   10840    28120     QPC running SMSQE not Qdos!

QL2K 0.x (the basis for GPL QLAY2) and QPC2

System/CPU      print  function  string    Emulator configuration

AMD K6/2-500     7220     9160    13100    QL2K -f2800 Win98, G400 GDI
AMD K6/2-500     7000     9040    13060    QL2K as above via Direct X
PentiumIII/1000 27920    49460    65740    QL2K -f15000, Min 1.98, GDI
PentiumIII/1000 29240    48500    65280    QL2K as above via Direct X
PentiumIII/1000 33040    93620   221680    QPC2 running SMSQE

Notes: The print test timing is dominated by Scrolling. Multi-processor emulators (e.g. QXL, Amiga Qdos) may save time by not rendering every update from the QL screen to the host screen memory. SMSQ[E] does not run interpreted SuperBASIC so its function and string times are for compiled code. When compiled code is run on both platforms, Qdos performance is proportionately several times faster. Benchmarks are interesting but the best tests of usability are to run real programs, not one-dimensionally contrived ones!

The speed of QLAY2 is also limited by the quality of the C compiler used to translate its source. An experimental build with the Intel compiler (not distributable because of licence issues) was 19%, 12% and 26% faster than the Visual C++ 6 version on the print, functions and strings benchmarks, respectively. So the speedup on core instruction throughput is only 12% (FT_BAS also sugested a 13% boost) but the Intel compiler's better cache and data handling gives a greater boost on the tests with a larger data set (e.g 26% on the string test is probably explained by smarter optimisation and cache awareness). This was with Minerva 1.98 on a 1600 MHz Pentium IV 1600 with GForce 2ti graphics in a 512 x 256 pixel window on a 32 bit desktop.


(6) Inner workings


QLAY2 comprises three parts: 68000 emulation, QL hardware emulation and interfaces to the Windows operating system.

After initialization and evaluation of the settings, the 68000 emulation starts. It will read one instruction, decode and execute it. Part of execution can be a read or write access to memory. If it is an access to the QL I/O area starting at 0x18000, QLAY2 will execute the necessary QL hardware emulation directly. E.g.: read a bit from the IPC (8049). If that implies, for instance, reading a keyrow, QLAY2 will execute a keyboard request in the Windows Linux interface part. Accesses to the QL ROM area at lower addresses are automatically write-protected.

The screen is emulated by detecting changes to the 32K (or 64K, for Minerva twin-screen mode) area at the beginning of emulated QL RAM and writing corresponding data to the host window, de-interleaving thee QL colour data and using Windows routines to convert pixels to the host format.

After each executed 68000 instruction, QLAY2 will check whether there is internal housekeeping to be done. This is when exceptions, interrupts, and timing events like the millisecond tick are handled. QLAY2 will then proceed with the next instruction according current value in the emulated program counter. QLAY does not patch any ROMs and does not access any of the QDOS system variables directly.

This way any program, PROM or even a complete QDOS replacement (such as Minerva or Tyche) can be executed by QLAY2, as long as it assumes the hardware, I/O and memory map of the original Sinclair QL.





(7) Known limitations & future plans


QLAY2 does not currently support QL Sound (either via BEEP or QLSSS extensions).

The implementation of delay, to make the emulator run at the same speed as an original QL, is hard to tune and does not work for all programs. It would be better if the speed could be set as a percentage of that of an original QL - with other CPU time released to the host - or unlimited with QLAY2 competing with other programs without any arbitrary cap on speed. The US QL Users Group NASQLUG has offered a small fee to anyone who can solve this problem. Contact Al Boehm for details.

This version of QLAY2 is open-source and freely distributable. You are encouraged to make your own version and to add any features that you wish for.

The downside of the GPL is that it does not permit the inclusion of non-free components with a software project, or a registration scheme - such as cardware. Consequently the original work on QLAY2, first promoted as QL2K under a non-GPL licence requiring free registration for updates, has spawned the development of QL2K version 1.0, a new QL emulator with extras beyond those possible under the GPL ((including custom ROMs and other extensions).

The future of QLAY2 depends on the interest of all users and their willingness to work together to extend it. Like other projects released under GPL, it could go anywhere, everywhere, or nowhere. The future of QL2K, by contrast, depends on its developer, Jimmy Montesinos, and the encouragement he receives from people who register their interest with him.

QLAY2 does not support SMSQ/E, the operating system developed by Tony Tebby, author of the original Qdos. Some programs for SMSQ/E may work on QLAY2, but this is not guaranteed; in many cases they will require extra files, which may be commercial products. QLAY2 emulates the QL, not later products billed as 'QL-compatible'. Many of those don't run on a real QL either, becase they depend on non-Sinclair extensions to the original.





(8) Frequently Asked Questions, and answers


(Q) QLAY2 runs too fast on my machine! How do I slow it down?

(A) You need to adjust the Delay and Timing settings to suit your PC and the QL programs you want to run. There are too many possibilities for this to be done for you automatically, sorry.


(Q) How do I use windows larger than the original QL screen resolution?

(A) You can't; QLAY2 emulates the graphics of the original QL, in resolution and colours. Changing this would stop a lot of original QL software running, and make the output from other programs, such as the Psion suite, hard to read on a modern display. However there are other emulators that support larger Qdos windows, such as UQLX (originally for Unix, freely distributable, now available for Linux, Mac OS X, and Windows via Cygwin) and QPC, a commercial Window package, with a free crippled demo available - though this runs SMSQE rather than the original Qdos, further limiting its compatibility. You may also be able to track down a QXL card - this is an ISA card with a genuine 68040 processor to run QL programs, and drivers for devices on a PC host; however display updates are slow, the operating system (SMS-Q) is not fully Qdos compatible, and software emulation on modern PCs may outperform the 20 or 25 MHz 68040.


(Q) How do I transfer programs from my original QL to QLAY2?

(A) If you have the programs on a QL floppy disk, you need to use QLAYT to read the disk and copy the files to one of the WIN directories that QLAY2 uses. If your programs are on microdrive cartridge you need to get them some other way, as only a real QL can read QL tapes. You could use a serial connection between the QL and PC, running matching terminal software (e.g. Kermit or Xmodem) at each end, or copy between the original QL and the emulator; set the transfer speed to 9600 baud (the QL default, and the highest rate it can comfortably handle even with hardware handshaking) and connect the serial ports as follows (assuming you use SER1 on the QL and a 9 pin D connector at the PC end):

  • RXD QL pin 3 to PC pin 3
  • CTS QL pin 5 to PC pin 4
  • GND QL pin 1 to PC pin 5
  • DTR QL pin 4 to PC pin 8
  • TXD QL pin 2 to PC pin 2

(Q) How do I use colours not available on the original QL?

(A) QLAY2 emulates the graphics of the original QL. Adding more colours would stop many original QL programs running. However there is a commercial emulator, QPC, that supports extensions to the original QL colour scheme, through the Qdos-like (but not fully compatible) SMSQ/E operating system. You could also run this with original QL hardware and up to 256 colours, using an QL expansion Aurora card, or replace your x86 PC motherboard with an ATX-format Q40 or Q60 superQL card, with up to 16 bit high colour support; both those offer Classic Qdos compatibility in addition to extra colours via SMSQ/E.




(9) References


This documentation was written by Simon N Goodwin, based on information provided by Jimmy Montesinos and Jan A Venema. It was edited in Amaya, the free HTML editor produced by W3C, the philanthropic consortium that creates and maintains Web standards.

Thanks are also due to Raphael Zhou for portions of the DirectX/Windows code, Bernd Schmidt, Giuseppe Zanetti and many others. Feedback is most welcome - please email all comments about QLAY2 to Jimmy Montesinos You can write in English, French or Spanish. Bear in mind that since QLAY2 is open source, requests for new features are likely to gain the time-honoured riposte, "use the source, Luke." But it is always good to hear from users of freely-distributed software - without them there would be no point in sharing such programs and going to the considerable extra effort of publishing the results.

If you search online for 'Sinclair QL' and 'Qdos' you are likely to find hundreds of pages of information about the QL and its emulators. Here are a few links to get you started:


The latest QLAY2, QL2K and related files

A large collection of QL files and links

Another large collection of QL files

Amaya HTML editor and Browser

The Free Software Foundation, home of the GPL

The original versions of QLAY, and relevant documents and support programs

Back to the top of this document

Written by Simon N Goodwin, on 2004-11-07.