QLAY	QL emulator

Version 0.82, 19970822

1. Copyrights

This program is freeware. You may do with it whatever you want for personal use.
Copyright Jan Venema.

Permission is granted to redistribute this program free of charge, provided it 
is distributed in the full archive with unmodified contents. No profit beyond 
the price of the media on which it is distributed is made.

There are no warranties of any kind for this program. If you use this program,
you do so at your own risk. The author is not responsible for any damages 
that might result from using this program.

The QL ROMs and PSION programs are (C) Amstrad Plc. Distribution and use on
a non-commercial basis is allowed.

2. Overview

Design intent of QLAY is to fully support the Sinclair QL hardware.
All original I/O is emulated. There is no focus on adding emulation 
for hardware extensions like floppy or hard drives, video cards etc.
One exception is made: Native File Access allows access to the DOS 
file system (DOS). With these hardware components emulated, all original
QL/QDOS software can be executed on QLAY. Newer OSes like SMS are thus
supported as long as they run fine on the original QL hardware.

QLAY emulates the hardware of a Sinclair QL with 128, 640k or upto 
8 Mbyte of memory.
It works with all known ROMs and ToolkitII ROMs.
In this version the following is emulated:
- Microdrives as basic file I/O. Up to 8 can be used.
- NFA. Access to MS-DOS file system as WIN1_.
- Various screen sizes are supported to display in QL mode 256 and 
  mode 512. Emulates: blank screen and 2nd screen bank. (Alt Tab).
- Keyboard via IPC.
- Mouse via memory mapped I/O.
- Emulation speed control and delay.
- IPC Beep sound emulation.
- Large memory: up to 8 Mbyte.
- Full MC68000 emulation, including *all* exceptions and trace.
- Place ROM cartridge files anywhere in memory.

3. Using QLAY

3.1 Requirements

- 386 CPU
- 4MB of memory
- 1MB of harddrive space for program and additional swap space 
  depending on emulated memory size.
- Any of the following: DOS, Win-3.x, Win-95, OS/2, DOSEMU (linux)

QLAY emulates comfortably and faster than the original QL on a 
486/DX2-66MHz system with 16Mbyte memory.

3.2 Installation and use

Unzip the archive into a suitable directory.

To start use:
	QLAY
	After initializations the familiar Sinclair logo should appear.
	Press F1 or F2 and off you go!

	QLAY -1emptydsk.mdv
	All mdv1_ operations will be made to the native DOS file.

	QLAY -1Rexample.mdv -2emptydsk.mdv
	mdv1_ is write protected, mdv2_ can be written to.

	QLAY -h 
	Gives short help on other options.

See section 3.3 for more options.

Special key combinations:
     End QL emulation.
     Refresh screen (when switching between Windows
			  or OS/2 and QLAY DOS box).

The microdrive file format is based on what is created during a FORMAT
command. It support 254 sectors of 512 bytes: almost 128kbytes. 
The native OS MDV files have to be exactly 174930 bytes long.

QLAY can be used from within a DOS box in Windows-3.x, Windows-95, OS/2
or dosemu of Linux. Via a 'PIF' or 'Shortlink' it can be started directly
from the graphical interface. A sample 'dosemu.conf' file for Linux is
included.
In addition, QLAY can be run from DOS, when the PC is booted in DOS.

QLAY requires a DPMI server. Windows has that support built in. 
Under DOS it requires the 'CWSDPMI.EXE' included in the zip archive.

3.3 Command line options

All command line options can be placed in a configuration file: 'qlay.rc'.
Simply place each command line option on a separate line. QLAY will
use these settings at emulation start.

-d num
Various screen sizes are supported. Mode 1 gives best aspect ratio, but is
slower than other modes. Modes 6 and 7 emulate correct aspect ration via 
a high resolution screen on high-performance PCs.

-o
Use the 'old' graphics driver. QLAY082 has new, faster drivers, but not
tested on different graphics cards. Old driver may be more stable.

-m num
Memory size can be chosen: 128k, 640k, or 1M up to 8 Mbyte.
Default is 640k. num=0: 128k, num=1: 1M, ..., num=8: 8M.
(QLAY082: option -s is not supported any longer)

-r file
Use 'file' as BOOTROM. Always loaded at address 0. As default QLAY will 
use file 'ql.rom'.

-c address@file
Expansion ROM files, like cartridges and I/O expansions, can be placed 
flexibly in memory. For each ROM a separate '-c ...' is needed. The file
will be loaded, starting at specified (hex) address. 
E.g.: toolkit and nfa: QLAY -r js.rom -c c000@toolkit.rom -c c0000@nfa.rom 
ROMs are write protected. QDOS limititions apply to address range.
On a real QL the ROM cartridge port is mapped at c000.

-f speed
Emulation speed control. This controls after how many instructions the
QLAY internal 1msec 'tick' should occur. With this 'tick' QLAY emulates
all timing sensitive functions: 50Hz interrupt, mouse sensitivity, BEEP
sound generation, MDV and some internal housekeeping.
The default value is '-f 400'. This emulates the 50Hz interrupt rate
about right on a 486/DX2 66MHz machine. On faster machines a larger value
should be used. The effect is easily seen: watch the cursor flash rate
and compare that to a real QL. 
The SuperBasic program 'ft_bas' helps finding the proper value for -f.
This option does not change the emulation speed, only the interrupt rate
is controlled.
NOTE: date and time are not affected. QLAY uses the PC's clock for those.

-w delay
Emulation delay. Makes QLAY emulate slower for e.g. a game that plays 
too fast. The emulation gets slower with higher values of the -w 
option. The default value is '-w 0' for undelayed emulation speed.

3.4 NFA support

Native File Access is supported via a small ROMable piece of QL code in
file nfa082.rom.

Start emulation with: QLAY -rjs-nfa.rom [options]
    QLAY -r js.rom -c c000@nfa082.rom

The boot screen shows that NFA is now available.
Type 'dir win1_' to find MSDOS files available via NFA.

When using a toolkit ROM or other ROM:
    QLAY -r js.rom -c c000@toolkit.rom -c c0000@nfa082.rom

For NFA to work properly a 'qlay.dir' file must be present. It must 
contain a 64-byte QDOS file header for each MS-DOS file that needs
to be accessed in QLAY. The 'qlay.dir' file can be created and updated
with the 'qlayt' file conversion tool. See section 5.

The free/good sectors numbers refer to the directory file only. Per 8
files one sector is used.

In QLAY 0.82 only WIN1_ is supported; only files in the local directory
are supported. Upto 159 files. Expect improvements in a next version.
There is little error checking.

NFA supports one extra SuperBasic command: win_use. 
To replace all FLP1_ or MDV1_ accesses with WIN1_ in existing programs: 
'win_use flp', or 'win_use mdv'. 
To get the WIN1_ device back : 'win_use'.

3.5 Mouse

QLAY can emulate a mouse for use with Pointer Environment. The mouse 
driver must be present before emulation starts. If no mouse driver is 
found mouse support is skipped. This should normally be no issue at all
when starting from Windows or OS/2.
The mouse is supported via memory mapped I/O. 

4.1 Development

QLAY was developed using DJGPP. I plan to make all sources available
when the program is in Rev 0.90. Other OSs should be easily to port to.

Not supported yet:
SER1_,SER2_,NET_,FLP_.
Keyboard country configuration file.
WIN1_BOOT file not recognized.

4.2 QLAY, how does it work?

QLAY consists of 3 parts: 68000 emulation, QL hardware emulation and
interfaces to the native operation system (DOS). 

After initialization and command line option evaluation 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, QLAY will execute
the necessary QL hardware emulation directly. E.g.: read a bit from
the IPC (8049). If that implies e.g: reading a keyrow, QLAY will execute
a keyboard request in the DOS interfaces part.

After each executed 68000 instruction, QLAY will check whether there
is internal housekeeping to be done. This is when exceptions, interrupts,
and timing events like the 1msec tick are handled. 
QLAY will then proceed with the next instruction according current value
in 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 (SMS?) can be executed by QLAY. As long as it assumes
the hardware, I/O and memory map of the original Sinclair QL.

4.3 QLAY, how fast is it?

Emulation speed depends on many factors. CPU performance has the biggest
impact, but also what QDOS does: 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 Intel CPUs have.

A simple SuperBasic benchmark (qsbb_bas) shows how many print, function
and string manipulation loops can be executed within 20 seconds.
Higher number is faster.

CPU		print  function	string
QL (68008)	800?	900?	1100?	Unreliable, see below.
486/DX2-66	1080	1360	1820	QLAY082	(-d2)
486/DX2-66	660	980	1300	QLAY081 (-d2)

Anyone has exact numbers for the original QL? My QL keyboard is
broken :-(  I'd be interested in any info on getting it replaced.


5. Tools and manual

QLAY is supported by the QLAYT tools for file conversion. From other
sources 'qltools' is available to convert files to/from floppy format.

5.1 QLAYT

QLAYT provides a set of tools and general support functions for the QL
emulator QLAY. The tools are needed because the QL and it's operating
system QDOS have some pecularities that do not match well with most
other Operating Systems. 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 needed
that the file header is stored separately.

The QLAYT program takes care of inserting or extracting files into/from
a directory file. It knows about datasize fields. And will import and
export files from other QDOS compatible systems and QLAY's MDV file format.

Read more about QLAYT in the manual file 'qlayt.man'.

5.2 QDOS introduction

An introduction in QDOS and SuperBasic can be found in file 'qdos.man'.
This file was take from another QL emulator. It may be incomplete and
contains errors. Has anyone better information?

6. Credits

The QLAY M68000 emulation code is derived from UAE, an AMIGA emulator
done by Bernd Schmidt and many others.

7. Revisions

7.1 Bugs

If QLAY fails, crashes or worse, there may be a hint in the 'qlay.log' file.

Some known bugs (082):
- Keyboard emulation only supports US keyboard.
- FLASH (mode 8) is not supported.
- MDV access may give 'bad medium'. Experiment with '-f' option.
- In some screen resolutions (-d) the power, mdv and win LED are invisible.

Undocumented/untested/unstable development options:
-F100	: fake F1 during boot
-D	: 68k debug mode
Key combinations:
C/A/S F : flush log file
C/A/S B	: no screen refresh toggle
C/A/S D	: dump memory to file 'qlay.dmp'

7.2 History

082	Improved 68k emulation: exceptions, speed
	New grapics code
	Rename added in NFA
	More emulation memory, ROM file support
	New tool: QLAYT to support all file conversions
	Command line options in configuration file
	Remove clock bug: QLAY now uses the local PC time of day
081	Repaired QL mode 4 on 16-color screens
	Improved error messaging in 'qlay.log'
080	NFA
	Mouse
	BEEP
	New key combinations for 'exit' and 'refresh'
	F6-F10 emulate shift F1-F5, PgUp/Dn: alt enter, End: ctl space
	Improved interrupt emulation
	Emulation speed control
	Better IPC emulation
077	Dual screen support
	ROM write protection
	New screen code. Mode 4 is wrong on 16 color screens now
	Minerva ROM support
	Scroll Lock key
076	Improved STOP instruction
075	Bug fixes to support tools
	More screen modes on QLAY
070	First release

7.3 Current versions

qlay      0.82i 970823
qlayt     0.82f	970806
nfa.rom   0.82h 970821
fil2win   0.8	Not supported anymore, use QLAYT
fil2mdv   0.4	Not supported anymore, use QLAYT
dos2qdos  0.8	Not supported anymore, use QLAYT
qdos2dos  0.8	Not supported anymore, use QLAYT

8. Info and updates

http://www.inter.nl.net/hcc/A.Jaw.Venema
A.Jaw.Venema@net.hcc.nl

Jan Venema

[ eof ]