Datenstruktur zur Abfrage und Anzeige zustzlicher Mglichkeiten der 
seriellen (und evtl. sonstiger) Kommunikationsroutinen
====================================================================

Data structure for request and display of additional possibilities of
serial (and possibly other) communication routines
=====================================================================
Note for the English reading people: The English version is appended on 
the German, look for it!


Cookie
------
Name: RSVF  (RS232 Version Fast)
Wert: Zeiger auf Datenstruktur
      Zeiger mu <>0 sein und auf gerade Adresse weisen

Datenstruktur
-------------
Beliebig viele Objekte sind als Liste hintereinander abgelegt. An das Ende 
einer Liste kann ber eine Verkettung eine weitere Liste angehngt sein. 
Am Ende der letzten Liste befindet sich eine Ende-Kennung.

Objekt
------
Jedes Objekt ist 8 Byte lang und beginnt auf einer geraden Adresse. 
Byte 0..3 sind ein Zeiger auf den Namen der Schnittstelle (Filename) im 
ASCII-Code. Der Name mu auf einer geraden Adresse beginnen und ist 
nullterminiert.
Byte 4..7 enthalten Angaben ber die Eigenschaften des Objektes (der 
Schnittstelle). Noch nicht definierte Bits/Bytes mssen vom anlegenden 
Programm auf 0 gesetzt werden.
Sollten irgendwann zustzliche Informationen ntig werden, so wird deren 
Vorhandensein auf noch zu definierende Weise in Byte 4..7 angezeigt. Die 
Informationen selbst liegen dann vor dem Namen der Schnittstelle.

Besondere Objekte
-----------------
Bei besonderen Objekten ist Byte4.Bit7 =0.
Ende-Objekt:
 Byte 0..3  0, ein NIL-Zeiger, kennzeichnet das Ende der Datenstuktur  
Verkettungsobjekt:
 Byte 0..3  Zeiger auf die nchste Liste mit Objekten.

Eigenschaftsdefinitionen im Wert
--------------------------------
Byte 4:
 Bit7  =1: dieser Name ist eine Schnittstelle
 Bit6  =1: Schnittstelle ist dem GEMDOS fr File-I/O bekannt
 Bit5  =1: Schnittstelle ist dem BIOS bekannt (Bco*-Routinen)
 fr den Rest fllt uns noch was ein (Fhigkeiten der Schnittstelle)
 Bit0  =1: Vor dem Namen (Namensadresse-4) steht ein Zeiger
           auf ein Feld mit Zeigern auf Funktionen, wie es auch der
           Magic Version3 Funktion Dcntl bergeben wird.
Byte 5:
 noch frei 
Byte 6:
 BIOS-Nummer der Schnittstelle (Bco*-Routinen)
Byte 7:
 noch frei


Sinn und Zweck
--------------
Kommunikationsprogramme knnen durch RSVF herausfinden, welche 
Schnittstellen fr sie geeignet erscheinen. Auerdem erfahren sie die 
Zuordnung von GEMDOS-Gertetreibername (in U:\DEV\) zur BIOS-Gertenummer.


Mindestforderung an Treiber bei gesetztem GEMDOS-Bit
----------------------------------------------------
Fopen, Fclose, Fread, Fwrite, Fcntl werden behandelt. Falls eine Funktion 
(oder auch Unterfunktion von Fcntl) nicht vorhanden ist, mu dafr ein 
Fehlercode (mglst. Fehlercode -32 (EINVFN)) geliefert werden.

Fopen darf immer nur mit dem vollen Pfad "U:\DEV\devicename" erfolgen. 
Konstruktionen mit Dsetdrv und Dsetpath sind UNZULSSIG.

Fcntl hat die Funktionsnummer $0104 und die Parameter:
handle, special, subfunction
handle:      16Bit filehandle
special:     32Bit parameter for subfunction
subfunction: 16Bit number of subfunction


Funktionen
----------
Die Funktionen sind im Textfile
SERSOFST.TXT
definiert. Einige werden von meinen Treibern schon untersttzt. Siehe 
SERSOFST.TXT zu Einzelheiten und zum Status dieses (noch? nicht 
Atari-offiziellen) Standards.


Harun Scheutzow, 16.05.1993
letzte nderung: 21.11.1993
(02.01.1993: nur Textaufteilung)
Ergnzung Byte4.Bit0: 20.08.1994
Harun_Scheutzow@B.maus.de

Harun Scheutzow
Dresdener Strae 83
D-10179 Berlin, Deutschland



Data structure for request and display of additional possibilities of
serial (and possibly other) communication routines
=====================================================================

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

Cookie
------
Name:  RSVF  (RS232 Version Fast)
Value: Pointer to data structure
       pointer must be <>0 and point to an even address

Data Structure
--------------
No matter how much objects can be placed one after the other as a list. On 
the end of the list a further list can be appended. On the end of the last 
list there is an end-object.

Object
------
Every object is 8 byte long and starts on an even address. Byte 0..3 
are a pointer to the name of the interface (filename) in ASCII. The Name 
has to start on an even address and is 0-terminated.
Byte 4..7 contain information about the attributes of the object (the 
interface). Not yet defined bits/bytes must be setted to 0 by the creating 
program.
Should additional information become necessary in the future, its 
existence will be displayed by some bits in byte 4..7. The information 
itself will lay in front of the name of the interface.

Outstanding Objects
-------------------
Outstanding objects are marked by bute4.bit7 =0.
end-object:
 byte 0..3  0, a NIL-pointer, marks the end of the data structure
link-object:
 byte 0..3  pointer to the next list of objects

Attribut definitions in the value
---------------------------------
Byte 4:
 Bit7  =1: this name is an interface
 Bit6  =1: this interface is known to the GEMDOS for fileI/O
 Bit5  =1: this interface is known to the BIOS (Bco*-routines)
 for the remainder we will have ideas in the future
 Bit0  =1: Before the name (nameaddress-4) there is a pointer
           to an array of pointers to functions, as passed to the
           Magic version3 function Dcntl.
Byte 5:
 free for future use
Byte 6:
 BIOS-number of the interface (Bco*-routines)
Byte 7:
 free for future use


Sence and Purpose
-----------------
Communication programs can find out which interfaces suit themselves by 
using RSVF. Additional they get to know the assignment GEMDOS-interface 
name (in U:\DEV\) to BIOS-device number.


Least demands for driver with GEMDOS-bit set
--------------------------------------------
Fopen, Fclose, Fread, Fwrite, Fcntl are managed. If a function (or 
subfunction of Fcntl too) is not available, an error code (-32 (EINVFN) or 
so) must be returned.

Fopen is only allowed with the full path "U:\DEV\devicename". 
Constructions with Dsetdrv and Dsetpath are PROHIBITED.

Fcntl has the function number $0104 and the parameter:
handle, special, subfunction
handle:      16Bit filehandle
special:     32Bit parameter for subfunction
subfunction: 16Bit number of subfunction


Functions
---------
The functions are defined in the text file
SERSOFST.TXT
Some are supported by my drivers until now. See SERSOFST.TXT about details 
and status of this (until now? not offical Atari) standards.


Harun Scheutzow, 16.May.1993
last change: 21.Nov.1993
(02.Jan.1993: only text layout)
added Byte4.Bit0: 20.Aug.1994

Harun_Scheutzow@B.maus.de

Harun Scheutzow
Dresdener Strae 83
D-10179 Berlin, Deutschland
