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