Amiga Elysian Archive/AmigaElysianArchive.iso/emulate/qdos4ami.lha/docs/Alpha_QDOS_TXT

Text File | 1990-05-20 | 20KB | 413 lines

          QDOS for the AMIGA
          ------------------

1) Introduction and motivation
------------------------------

I have bought my first QL at 1984 in Berlin, and since this time the
QL has proofed to be a very handy tool for all kind of computer work.
But unfortunately this computer was not very popular, it was difficult
to get anything (software and hardware) for the QL, and without the
usergroup, I would have given up very early. With the advent of the
ATARI 520 ST and the increasing popularity of the IBM clones the
QL became more and more uninteresting for new users, and Sinclair
lost interest in the computer himself.
So far so bad, but after checking the possible alternatives, there
was actually no computer which was really much better than the QL.
So the Idea came up to build a new computer with 68000 CPU and
a reasonable keyboard. But why building a new computer, when you
can buy one ?
For this purpose the AMIGA seemed to be best suited. It is
highly expandable and has many hardware features allready on board.
Furthermore, it seemed to be more easy to emulate the QL screen
on the AMIGA, than on the ATARI.



2) What has been done up to now
-------------------------------

The gamma version was made from a disassembly of the JS-ROM,
which was expanded in some features and testet on the QL.
The QL-screen emulation is performed using the Blitter, which
makes it a very fast process, costing nearly no CPU time.
The keyboard is emulated in most features (including Ctrl-Alt-7)
and Keyrow (using the IPC) is working on all programs.
Additionaly a default trap handler has been installed, which will
tell you what happend at what address, and return to SuperBASIC.
The program must be assembled on the QL using the GST macro assembler.
NO OTHER assembler can be used (I have tested some Amiga assembler,
but there is no Assembler, which has a linker and is really bug free.
The best result gave the Atztec-C assembler. It was able to assemble
all files, but the linker crashed the system when attempting to link the
QDOS file.)
Apart from the MicroDriVes and the NETwork all standard QL devices are
implemented: CON_ , SCR_ , PIPE_ , SER1 , PAR , FLPn_ . The RAMdisks are
running too, but it is only included in the ! Friends only Version !
The clock should run too, if you use the system routines.
The T.Tebby toolkit is working also, when TAS instructions are replaced.
* Additionally in This Version  (3.01) a JANus device driver is  included
* which allows you to use the Harddisk from the IBM Sidecar.
** A FLoPpy driver accomplishes the system in this release (3.03)
** The Amiga mouse is integrated, QRAM (pointer interface) and MPAINT
** have proofed to work correctly with it.

Disks supplied:
Version 3.03 comes on 3 disks:
Disk 1 is a Amiga BOOT disk, it contains this document (Alpha_QDOS_TXT)
       an introduction to QDOS (QDOS_INTRO) an old description for the
       RK00 Version (RK00_INFO) and the QDOS system, ready to BOOT.
       Additionally, some Programs for File transfer and other utilities
       are included in executable and source form.
Disk 2 is in QDOS format and contains the Assembler source for QDOS.
       This Disk should be copied using INDEX synchronization
       and nibble mode or the QDOS DISKCOPY.
Disk 3 is also in QDOS format and contains some Utilities and patched
       programs. Specifically programs to support Filetransfer,
       TAS replacing and using the PROSPERO compilers.

NOTE ! if you give this Disk to other persons, please copy all 3 disks !
If you possess a "Friends only" version, then delete the Files
TOOLKIT_CDE and MIXTOOL_CDE and change the startup-sequence accordingly
before giving this Disk to others.


Files supplied:
*** In this sector there are a lot of changes since the early versions.
*** Mostly the Batch files have become redundant.
*** But I am too lazy to update this list. So here it is:

QDOS                          The complete running QDOS
TKamiga_CDE                   The T.Tebby toolkit without TAS instructions
                              !!! Friends only !!!
MIXTOOL_CDE                   A combined toolkit including EDITOR
                              and RAMdisk and QMON and Qliberator
                              runtime library
                              !!! Friends only !!!
QL_EXTRA                      batch file to start the QL-emulator
                              in fast memory

S/startup-sequence            start the QDOS 512k system
AllocAbs                      used to allocate Memory
Lbytes                        used to load files into memory
Load_Qdos                     This programm moves QDOS from $30000
                              to $00000, sets the clock and memory
                              boundaries. The full format is:
                              Load_Qdos RAMbottom RAMtop SSP
                              All addresses are hex numbers,
                              where RAMbottom and RAMtop should lie
                              in Fast memory, and no care must be taken
                              about Amigados. SSP is the Supervisor
                              Stackpointer and must lie outside the
                              scratch area between RAMbottom and RAMtop
SerQl                         A filetransfer program which can be used
                              to send files from the QL to the Amiga
                              via the serial port. The Handshake lines
                              must be connected for this.
                              Allthough the programm works correct on
                              the Amiga side, it may be difficuld to
                              send files from the Amiga to the QL.
                              I had not the time to search for the
                              reason, but i think the Problem must
                              be the QC compiler on the QL.
                              You can transfer files from the Amiga
                              to the QL nevertheless by sending them
                              with the Amiga SERQL and receiving them
                              with
                              COPY SER2hr to RAM1_hilf
                              and removing the additional bytes in a text
                              editor.
                              Note, that you MUST use the Ramdisk for
                              long files on BOTH computers.

SRC/SerQL.C                   Amiga version of SERQL (Aztec C)
SRC/SerQL_C                   QL version of SERQL (QC)

SRC/Load_QDOS.ASM             (use Aztec C assembler)
flp2_TAS_replacer_BAS         Superbasic program to replace the
                              TAS instructions in any program.

flp1_JAN_ASM                  janus device driver source, QL side
JAN_CDE                       janus device driver binary, QL side
PC/QLDISK.PAS                 Turbo pascal source for IBM part
PC/QLDISK.COM                 compiled version (TURBO 3.0 !)
PC/AUTOEXEC.BAT               example for IBM

flp2_QLTRA_BAS                file transfer program QL->QLamiga, source
flp2_QLTRA_OBJ                compiled version (4800 BAUD  !!!)



3) Known Bugs !!!
-----------------

To Start with the hardest one: The Amiga hardware does not allow
the CPU to get two contigues bus cycles. This means, that any
read - modify - write cycle is dammed to fail.  More precise:
the TAS instruction does not work ! neither in Chip nor in Fast memory !
To get around this problem, the line $F... emulator was programed
to emulate the TAS instruction. Now you just need to run TAS_replacer_BAS
on any program which contains TAS instructions to replace them by
the appropriate line $F... instruction.
So far, so good, but the sideeffect may be as follows:
One day you want to give a program to a friend with a normal QL.
If your program needs a library, which contains TAS instructions,
then it will now contain line $F... instructions. On a normal QL
this will cause a total system crash. Thats it !

The Next Bug is perhaps correlated with this. The RAMdisk (QRAM)
can not be formatted correctly, although i have applied TAS_replacer_BAS
to it. This should not bother you too much, since you can still use it.
But if you try to use the Qliberator compiler with an unformatted
RAMdisk, you may have some trouble. Just try some other RAMdisks.
!!! The RAMdisk is only included on the friends only Version !!!

** The obscure Memory Management Bugs are fixed in this Version (3.03)
*** The Slave Block Bug is fixed in 3.10 by M.J. Swift

For those, who want to program amiga hardware under QDOS, I want to
give one essential hint:
Interrupts and DMA are very very very critical. You MUST enable your
interrupts directly after starting QDOS.
You should never disable interrupts in INTENA. Use 'OR #$0700,SR' instead.
You should reset interrupt requests only once and only those which
really have occured.
If you fail to do so, then NOTHING will work, even if you don't need
interrupts !

A last remark must be made upon the keyboard. You should try to buy a
computer in Germany with an English keyboard. Hopeless !
This stupid selling staff can not imagine, that not everybody who buys
a computer is a secretary which needs ä,ö,ü in the proper place.
So you have always the pleasure to search for @,[,],{,},_,Y,Z and many
other commonly used keys. But this does only bother those, which
must write programs for computers, and not the so called "User"
which is a much better, this means richer, person.
Okay, what i want to tell you is, that the keyboard emulation is only
good for German Amigas and not for English Amigas.
For the first time you can use ALTKEY to redifine some keys.
But over a long range you have to change the QLASC... tables
in the QDOS_ASM file and generate a new QDOS version.
The sideffect is, that KEYROW may contain some minor inconsistencies.

* The keyboard emulation has proofed to fail on certain keyboards.
* This Bug should be fixed now !

* The Ctrl-C , Ctrl-spc , Ctrl-F5 'bug' is fixed  now !

*** An english keyboard emulation is included. A source for this Emulation
*** can be found in the "SRC" directory of this Disk. it is named
*** QLASCII_asm. You should not try to assemble it on the Amiga, since
*** this will not produce the correct object code.

If you have fixed a bug, I will be greatfull when you can send me the
corrected SOURCES or inform me about the reasons.

4) New standards
----------------

(Read also RK00_INFO !)
Changes to the System variables:

$28002              Flag byte, now contains the following flags:
                     Bit 0 : 0 => OPEN path enable
                     Bit 1 : 0 => OV error disable
                     Bit 2 : 1 => No clearing of memory on MM.ALCHP

$28003              Is the contents of CIA-A ICR, updated by interrupt
                    from the Keyboard server. The new value is ORed to
                    the old one.

$280A2              in previous versions this was the Caps lock routine
                    address. Since this was never used, i have changed
                    its meaning. It is now a long word offset to the
                    system clock. should not bother you.

$280F2              Priority increment of the QL screen emulator.
                    the following byte is increased by 2*contents
                    of this byte, if the result is negative, the
                    next plane (green or red) is updated.
                    Default is 20dez. This will not cost any CPU time.
                    A value of 80dez. will cost 20% CPU time,
                    and a value of 127dez. will cost 30% CPU time.
                    If you set this byte to zero, then the emulation
                    is switched of after the next vertical blank int.

$280F3              actual QL screen emulator priority.
                    This byte should be set to zero too, when switching
                    off the screen emulation.

$280F4              Address of Blitter interrupt server.
                    If you have switched off the QL screen emulation,
                    you must wait until this Long word contains 0.
                    Afterwards you can link in your own server for
                    Blitter interrupts here.

Any program which needs the Amiga hardware interrupts can use
the old MT.LXINT system call. This now handles all interrupts
except the Blitter, Keyboard  and 50 Hz interrupt.
You must read the INTREQ register by your own to decide what to do.
If it was the interrupt you was waiting for, you have to reset it by
your own. You will get the CPU with all interrupts masked out, and
you should not change this status.

* The Amiga bitplanes are starting at $18000.
** The Floppy controller uses the Memory from $10000  on.
* Additional bitplanes can claim the Memory between $14000 - $17FFF.
*** A new Manager Trap is introduced: TRAP #1 with D0 set to $27
*** and D1 containing the address of the new Keyboard table
*** will set foreign Language keyboard tables.

****************************************************************

* 5) The JANus device driver
* ---------------------------
In the Gamma release, you had no possibility to save or load
programs from a permanent medium. In the Beta release, I had
included a very simple directory device driver which enables you to
use the IBM-harddisk on the Bridgeboard. Of course you can make
use of this program only, if you posses the IBM bridgeboard (sidecar)
and a  Harddisk in one of the IBM compatible slots.
(But the floppy on the  IBM will give you  at least 360K.)
The JANus devicedriver expects the program QLDISK.COM running on
the IBM side. This program is also included in source format (QLDISK.PAS)
and must be compiled with TURBO pascal 3.0 !
any filename has the form:         JAN1_name_ext
where 1[,2,3,4,5,6,7,8] has no function.
The extension is converted from _ext  to .ext automatically.
Names consist  of capital letters only and must not be longer than 8
characters.
Subdirectories and file conventions of MS-DOS are used.
If you try to read MS-DOS files from QDOS, you will experience some
trouble, since QDOS needs a 64 byte fileheader, which is of course
not present in MS-DOS files. The other way around, you will find
64 additional bytes at the top of any QDOS file, when you try to read
QDOS files from the  IBM side.
additional BASIC extensions:
CHDIR "path"                  changes the  subdirectory path (CD on IBM)
MKDIR "name"                  make subdirectory (MKDIR on IBM)
RMDIR "name"                  remove subdirectory (RMDIR on IBM)
SHODIR                        display the actual path at channel #1
JAN_USE "abc"                 set up a new device name for JAN (eg MDV)

For transfer of files between the QL and QDOS on the amiga you
can use the program QLTRA_BAS or QLTRA_OBJ.
This program transferes a complete disk.
Up to now you should not try to operate  on more than 4800 Baud.
It is  also essential, that  you don't type anything on the keyboard
while files are transfered. This is because interrupts from the serial
port are disabled while processing the keyboard interrupts.

** Access of MS-DOS files is possible in the new Version using
** a filename which contains a 'commercial at @' (eg. D:\@AUTOEXEC.BAT)
** A backwards searchlist is established, which scans all parent directories
** for OPEN old file QDOS calls
****************************************************************
****************************************************************
Version 3.03 comes with a floppy device driver for QDOS floppies.
This device driver is not the fastest one, and there are lots of
bugs, but for the first time you can use it.
The Format of a QDOS filename on the floppydisk is FLPn_name_ext.
Where FLPn_ is the device name. FLP1_ stands for DF0:, FLP2_ for DF1:
and so on (sorry, QDOS convention was first). Filenames can consist of
up to 32 characters. The *D2D random access convention is emulated in
full scale, so that CP/M and MS-DOS emulator should work.
Additional extensions:
DISKCOPY
   make a track to track copy from FLP1_ to FLP2_
   You should use DISKCOPY instead of FORMATing a Disk, since
   Formating a Disk takes 8 minutes !
RQDISK drive,side,track
   Read one Track from a drive to the Trackbuffer ($10000) and
   convert from MFM to ASCII

Bugs and Hints:

Again the hardest Bug first:
*** This Bug has been fixed in Version 3.10 by M.J. Swift.
You can read QDOS disks and write files on Disk, and do everything
like on the QL. But when you try to read a Disk which was written on
the Amiga using a normal QL, you will not be able to read anything !
This is because the CRC calculation routine in my driver does not
work correct. I have tested every possible combination, but i couln't
find the bug. If you are able to fix it, please let me know!

Some combination of Floppy drives have proofed to give unreadable
Disks. This depends much on the drives of your Amiga AND the drives
of your QL. Up to now, my Amiga was able to read every QDOS disk,
but a friend had trouble to read the same disks.

A little hint:
Normally QDOS scatters the sectors of adjencent blocks on different
sides of one disk. This doesn't matter with a WD1770, but it makes reading
a Disk on the Amiga unneccessary slow. You can gain a factor of 3 in speed,
when you FORMAT a Disk on the Amiga (afterwards just make a DISKCOPY from
this Disk) and copy the files from the original QDOS Disk to the Amiga disk.

*************************************************************

6) What has to be done next
----------------------------

These are the most important things to do, but unfortunately
I don't have enough time to do this all by myself. I am writing
my doctor thesis in Physics, and this will cost most of my time.
So I am looking for people who are interested in this project
and are able and willing to do some work for it.
I think, it is best you contact me to get information about a specific
part of the project. So you can avoid to invent the wheel a second
time. You can reach me by post mail:
Rainer Kowallik, Eisackstr. 14, 1000 Berlin(W) 62 (Germany)
By Phone:
(Germany) 030 855 866 5
By EAN mail
Kowallik@vax@[e-mail]              or in the new form:
S=KOWALLIK;OU=VAX;P=HMI;A=DBP;C=DE

ALL PROGRAMS HAVE TO HAVE THE FORMAT OF A STANDARD QL-ROM.
NO OTHER INTERFACE THAN A ROM TOOLKIT SHOULD BE USED !

Subject                                              programmer
-------------------------------------------------------------------------
An adaption of the Toolkit network server which    |
uses the CD bit of the serial port (CIA-B, PRA #5) |
The transmission speed should be changeble         |
-------------------------------------------------------------------------
A device driver for the Harddisk DH0, using        |
subdirectories and fileformat of Amigados          |
-------------------------------------------------------------------------
New SCR_ and CON_ drivers which can use all        |
features of the Amiga (32 colours, extra halfbright|
Interlace, overscan)                               |
-------------------------------------------------------------------------
QDOS Disk Read and write access under Amiga DOS    |
-------------------------------------------------------------------------


8) Copyright statement :
------------------------

Since I have really spend much time on develloping this QDOS emulator,
I think that it is not imoral to claim this emulator as my program.
Nevertheless QDOS and the related names are protected by the ones
who have now the rights (is it sinclair again, or amstrad, or t.tebby
or who or what ?)
But this should not stop you from spreading this disk, as long as you
are shure, that no commercial use is made from all that stuff.
I am shure, that these  programs are only interesting for people
who have or have had a QL or THOR, and so have allready paid for this
software. Those who are working with these programs and don't posses
a QL are invited to buy a second hand QL or so.

9) Acknoledgement
-----------------

Thanks to
Wolfgang Schroeder and Joern Ryba for discussion,
Boris Jakubith and Mathias Leidig for the CRC generator,
Andreas Ihlenfeld for his Keyrow MT.IPCOM,
M.J.Swift for all of his Bug fixes


and you for your interest.