• Getting started
  • Introduction
  • Requirements
  • Installation and using other QL ROMs
• Features
  • Current features
  • Future improvements
  • Overview
• Files
  • QDOS Files
  • Access to QDOS formatted floppy disks
  • Access to QXL.WIN files
• Devices
  • Ram disk
  • Sound
  • Mouse support
  • Real time clock
  • Serial ports
  • Parallel ports
• Configurations
  • The QL Configuration dialog
  • Configuration files
  • Installing 16K expansion ROMs
• Appendices
  • Appendix I - Format of .QCF files
  • Appendix II - Format of QL files stored in the PC file system
  • Appendix III - Q-emuLator support site
  • Appendix IV - Address for feedback

Q-emuLator is a software emulator of the Sinclair QL home computer.

Originally written in 1994/95 for the Mac OS, Q-emuLator was ported to Windows 9x/NT three years later, and is still being improved.

Q-emuLator emulates the QL processor (the Motorola M68008) and redirects the basic QL I/O (video, keyboard, mouse, mass storage, sound, parallel and serial ports) to the PC hardware. Putting a QL ROM in this virtual environment makes it possible to run QDOS without its noticing that it's not running in a QL black case.

Q-emuLator runs like any other applications in the Windows environment, without taking over all the machine. You can switch to other active applications, and Q-emuLator can also run (more slowly) in the background.

A 486 or better system with Windows 95, Windows 98 or Windows NT 4 or later.

Sound emulation is available only if DirectX is installed on your system.

No special installation is required before running Q-emuLator: run the program and start the emulation by choosing "Start" from the ‘QL’ menu, or just by clicking over the QL picture!

Have fun!

The emulator needs a file with a 48K QL rom image to work, but such a file is already provided with Q-emuLator. The provided ROM is a Minerva 1.89 ROM, compatible with the original Sinclair ROMs, but faster and with more features. Minerva version 1.89 and earlier is public domain. It duplicates all standard QL commands and firmware features. A disk version of an up-to-date Minerva, with disk manual documenting extra features (currently 1.97 with 1.99 in preparation) is being compiled for sale. Enquiries to Tony Firshman, TF Services, 29 Longfield Road, TRING, Herts, HP23 4 DG, UK. Tel: 01442-828254. Fax: 01442-828255. Email: tony@firshman.demon.co.uk.
Other QL ROMs are not included in the Q-emuLator’s package for copyright reasons. If you like, you can find a Sinclair ROM image on Internet (follow the link from the ‘Q-emuLator for Windows 9x/NT’ www page), or you can create it on your QL with the "SBYTES FLP1_QL_ROM,0,49152" command. This command doesn't work on (Super) Gold Card systems, as you get a modified ROM image instead of the original one. Therefore, if you have a (Super) Gold Card, you must disconnect it before using the SBYTES SuperBASIC command and copy the ROM to a microdrive, then from there to a floppy after reconnecting the card.

Once you have the ROM file on a QDOS floppy disk you can read it from Q-emuLator on your PC. Follow these steps:

1. Launch Q-emuLator.
2. Insert the QDOS floppy disk with the ROM file image in the PC drive (A: or B:).
3. Click on the gray rectangle representing the left microdrive slot (below the window with the QL picture); choose ‘QDOS Floppy Disk’ from the pop-up menu that appears, and choose either ‘A:’ or ‘B:’ from the sub-menu, depending on where you inserted the floppy disk. Q-emuLator looks at the disk and displays its name on the microdrive slot.
4. Choose the ‘Install QL ROM from disk...’ command from the ‘File’ menu. This instructs Q-emuLator to copy the ROM image in its directory and use it for emulation. (Warning: this command requires Q-emuLator to reside in a writable directory and not on CD-ROM or other read-only media).

What if you would like to install a new ROM image that is already on your PC, instead? (For example a ROM that you downloaded from Internet.) In this case you need to point Q-emuLator to the ROM image: go to the ‘QL Configuration’ dialog (Choose ‘QL Configuration...’ from the ‘QL’ menu), click the uppermost ‘Select...’ button and find the ROM image file in the file selection dialog that appears. Done! Close the ‘QL Configuration’ dialog by clicking the ‘OK’ button.

• original QL with up to 16M of RAM
• supports Sinclair and Minerva ROMs
• up to two additional 16K ROMs
• up to 8 microdrives, each mapped to a Windows directory, a floppy disk drive or a QXL.WIN file
• access to QDOS formatted floppy disks
• support for subdirectories
• original QL screen (mode 4, mode 8 without flash) and second screen (used by some games and by the Minerva ROM)
• should be compatible with any PC keyboard layout
• built-in ram disk
• sound
• mouse support (when the Pointer Environment is installed)
• serial ports
• parallel ports
• QL and Q-emuLator settings can be stored in files and later retrieved
• QL and Q-emuLator settings easily editable through a user-friendly interface
• acceleration of some QDOS graphics routines

Some features of the Mac version of Q-emuLator have not been ported to Windows, yet:

• format QDOS floppy disks
• faster graphics
• faster emulation

The program main window has two parts: the upper part shows the QL display, and the lower part the microdrives.

You can attach a Windows directory, a disk drive or a QXL.WIN file to a microdrive slot by clicking in it and selecting a command from a popup menu.

To transfer files from your QL system to the PC you can use QDOS formatted floppy disks and read them from Q-emuLator.

Executable files (and some other kind of files) are stored on the PC in a special format containing QDOS-specific information.

The compressed "FileUtil_zip" archive contains some utilities that can be used on a QL, should you ever need to transform files with a QL between QDOS and Q-emuLator for Windows formats. The transformation is automatically carried over for you on your PC when you use Q-emuLator to copy files between a Windows directory and a QDOS formatted disk. To translate (on a QL) QDOS files to the Windows format you can use the "QLToWin_exe" utility. The archive contains two other utilities: "MdvToWin_exe" translates to the Windows format files stored on copy protected microdrives, while "WinToQL_exe" translates back from the Windows format to the QL's.

Note: most non-executable files don't need to store extra QDOS information; therefore they have the same format both in the QDOS and in the Windows environment.

You can attach QDOS formatted floppy disks to microdrive slots. When you click on a slot you can choose to attach it to a Windows directory, to a QXL.WIN file or to a floppy disk drive with a QDOS formatted disk in it, or you can empty the slot if it was already filled. Note that you access each of the eight virtual MDV slots with all of the MDV, FLP and WIN device names, regardless of what type of medium is attached to a slot.

Note: FLP1 and FLP2 refer to slot 1 and slot 2, NOT to drive A: and B:. Of course, if you like you can attach drive A: to slot 1 and drive B: to slot 2, but you are not required to do so.

Note: When you swap QDOS disks in an attached drive you should tell Q-emuLator about the change by clicking on the slot and choosing again ‘QDOS Floppy Disk’ and either ‘A:’ or ‘B:’.

The FORMAT command is not supported, yet.

In this manual the term ‘QXL.WIN file’ refers to the DOS files used by the QXL (a hardware QL emulator for DOS) and by QPC (a software QL emulator for DOS) to store the emulated QL filesystem. These files are similar to images of QL hard disks stored in a single DOS file.

Q-emuLator allows you to attach QXL.WIN files to microdrive slots to access their content. However, Q-emuLator can't write to or alter QXL.WIN files in any way.

Q-emuLator provides a built-in ram disk device driver. If you use it instead of loading a QL software ram disk driver (like 'ramprt') you will gain in speed.

The device name is 'ram' (but you can change it in the ‘QL Configuration’ dialog) and it has eight drives, 'ram1_' through 'ram8_'.

You can use the ram disk both in dynamic and static mode. In dynamic mode you can freely copy files to the ram disk and more ram will be allocated for it every time it is needed, up to filling the whole QL's memory. In static mode you assign a fixed memory amount to each drive, by formatting the drive and specifying the requested number of blocks as the medium name: for example, the command ‘FORMAT ram1_400’ assigns a fixed amount of 200K (as each block is 512 bytes long) to the first ram drive.

To erase a whole ram disk drive at once use the ‘FORMAT’ command without specifying a file name: for example ‘FORMAT ram4_’.

In static mode all the memory needed by the driver is allocated when you format the drive. This means that you are sure that no other job can take away that memory before the ram driver needs it, but also that the ram driver is not allowed to use more memory than the amount specified.

While dynamic mode is easier to use, you are encouraged to use static mode whenever it is possible, because it is a lot faster: in dynamic mode the driver has to call emulated QDOS routines every time that it wants to allocate or release a block of memory, whereas in static mode all the memory is allocated at the beginning and QDOS is no longer called.

The ram disk device driver is not level 2 (i.e. it doesn't support subdirectories), and there are no SuperBASIC extensions to modify its behaviour (for example there is no RAM_USE keyword).

If you prefer to use another ram disk driver (although it will be slower, as it has to be emulated), just disable the built in device driver in the ‘QL Configuration’ dialog, and install your driver by installing an add-on rom containing it or by loading it from your boot file.

Note: For a ram disk drive used in dynamic mode, the DIR command reports a negative number of free sectors and zero total sectors. Zero is the number of sectors statically allocated to the ram drive (none if in dynamic mode). The number of free sectors is calculated as the total number of statically allocated sectors (zero for a dynamic ram drive) minus the number of used sectors, and it is therefore negative for a dynamic ram drive. Consider for example a ram drive whith 100 sectors full of data; if in dynamic mode, DIR reports -100/0 free sectors; if the ram drive was statically formatted with 400 sectors, DIR reports 300/400 free sectors.

QL 'BEEP' emulation is available if DirectSound (a DirectX component) is installed on your system.

Sound is on by default. You can turn it off through a switch in the ‘QL’ menu.

There is still a problem with sound emulation: a click is sometimes heard if a BEEP command is issued when another BEEP command is still playing.

Mouse emulation is provided under the Pointer Environment through a special mouse driver, named ‘MacMouse’.

To take advantage of it, install the ‘MacMouse’ mouse driver (included in the Q-emuLator package) JUST AFTER having installed the Pointer Environment (that is, the ‘PTR_GEN’ extension, not included in the Q-emuLator package).

To install the mouse driver use the following SuperBASIC command:

a=RESPR(1024):LBYTES mdv1_MacMousexy,a:CALL a

or, if Toolkit II is installed:

LRESPR mdv1_MacMousexy

The command assumes that the ‘MacMousexy’ file (replace x and y with the version number: for example ‘MacMouse11’ for the mouse driver version 1.1) is in the first Microdrive slot.

Once the mouse driver is installed, any active QL mouse cursor will be moved instead of the Windows pointer when it is over the QL display window (provided that the QL display window is the frontmost window).

Note that as the QL cursor follows the Windows’ one, its speed is independent from any settings in the QL environment; on the PC, the mouse speed can be set in the Mouse Control Panel.

Unlike the left and right mouse buttons, the central button is not emulated.

The QL had a real time clock, but you had to set it every time you started the computer, because there was no battery to keep it working while the computer was powered off. On Q-emuLator there's no need to set the QL real time clock, as the current date and time is read from the PC clock every time the program starts.

Note: changing the QL clock settings doesn’t affect the PC clock.

SER1 through SER4 are linked to COM1: through COM4:.

To open a serial port I/O channel you specify the device name and options with the following syntax:

SERnpft

n, p, f and t represent optional characters that you can add to the name to specify the port number and other parameters. The following table shows the possible values for these parameters:

You can omit any of the n, p, f and/or t parameters (the driver assumes default values), but if you specify them you can’t invert their order. For example you can write SERHZ, but not SERZH.

The baud rate can be set to most of the usual QDOS values, plus many PC values not originally supported by the QL, up to 256000 baud, if your serial port supports it. For the higher transmission rates, however, it is recommended to use hardware handshake, as otherwise the emulated QL could be too slow to handle the data without losses.

The TRA command, present in JS and later ROM's versions, is not implemented. This command allows to specify a character translation table, but usually communication programs don't use this feature.

The Minerva and SMSQ extensions to the serial driver are not supported.

You can access to the LPT1: and LPT2: parallel ports of your PC through the PAR1 and PAR2 QL devices.

The driver supports bi-directional ports.

To open a parallel port I/O channel you specify the device name and options with the following syntax:

PARnt

n and t represent optional characters that you can add to the name to specify the port number and other parameters. The following table shows the possible values for these parameters:

You can omit the n and/or t parameter (the driver assumes default values), but if you specify them you can’t invert their order. For example you can write PAR2Z, but not PARZ2.

You can disable the QL parallel device or change its name in the ‘QL Configuration’ dialog.

The term configuration denotes a set of Q-emuLator's preferences and of emulated QL's settings. Only one configuration can be active at any time. You can change some configuration settings through menus. For example you can change the QL's RAM amount through the ‘RAM’ menu. All the other settings that can't be changed through menus are editable in the ‘QL Configuration’ dialog

To recall the ‘QL Configuration’ window, choose the ‘QL Configuration’ command from the ‘QL’ menu.

The ‘QL Configuration’ window has five pages, named ‘ROMs’, ‘Devices’, ‘Serial ports’, ‘Graphics’ and ‘Start-up’. You access each page by clicking on its label in the top part of the window.

The ‘ROMs’ page allows setting the names and locations of the QL ROM images to be used by the emulator. File paths can be absolute or relative. In the latter case they are relative to the directory containing the Q-emuLator application.

The ‘Devices’ page allows to enable or disable devices not present in the original QL (for example, the ram disk) and to change their names. Device names can be 1 to 9 characters long.

The ‘Serial ports’ page defines which PC COM port to attach to each of the four QL SER devices available (SER1 to SER4). A QL SER device can be disabled by setting its output to ‘None’. You can route more than one QL SER device to the same COM port, provided you don't use all of them at the same time.

The ‘Graphics’ page allows to enable or disable acceleration of some QDOS graphics commands (cls, scroll, pan, block, mode). Enable graphics acceleration for maximum speed, disable it when you run emulation at original QL speed to play games or in case graphics acceleration turns out to be incompatible with your QL software.

The ‘Start-up’ page allows to enable or disable two Q-emuLator preferences:

• If the ‘Skip QL power-on memory test’ option is checked, the QL will not execute the memory test at start-up. The memory test is the first thing that you see when you power on or reset a real QL and is responsible for the coloured dots that fill the screen before the F1/F2 prompt. Checking this option skips this test, so you go directly to the F1/F2 prompt. As a result, the QL's start-up is quite faster, expecially with large QL RAM amounts.
• The ‘Open QL session at start-up’ option instructs Q-emuLator to immediatly start a QL emulation session when starting or when reading the configuration from file.

Configuration files store the emulated QL’s configuration and some other Q-emuLator’s settings.

Configuration files have the ".QCF" suffix.

To start Q-emuLator with the settings specified in a particular configuration file, double-click its icon, or drag it onto the Q-emuLator’s icon. If you start Q-emuLator without opening any configuration file, the program uses a default configuration. If you want to define your personal default configuration, you can do it by saving the desired settings into a configuration file named "default.qcf" and placing it in the Q-emuLator’s directory.

You load and save configuration files through commands in the Q-emuLator’s ‘File’ menu.

A 16K expansion ROM can also be optionally used by the emulator. If a 16K expansion ROM is insatalled on your QL, you can get an image of it with the "SBYTES FLP1_BACK_ROM,49152,16384" command. To tell Q-emuLator to use the ROM image, copy it to your hard disk, go to the ‘QL Configuration’ window, press the second ‘Select...’ button (that on the ‘Back ROM’ line) and select the ROM image on your hard disk.

A configuration file is a text file used to store the emulated QL’s configuration and some other Q-emuLator’s settings.

Configuration files are quite similar to Windows ".INI" files: each line of text describes a different preference or setting, identified by a keyword. The format of each line is:

Keyword = Value

You can, for instance, set the QL’s ram amount to 640K with the following line in a configuration file:

Ram = 640K

Configuration files have the ".QCF" suffix. Unlike ".INI" files, you can have multiple configuration files, and you can store them anywhere you like.

Follows a description of the keywords you can find and use in configuration files. For each keyword the following table shows the possible values, their meaning, and the default value. The last column shows how you can alter the setting from within Q-emuLator.