DRVIN.PRG
=========

(Note for the English reading people: The English version is appended on 
the German, look for it!)

(Ich habe keine Zeit, alles ausfhrlich einzutippen. Wenn jemand Treiber 
fr andere Hardware oder einen "Treiberadapter" fr Mint schreiben will, 
kann er sich gern an mich wenden. Assemblerkenntnis setze ich allerdings 
voraus. Irgendwann wird hier die vollstndige Doku der Funktionen 
erscheinen.)


Dieses Programm (DRVIN) untersttzt nachladbare Gertetreiber. Es mu vor 
diesen Treibern geladen werden. DRVIN und Treiber mssen vor den 
Programmen geladen werden, die die Treiber nutzen sollen. DRVIN gehrt in 
den AUTO-Ordner (fr Spezialisten: oder in eine quivalente 
Programmsammelecke). Man kann es zu Testzwecken auch vom Desktop aus 
starten. Es sollte aus Geschwindigkeitsgrnden mglichst weit hinten im 
AUTO-Ordner stehen.


TOS
---
DRVIN luft unter allen mir bekannten TOS-Versionen.

Mag!X
-----
DRVIN luft unter Mag!X ab Version 2.00. Mit lteren Mag!X-Versionen mte 
es ebenfalls funktionieren, dies wurde aber nicht getestet. Bei 
Mag!X-Versionen >2.00 sind einige Funktionen von DRVIN unntig und werden 
nicht verwendet. Mglicherweise wird es ein Mag!X geben, das alle 
Funktionen von DRVIN enthlt. Dann ist DRVIN berflssig und die Treiber 
werden ohne DRVIN gestartet.

MiNT
----
Wenn man DRVIN und die Treiber vor MiNT startet, bleibt nur wenig von den 
Funktionen brig. Deshalb sollte man DRVIN und die Treiber nach MiNT 
starten. Dabei realisieren sie alle ihre Funktionen wie unter TOS, aber 
nicht mehr. Umlenkungen oder sonstige Spielerchen sind mit den Filehandles 
dieser Gerte nicht mglich. Ich wei nicht, ob die Umschaltung des 
AUX-Gertes fr den aktuellen Proze dann noch funktioniert. Ich benutze 
weder MiNT noch MultiTOS. Solange sich kein MiNT-Freak findet, der die 
Anpassung und Untersttzung bernimmt, wird es wohl kaum speziell an MiNT 
angepate Versionen geben.


Aufbau
------
DRVIN besteht aus drei wesentlichen Teilen: dem Anlegen des RSVF-Cookies, 
der neuen Bconmap- und MAPTAB-Verwaltung fr BIOS und XBIOS sowie den 
Basisroutinen fr die Installation einfacher Mag!X-kompatibler 
Gertetreiber.


RSVF-Cookie
-----------
Es wird ein RSVF-Cookie angelegt, dessen Wert auf zwei 0-LONGs zeigt, also 
auf ein Ende-Objekt. So brauchen Gertetreiber keinen Cookie mehr 
anzulegen, sondern sich nur noch in die RSVF-Listen einzuhngen. Der 
RSVF-Cookie liefert eine Struktur zur Anzeige grundlegender Informationen 
ber Schnittstellen. Zur Beschreibung des RSVF-Cookies siehe Textfile 
RSVF_COO.TXT.


MAPTAB-Verwaltung
-----------------
Dieser Programmteil hngt im BIOS- und XBIOS-Trap und bearbeitet die 
XBIOS-Funktionen Bconmap, Rsconf und Iorec(fr AUX). Es werden die 
BIOS-Funktionen Bconstat, Bconin, Bcostat und Bconout fr Gert AUX sowie 
alle Gerte ab einschlielich 6 aufwrts bearbeitet. Bconmap und eine 
MAPTAB werden unter jeder TOS-Version angelegt. Die Routinen des aktuell 
per Bconmap eingestellten Gertes werden zustzlich in die xco*-Vektoren 
(auer bei TOS1.00) kopiert, dort aber nicht benutzt. Es werden zwei neue 
Bconmap-Unterfunktionen mit den Opcodes -300 und -301 zum berschreiben 
eines MAPTAB-Eintrages und zum Anhngen an die MAPTAB bereitgestellt.

Die Lnge der MAPTAB ist nicht mehr fest begrenzt. ### Momentan liegt die 
Maximallnge in DRVIN.PRG bei 10 Eintrgen, ist aber nur eine konstante 
Variable in der Assemblerquelle und jederzeit erweiterbar.


GEMDOS-Teil
-----------
Der sieht von auen aus wie die bisherigen HSMODEM1-Versionen und von 
innen wie eine (### momentan noch) stark abgerstete Mag!X-Beta. 
Es werden Fopen, Fread, Fwrite, Fclose, Fcntl an den Treiber 
weitergeleitet, aber alles mit fileptr == NULL.


Aktionen
--------
Wird DRVIN auf TOS > 2.00 oder auf Mag!X >= 2.00 losgelassen, dann kopiert 
es die alten Routinen aus den alten MAPTABs, so da eine Funktion der 
(X)BIOS-Aufrufe mit den alten TOS-Routinen gegeben ist, auch ohne 
installierte Treiber. Bei TOS1.00 sieht es ganz bel aus, man mu den 
MFP-Treiber nachladen, sonst geht SerialI/O nicht mehr (nur Zeiger auf 
IOREC wird bertragen). Bei 1.00 < TOS < 2.00 geht es etwas, da nur Rsconf 
nicht bertragen wird, aber deshalb mu man trotzdem den MFP-Treiber 
nachladen.


Mag!X- (und DRVIN-) freundliche Bco*-Routinen
---------------------------------------------
vernderbare Register A0-A2/D0-D2 (auch bei Rsconf)
Bconout mu mit dem Befehl
move.b 7(sp),d0
    oder auch:
move.w 6(sp),d0
beginnen und wird meist hinter diesem (Startadr+4) mit Parameter in d0.b 
aufgerufen


Neue XBIOS-Bconmap-Funktionen (-300, -301)
------------------------------------------
Diese Funktionen drfen nur zur Installation Mag!X-freundlichen Funktionen 
benutzt werden.

In der MAPTAB ist Platz fr mehr als 4 Gerte. Der Lieferant dieser 
XBIOS-Funktionen (DRVIN oder zuknftiges Mag!X) sorgt fr ausreichend 
Platz zur Installation neuer Gerte in der MAPTAB. Entweder er schafft den 
Platz dynamisch oder er hat eine feste Obergrenze. Ein Treiber sollte 
trotzdem mit einer Fehlermeldung rechnen, die durch Speichermangel 
ausgelst sein knnte, aber auch ganz andere Ursachen haben kann.

Die XBIOS-Funktion Bconmap wird um zwei Unterfunktionen erweitert. Sind 
diese Erweiterungen nicht vorhanden, bekommt man beim Funktionsaufruf 
automatisch eine 0 als Fehlermeldung zurck.

LONG Bconmap((WORD)-300, (WORD) dev_nr, (LONG) ptr_to_6_longs)
dev_nr ist eine Gertenummer ab 6 aufwrts, die in der MAPTAB bereits 
existieren mu, andernfalls wird der Fehlercode -15 EUNDEV zurckgegeben. 
ptr_to_6_longs zeigt auf eine Struktur, die einem MAPTAB-Eintrag 
entspricht. Diese Struktur wird auf den entsprechenden Platz in der MAPTAB 
kopiert. Ist das angesprochende Gert das aktuell per Bconmap fr AUX 
eingestellte, so werden die eben eingehngten Routinen auch nach xco* und 
in die aktuellen rsconf und iorec-Zellen kopiert. Diese Funktion dient nur 
zum Einhngen Mag!X-freundlicher Routinen. Als Erfolgsmeldung wird die 
Gertenummer zurckgegeben, auf die der Eintrag erfolgte, also dev_nr ist 
Rckgabewert.

LONG Bconmap((WORD)-301, (LONG) ptr_to_6_longs)
hnlich -300, fgt aber einen Kanal an die MAPTAB an. Rckmeldung ist 
entweder die von dieser Funktion fr den Eintrag gewhlte Kanalnummer, 
oder der Fehlercode -12 EGENRL, falls kein Platz fr eine 
MAPTAB-Vergrerung ist. Logischerweise kann es hier nicht vorkommen, das 
die Vektoren sofort nach xco* bertragen werden.


Treiber
-------
DRVIN bietet im GEMDOS-Bereich nicht alle Mglichkeiten der 
Mag!X-(beta)Versionen. Wer einen Treiber schreiben will, der auch unter 
DRVIN funktioniert, kann sich wegen der Einzelheiten an mich wenden.


Versionen
---------
1993-11-23
im GEMDOS-Trap nun nur noch A0/D0 modifiziert, fr solche unsauberen 
Programme wie STZIP (mindestens bis Version 2.3), ZIPJR, das 
PureC-Hilfesystem, Teleoffice und ungezhlte andere.
Fopen und Fclose werden an Devices weitergereicht
1993-11-28
Fehler unter TOS1.00 bei XBIOS-Bconmap beseitigt
eigener Env-String _PNAM=DRVIN.PRG


Harun Scheutzow, 21.11.1993 und spter
(Harun_Scheutzow@B.maus.de)



DRVIN.PRG
=========

(Translated from German to English on 1994-01-02 by Harun Scheutzow)

(I have no time for typing everything in the long form. When somebody 
wants to write a driver for different hardware or so, he may contact me. 
In the future here will appear the complete documentation of the 
functions.)


This program (DRVIN) supports loadable device driver. It has to be loaded 
before the drivers. DRVIN and drivers must be executed before the programs 
using this drivers. This program should be placed into the AUTO-folder 
(for specialists: or an equivalent program collection place). It can be 
startet from the desktop too for test purposes.


TOS
---
DRVIN works with all TOS versions I know.

Mag!X
-----
DRVIN runs under Mag!X from version 2.00 up. It should be run under older 
Mag!X versions too, but this isn't tested. With Mag!X >2.00 some functions 
of DRVIN are no longer needed and not used. Possibly it will exist a Mag!X 
in the future which contains all functions of DRVIN. In this case DRVIN is 
not necessary and the drivers will be startet without DRVIN.

MiNT
----
If DRVIN and the drivers are started before MiNT only a little of the 
functions will remain. That's why DRVIN and the drivers should be started 
after MiNT. In this case all functions are realized as under TOS, but no 
more. Redirections and other plays are impossible with this file handles. 
I don't know whether the AUX-device switching for the aktual process will 
continuosly work. I use neither MiNT nor MultiTOS. As long as no MiNT 
freak is to be found who takes over the adaption and support, no special 
versions for MiNT will exist.


Construction
------------
DRVIN consist of three import parts: making the RSVF-cookie, new Bconmap- 
and MAPTAB-manager for BIOS and XBIOS, basic routines for installation of 
simple Mag!X compatible devices drivers.


RSVF-Cookie
-----------
A RSVF-cookie is created which value points to two 0-LONGs, representing 
an end-object. So devices drivers aren't in need of creating a cookie. 
They hook themselves only in the RSVF-lists. The RSVF-cookie provides a 
structure for providing the basic information about interfaces. The 
description is contained in the file RSVF_COO.TXT.


MAPTAB-Verwaltung
-----------------
This part hooks in the BIOS- and XBIOS-trap and manages the 
XBIOS-functions Bconmap, Rsconf and Iorec(for AUX). The BIOS-functions 
Bconstat, Bconin, Bcostat and Bconout for device AUX and all devices from 
included 6 up are managed. Bconmap and a MAPTAB are provided under every 
TOS-version. The routines of the actual setted device by bconmap are 
copied in the xco*-vectors (except TOS1.00) too, but not used there. Two 
new Bconmap-subfunctions with the opcodes -300 and -301 are provided for 
overwriting a MAPTAB-entry and for adding a new entry.

The length of the MAPTAB is no longer limited. ## The actual limit in this 
DRVIN is 10 entry, but this is only a constant in the source, easy to 
change and extend.


GEMDOS-part
-----------
It looks like the old HSMODEM1-version from outside and from inside like 
(### at the moment) a reduced Mag!X-beta. Fopen, Fread, Fwrite, Fcntl are 
directed to the driver, but all with fileptr == NULL.


Actions
-------
When DRVIN is started under TOS>2.00 oder Mag!X>2.00, all old routines 
from the old MAPTAB are copied in the new one, so that the 
(X)BIOS-functions will work with the old routines if no driver is 
installed. Under TOS1.00 it looks very bad, the MFP-driver must be loaded, 
otherwise serialI/O will not work (only the IOREC-pointer is copied). 
Under 1.00<TOS<2.00 will it work a litte without drivers because only 
Rsconf is not copied, that's why the MFP-driver must be loaded.


Mag!X- (and DRVIN-) friendly Bco*-routines
------------------------------------------
modificable registers A0-A2/D0-D2 (for Rsconf too)
Bconout has to start with the instruction
move.b 7(sp),d0
   or other opportunity:
move.w 6(sp),d0
and will be called mostly after this (startadr+4) with the parameter in 
D0.b


New XBIOS-Bconmap-functions (-300, -301)
----------------------------------------
These functions may only be used to install Mag!X-friendly functions.

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 fast 
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 error message.

LONG Bconmap((WORD)-300, (WORD) dev_nr, (LONG) ptr_to_6_longs) dev_nr is a 
device number from 6 up which is already exists in the MAPTAB, otherwise 
the error code -15 EUNDEV is returned. ptr_t_6_longs points to a structure 
equal to a MAPTAB-entry. This structure is copied to te according 
MAPTAB-place. If the new installed device is the actual AUX-device, the 
routines are copied to xco* and the actual rsconf and iorec cells to. This 
function is only for installing Mag!X-friendly routines. The device number 
is returned as a success message, that is, the dev_nr is return value too.

LONG Bconmap((WORD)-301, (LONG) ptr_to_6_longs)
similar -300, but adds a device to the MAPTAB. Return message is either 
the device number selected by this function or the error code -12 EGENRL 
if it's impossible to enlarge the MAPTAB. This function will never 
transfer the vectors to xco* because a added device can't be the actual in 
the moment of adding.


Driver
------
DRVIN doesn't provides all possibilities of the Mag!X(beta)-versions. Who 
wants to write a driver running under DRVIN too, could contact me for 
details.


Versions
--------
1993-11-23
in the GEMDOS-trap only A0/D0 modified as adaption to such very unclean 
program as STZIP (least until version 2.3), ZIPJR, the PureC help system, 
Teleoffice and many others
Fopen and Fclose directed to the drivers
1993-11-28
Bug under TOS1.00 in Bconmap removed
own environment string _PNAM=DRVIN.PRG
