English translation by Mick Lock verified by Peter West 1996,1997
-----------------------------------------------------------------


DRVIN.PRG, DRVINSA.PRG
======================
(I don't have time to type everything longhand, so if someone wants to 
write a driver for different hardware or a "Driver adaptor" for Mint, then 
they can contact me. Assembler knowledge needed up front. Sometime in the 
future I hope to document all functions here.


The program (DRVIN) supports loadable device drivers. It must be loaded 
before the drivers. DRVIN and the drivers must also be loaded before the 
program that will use them. DRVIN must be placed in the AUTO folder (for 
specialists: or in an equivalent program area). It can be run from the 
Desktop for test purposes. It should be placed as far as possible to the 
back of the AUTO-folder.


TOS
---
DRVIN runs under all known TOS versions.

Mag!X, MagiC
------------
DRVIN runs under Mag!X from version 2.00. It should run with older 
versions of Mag!X, but I've not actually tested it. With MagiC versions 
>2.00 some functions of DRVIN are unnecessary, and therefore not used. 
There will be a MagiC, probably MagiC3, that will contain all of the 
functionality of DRVIN, making it superfluous.


MiNT
----
When DRVIN and the drivers are started before MiNT, only a few of the 
functions are available, so DRVIN and the drivers should only be started 
after Mint has been loaded. This will ensure that all functions work, with 
the exception of Redirection and Sleep or other functions under TOS which 
are not available because their filehandles are not supported. I am not 
sure if the change of AUX-device for the current process will still 
function. I use neither MiNT nor MultiTOS. So long as there is no MiNT 
freak who can support and configure it, there will be no special to MiNT 
versions created.


Configuration
-------------
Configuration is achieved through SETTER.TTP. See SETTER.TXT for more 
details.

FASTINT:
MFP.PRG can modify the timer interrupt of TOS to about 57600Bd with an 
8MHZ 68000 using MODEM1. Even on the MegaSTE, TT and Falcon you can 
achieve positive results. Under MagiC the modification will not be 
implemented, there is already a "friendly" timer routine in MagiC (from 
version 2.0). When experimenting with other operating systems or you get 
strange effects, you should switch FASTINT off first.

Function (for interested users):
--------------------------------
I have shown that it is enough to use the routine (GEMDOS-timer) in 
NEXT_TIM (negative LineA variable) with an IPL < 6 to achieve 57600Bd 
receive using a 68000/8MHz. So I insert a block of code that resets the 
IPL to 5. This type of action is not without risk, but only creates 
problems when other programs attempt to do the same.

EXOPEN:
(Only works if the GEMDOS part of DRVIN is used, but not under Magic 
version 3).
Using "Yes" activates a strict GEMDOS function, Fopen. This prevents a 
device from repeated and simultaneous opening. This protects activated 
(opened) devices from external interference by other programs, but only at 
the GEMDOS level. Normally you should select "No", on the one hand some 
programs don't expect error messages from Fopen (so absurdly redisplay 
until a crash occurs), on the other hand termination of programs is not 
watched, so it makes no difference to any other GEMDOS-behaviour so the 
device stays opened (even after an abnormal program termination = crash)! 
(In short: more a game for the developer at the moment.)


Differences between DRVIN.PRG and DRVINSA.PRG
---------------------------------------------
DRVIN is the complete normal version, that can normally be used without 
problems except in a few extremly old programs that will hopefully die 
out, that assumes that the Processor registers A1/A2/D1/D2 are not altered 
with a BIOS call. DRVINSA saves these registers so you can use it with 
faulty programs. DRVIN does not save these registers and is therefore 
faster. It is absolutely legal to make BIOS, XBIOS and GEMDOS calls to 
registers A0/A1/A2/D1/D2!


Construction
------------
DRVIN consists of three essential parts: The placing of the RSVF Cookies, 
the new Bconmap and MAPTAB management for BIOS and XBIOS, as well as the 
Basic routines for installation of simple Mag!X compatible device drivers.


RSVF-Cookie
-----------
A RSVF Cookie is created which points to two 0-LONGS, and an end object. 
So device drivers do not need to create their own Cookies, but instead 
they hook into the RSVF lists. The RSVF Cookie provides a structure to 
display fundamental information about interfaces. The description of the 
RSVF Cookies is contained in the text file RSVF_COO.TXT.


MAPTAB-Management
-----------------
This part of the program attaches to the BIOS and XBIOS trap and deals 
with the XBIOS functions, Bconmap, Rsconf and Iorec (for AUX). It deals 
with the BIOS functions, Bconstat, Bconin, Bcostat and Bconout for device 
AUX as well as all other devices from 6 upwards, inclusive. Bconmap and a 
MAPTAB are set for all TOS versions. The routines of the device set by 
Bconmap are also copied to the xco*-vectors (except TOS1.00), but are not 
used. Two new Bconmap sub functions with opcodes -400 and -401 are 
provided for replacing a MAPTAB entry and for attaching new entries to a 
MAPTAB.

The length of the MAPTAB is no longer limited. ### At the moment DRVIN.PRG 
is set for a maximum of 10 entries, however it is only a variable constant 
in the Assembler sourcecode and can be changed at any time.


GEMDOS Part
-----------
This looks outwardly like previous HSMODEM1 versions but inwardly (### at 
the moment) a very limited Mag!X-Beta.
Fopen, Fread, Fwrite, Fclose, Fcntl are all passed to the driver, but all 
with fileptr == NULL.


Operation
---------
When DRVIN is activated under TOS>2.00 or Mag!X >2.00, all the routines 
from the old MAPTAB are copied into the new one, so that (X)BIOS functions 
will work with the old routines if no driver is installed. Under TOS1.00 
it looks pretty bad, the MFP driver must be loaded, otherwise the serial 
I/O will not work (only the IOREC pointer is copied). Under 1.00<TOS<2.00 
it will work slightly without drivers because only Rsconf is not copied, 
which is why the MFP driver must be loaded.


Mag!X (and DRVIN) friendly Bco*-routines
----------------------------------------
Modifiable registers A0-A2/D0-D2 (also with Rsconf)
Bconout must be activated with the command

  lea 6(sp),a0

and will primarily be called with (Startadr+4) with A0 as a pointer to the 
WORD with the parameters.


New XBIOS Bconmap functions (-400, -401)
----------------------------------------
These functions only allow Mag!X friendly functions to be installed & 
used.

In the MAPTAP there is room for more than 4 devices. The provider of the 
XBIOS functions (DRVIN or a future Mag!X) provides enough room to install 
additional devices. It may create the room dynamically or have a fixed 
upper limit. Nevertheless a driver could get an error message caused by 
insufficent memory or other reasons.

The XBIOS-function Bconmap is extended by two new subfunctions. If the 
extensions are unavailable, the caller gets a 0 as an error message.

LONG Bconmap((WORD)-400, (WORD) dev_nr, (LONG) ptr_to_6_longs)

dev_nr is a device number from 6 upwards, that must already exist in the 
MAPTAB otherwise -15 EUNDEV error code will be returned. Ptr_to_6_longs 
points to a structure that equals a MAPTAB entry. This structure will be 
copied to the corresponding place in the MAPTAB. If the installed device 
is the current Bconmap for AUX, then the basic routines are copied to xco* 
and the current rsconf and iorec cells. This function is only for the 
installation of Mag!X friendly routines. On success the device number will 
be returned, thus dev_nr is the returned value.

LONG Bconmap((WORD)-401, (LONG) ptr_to_6_longs)

similar to -400, but opens a channel to the MAPTAB. Response is either the 
channel number selected, or the error code -12 EGENRL when there is no 
space to enlarge the MAPTAB. Logically, the vectors can't be transferred 
to xco* because the additional device can't be current at the time of 
inclusion.


Driver
------
DRVIN doesn't provide for all GEMDOS capabilities in Mag!X (beta) 
versions. Anyone who wants to write a driver that functions under DRVIN, 
can contact me for details.


Versions
--------
1993-11-23     GEMDOS trap modifies only A0/D0 as configuration for the 
               many dirty programs.
               Fopen and Fclose passed to Devices.
1993-11-28     Bug under TOS1.00 in XBIOS Bconmap removed
               Separate env string _PNAM=DRVIN.PRG
1994-06-17     Pointer array for Dcntl DEV_M_INSTALL has changed to the 
               format of MagiC version 3 (ex Mag!X). INCOMPATIBLE with 
               earlier versions of DRVIN and drivers.
1994-08-13     Only the pointer to the driver array is stored during Dcntl 
               DEV_M_INSTALL, not the array itself. Space for 16 GEMDOS 
               devices.
1994-08-18     FASTINT configuration moved from MFP* to here and IPL4 
               instead of IPL5
1994-08-25     Internal changes
1994-10-12     EXOPEN option
1994-10-29     Changes to Dcntl, provides for up to -36 devices to be 
               installed. Fdelete built in. Deleting and re-installing 
               drivers should work as in MagiC3.
               FASTINT automatically switched off by MagiC.
1994-12-30     Fast Bconmap parameter passing changed, therefore 
               MAPT_APP/MAPT_OVE have new function numbers
1996-03-30     DRVINSA variant with protection for the registers 
               D1/D2/A1/A2 generated in the BIOS trap.

Harun Scheutzow, 21.11.1993 and later
(Harun_Scheutzow@B.Maus.De)

-EOF-
