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 he 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 equivilant programme 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, probablly 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 or 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 a 
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 
version3.)
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. Is it absolutely legal for 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. Never the less 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 an 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-
