QLem 1.45Jx(beta) manual
========================

This is a short description of my QL emulator for the various Atari ST
machines and the Falcon030. It _may_ also run on the TT.

Please, do not make this version of the emulator available to anyone else
without asking me first. The emulator works rather well, but I want some
more feed-back before I do a general release.
If you have anything at all to say regarding QLem, _please_ contact me.

All questions, suggestions, help offers, bug reports etc are very welcome.
If you want to help develop this emulator further, I'd really appreciate it.
I don't have as much time to spend on my programming projects nowadays as I
used to have.  :-(

Johan Klockars, 960120
(rand@cd.chalmers.se  or  johan@rand.thn.htu.se)


Overview of features and handling
=================================

A QDOS JS rom dump is included in the emulator archive since I've heard from
a number of sources that Amstrad is not interested in the issue.


How to start the QDOS emulator
------------------------------
Run QDOSJX.PRG with QDOS.JS (and TRUMP.121 if available) in the current
directory. A text with some information about the emulator will be shown
while the emulator loads and patches the rom dumps.
After a while the screen will clear and finally the familiar F1/F2 screen
will appear. If you run QLem on a monochrome screen, you'll not be able to 
read the text without pressing HELP once. This is caused by the way the
screen emulation converts from the QL four colour mode to black and white.


What's known to work in this version of the emulator
---------------------------------------------------
(Apart from the obvious things that is.)
- JS rom dumps
- Screen emulation on monochrome and colour monitors
- TOS/DOS floppy support (root directory only)
- With TrumpCard 1.21 rom dump, read and write(no error checks) of QL disks
- Boot from flp1_boot(QL disk with TrumpCard 1.21)


What _should_ work, but hasn't been tested since '92
----------------------------------------------------
- JM rom dumps
- Parallel port (PAR)
- Second disk drive
- Joystick emulation (arrow keys)
- Changeable delay for games (see DELAY below)
- Boot from dsk1_boot (TOS/DOS disk)


Available support programs
--------------------------
A GEM based file transfer program QL -> TOS/DOS with formatting of QL disks
is available. It _should_ work with HD disks, but I have no such QL disks...
If anyone has any info on the new QL filesystems (level 2?), please let
me know.

A native ST monochrome mode screen device driver (no graphics) is supplied
in the emulator archive. To run it, use the following (or similar):
  a=malloc(20000):lbytes "dsk1_textdev.cde":call a
The device driver is called dsp_ and should be able to handle everything that
the normal con_ driver can (except graphics), but it's _much_ faster (fastest
text draw routines I've ever seen on an ST) and can only be used with the
screen emulator turned off (otherwise the output is immediately overwritten).


The keyboard
------------
The keyboard layout currently depends on both the QL rom used and the
keyboard your ST has. I hope to fix this in the near future.

Keys            Description

F6 - F10        The function keys F6-F10 are the same as F1-F5 but shifted, as
                on other extension keyboards for the QL.
                However, they have no KEYROW codes.

Help            Monochrome:
                  Used to switch between the two colour emulation modes.
                  There are two modes because the monochrome emulation can only
                  show two of the four possible colours at once.
                  MODE 8 is emulated in exactly the same way as MODE 4, which
                  makes it look somewhat funny at times.
                Colour:
                  Used to switch between emulation for MODE 4, MODE 8 and
                  MODE 8 with flash. The MODE 4 emulation is by far the
                  fastest and can (should) be used all the time.

Ctrl-Alt-Help   Tries to reset the QL emulator. This does not always work.

Ctrl-Alt-Delete Hard reset (return to ST mode).

Delete          Same as Ctrl - left.

Backspace       Same as Ctrl - right.

UNDO            Equivalent to the ctrl-F5 combination, ie it stops output to
                the screen temporarily, until another key is pressed.

* (numeric)     Toggles the screen emulators modes:
                multitasking  -  default mode, does not work for all programs
                                 The priority can be changed in the the usual
                                 ways if needed.
                interrupt     -  emulates the screen no matter what...
                                 Some games and other special programs need
                                 this mode. Also gives less 'jumpiness' in
                                 the display.
                none          -  no emulation of the screen is done
                                 For extra speed or testing of native screen
                                 device drivers such as textdsp.cde.
                
+- (numeric)   Only on colour monitor.
                Switch between showing the top and the bottom of the screen
                (the whole screen won't fit).

The rest of the keys have their normal meaning.
None of the special keys have any KEYROW codes.


New SuperBASIC commands/functions
---------------------------------
      SHOWFIX   -   Shows what fixes the emulator has been forced to do
      RCONV     -   Removes the screen emulation job (not the interrupt one)
      SCONV     -   Starts the screen emulation job again
      MALLOC    -   Reserves memory on the common heap (addr=malloc(n))
      FREE      -   Frees memory reserved on the common heap (free addr)
      DELAY     -   Sets the delay used in the KEYROW code (delay word)
                    (A DBRA counter is set to the value you give, which will
                     cause a delay of about 12*word cycles per KEYROW read)
      HEADREAD  -   Reads a file header.
      HEADSET   -   Sets a file header.
      FLOPPY    -   Informs the TOS/DOS floppy device driver that there's
                    a file name translation table to use. See below.


TOS/DOS floppy support
----------------------
The only disk drive support built into QLem is a TOS/DOS directory
device driver. This usually works rather well (together with QL2ST for
transfers from QL disks), but there are a few things that can cause
problems:
- The file names are the normal TOS/DOS 8+3 characters.
  The native QL file system handles file names of up to 36 characters.
- Normal QL disks have extra information for each file, for example the
  size of the data area for EXEC(utable) programs. TOS can't write that.
- There's currently no error checking on either read or write.
  Most of the time everything will work fine, though...

The latest versions of QLem/QL2ST partially solves the first problem by
introducing 'name translation tables' and has a work around for the second.

Name translation tables
-----------------------
The idea is that QL2ST writes all the file information from a QL floppy
into a special file (_QDOS.NME) on the TOS file system. The TOS/DOS
disk device driver under QLem can then be made to use this information in
the following way:

  a=malloc(1000)                 Size depends on the _QDOS.NME size
  lbytes "dsk1__qdos.nme",a
  print floppy(a)                The value printed is of no importance

After that, every time you try to open a file, the name translation
table will be searched for a match. When one is found, the correct
TOS/DOS file name will replaced the name you gave before the actual
open operatioyn takes place.

As an example, imagine that you have a QL floppy with a lot of files.
Using QL2ST, select them all and start the conversion.
For each file, QL2ST will ask you for a new file name, while suggesting
one based on the QL file name. After the file is written, the _QDOS.NME
file, in the same directory, will be updated (perhaps created as well)
with both the original name/data and your TOS file name.
When you want to use the disk with the converted files under QLem,
do the SuperBASIC steps described above.

If you for example converted a file named my_database_dat using QL2ST,
the suggested name would've been MY_DATAB.DAT. A directory of the TOS
disk under QLem will also show that name. However, if you want to open
the file, from within Archive or anywhere else, you can use _either_
name without problems.

The name translation table will automatically be invalidated if you
change disks.


Additional file information on TOS disks
----------------------------------------
It appears there us actually space in the directory entries on TOS disks
for at least the most important of the QL file information. As was
mentioned before, that information can't be written by TOS, though.

The important extra information is that about the file type and data area,
which is needed for EXEC(ing) of files to work.
When files are saved to a TOS/DOS disk from under QLem, that information
will be written, so if it was just available in the first place everything
could be corrected. Actually, the device driver will supply some default
values for the information if none is available. That was the case with
older versions of QLem as well, but other errors caused direct EXEC from
floppy to fail anyway (you could always copy to a RAM disk and EXEC there).

Now, with the name translation tables, things can be corrected.
While it might sound reasonable to use the information from in there
directly, that would be very dangerous when updates are done to files on
the disk (the table wouldn't change), so a simple program is used instead.
Run the supplied SuperBASIC program, FIXFILES, and follow the instructions.
(LRUN dsk1_fixfiles should do the trick.)


Automatic file loading at startup
---------------------------------
To make it possible to try QLem even on systems without working disk
access, for example under STonX, a simple scheme has been implemented
to allow files to be loaded into memory when QLem is started.
QLem will look for a file called 'LOADFILE.DAT', load all files mentioned
in it and put them at the specified memory locations.
A short example:

$200000
j:\qlprogs\qmon2
$210000
j:\qlem.140\qlem_140.txt
$0

All addresses must be given in hexadecimal form, with a leading '$'.
The number '$0' marks the end of the file.
QLem will abort if it can't find all the files mentioned, but it will
not check whether it is possible to store them at the specified addresses. 
Space for the files will be allocated using Malloc at first. Later the
files are moved up to the top of RAM and finally, just before QDOS is
started, the files are moved to the specified locations.


Additional comments
-------------------
- Most programs should work under the emulator, for example:
    Turbo, Desktop Publisher, The Editor, PSION Xchange and Scrabble
- All keys may not give the expected characters.
- There is no timeout on disk operations.
- Use of unsupported devices can lock up the emulator.
- If you have another rom version that you would like to use, then send me a
  copy and I will look into it. This especially applies to disk interfaces.
- The emulator is set to give a 1Mb QL since I only had that amount of memory
  when I last did any work on it. There should be no problem changing this to
  2Mb, but more will give serious problems due to 16 bit slave block addressing
  in QDOS. I'll fix it when I have the time.
- It would be nice to have a list of compatible and non-compatible programs,
  so please let me know what you've tried.
- If a program crashes for you, I can most likely fix it quite easily if you
  mail me an executable copy.


For programmers
---------------
Some programs have trouble with the way the ST protects low memory.
If you know a bit about machine code programming, you can use a monitor
program, for example Qmon, to help find out what's wrong.
The problems will show up as an illegal instruction error in the m/c-monitor.
This is because the emulator has to trap all accesses to low memory, mainly
because of the vectored QDOS routines ($c0-$12a). If the error trapping code
does not recognize the offending instructions it will execute an ILLEGAL
instruction to enter the monitor program.

For the Falcon030 some new code had to be written, dealing with the
different exception stack format, MMU page tables, cache control etc.
It all seems to work well now, but if you have trouble understanding
something (there are no QL debuggers that handle the '030 instructions
that I know of)), please don't hesitate to contact me.

If you need help, please email.

What still needs to be done (in no particular order):
- RS-232/MIDI device drivers
- 'Virtual' micro-drives
- Native ST colour screen device driver
- Graphics support in the native monochrome device driver
- Fixes to the hard disk code. It's currently not enabled in the emulator
- Support for better graphics modes on TT/Falcon/graphic-cards
- Falcon DSP support for screen emulation. Yes, yes, yes!
- Sound

And probably a lot of other things I haven't thought of. Let me know!

Johan Klockars
