Das Pure-C-Interface fr die XFS-Schnittstelle von MagiC >= 3
-------------------------------------------------------------


1. Einleitung
-------------

Durch die komplette Realsierung der XFS-Schnittstelle von MagiC in 
Assembler ist diese zwar schnell, aber auch sehr unkomfortabel. Mit 
diesem "Frontend" wird es mglich, ein XFS fr MagiC komplett mit Pure 
C zu erstellen. Zu diesem Zweck meldet das Interface ein Pseudo-XFS an, 
dessen Funktionen nichts weiter tun als die Parameter Pure-C-gerecht 
aufzubereiten und dann ihr C-quivalent aufzurufen. Umgekehrt stellt 
das Interface Assemblerroutinen zur Verfgung, mit denen die 
Kernelfunktionen direkt aus Pure-C-Routinen heraus aufgerufen werden 
knnen.

Durch diese Vorgehensweise geht zwar ein wenig Zeit durch die 
Umwandlung und Weiterleitung verloren, es wird mir jedoch sicherlich 
(fast) jeder zustimmen, da es einfacher und bequemer ist, ein 
Filesystem in C zu entwickeln, als dies direkt in Assembler zu tun.

Man kann mit dem Pure-C-Interface nur einzelne Filesysteme erstellen, 
also nicht zwei in ein Programm packen. Allerdings sollte das keine 
echte Einschrnkung darstellen, denn in der Regel wird man ja jedes 
Filesystem als eigenstndiges Programm entwicklen.

Es ist erlaubt, Filesysteme, die mit diesem Interface erstellt wurden, 
in beliebiger Form zu verbreiten, d.h. sie drfen als Free-, Share- 
oder Lhnware vertrieben werden. Zu den genauen Bedingungen hierzu 
steht in Abschnitt 3 genaueres.


2. Benutzung
------------

Im Prinzip ist es ganz einfach, das Interface zu benutzen. Man geht am 
besten schrittweise vor:

1. Projektfile erstellen, das den gewhnlichen Pure-C-Startupcode 
   benutzt (pcstart.o) und pc_xfs.s als zu compilierenden Quellcode 
   enthlt. Libraries wie bentigt einbinden (natrlich kein GEM, in 
   der Regel werden also pcstdlib.lib und pctoslib.lib ausreichen).
2. In jedem der eigentlichen Quellcodes des zu schreibenden Filesystems 
   mu pc_xfs.h eingebunden werden, damit die notwendigen Deklarationen 
   und externen Variablen zur Verfgung stehen.
3. In einem der C-Quellcodes mu je eine Variable bzw. Struktur des 
   Typs THE_MGX_DEV und THE_MGX_XFS definiert werden; die einzelnen 
   Elemente sind dabei die C-Funktionen, die die jeweilige Filesystem- 
   bzw. Gertetreiberaufgabe bernehmen. Welche das genau sind, 
   entnimmt man am besten der MagiC-Doku und den Deklarationen in 
   pc_xfs.h
4. Zu Beginn sollten alle Filesystem- und Gertetreiberfunktionen als 
   Leerfunktionen angelegt werden, die nur EINVFN zurckliefern. Im 
   Laufe der Entwicklung kann man sie dann der Reihe nach mit Leben 
   fllen.
5. Die Anmeldung des Filesystems geschieht ber die Funktion 
   install_xfs, der man den Zeiger auf die unter 3. genannte Variable 
   des Typs THE_MGX_XFS bergibt (die Elemente der Struktur mssen 
   dabei natrlich schon belegt sein, also die korrekten 
   Funktionszeiger enthalten). Als Ergebnis erhlt man den Zeiger auf 
   die Interface-interne Version der MagiC-Kernelstruktur, oder NULL, 
   wenn etwas nicht geklappt haben sollte. Diese Struktur wird 
   gebraucht, um die Funktionen aus der Kernelstruktur aufzurufen; 
   Variablen sollten immer aus der "echten" Struktur ausgelesen werden, 
   deren Zeiger in der externen Variable real_kernel zu finden ist. 
   Nach erfolgreicher Installation mu sich das C-Programm mit Ptermres 
   beenden.
6. Bei drv_open mu man den Zeiger auf die Filesystemstruktur in den 
   DMD eintragen; dies darf jedoch nicht die C-Struktur sein, da sie 
   nicht die ist, die vom Kernel angesprochen wird. Fr d_xfs mu immer 
   real_xfs eingetragen werden, ein externer Zeiger auf das Pseudo-XFS 
   des Assemblerteils, sonst geht's schief!

Als Anschauungsobjekt kann dabei der Quellcode des Ramdisk-XFS dienen, 
der der Originaldistribution beiliegt. Es ist auch sehr ratsam, sich 
die Datei pc_xfs.h aufmerksam anzuschauen und die Kommentare zu lesen. 
Wer Fragen hat, kann sich gerne an mich wenden, meine Adresse steht in 
Abschnitt 5.


3. Rechtliches
--------------

Das Pure-C-Interface wurde mit groer Sorgfalt entwickelt und eingehend 
getestet. Dennoch kann ich nicht ausschlieen, da es noch Fehler 
enthlt. Ich, Thomas Binder, kann daher weder fr die einwandfreie 
Funktionsfhigkeit, noch fr die Tauglichkeit zu einem bestimmten Zweck 
garantieren.

Darberhinaus erfolgt die Benutzung des Pure-C-Interfaces und aller 
damit erstellter Filesysteme auf eigene Gefahr! Ich bernehme keinerlei 
Haftung fr Schden jeglicher Art, die direkt oder indirekt durch die 
sach- oder unsachgeme Anwendung des Pure-C-Interfaces oder damit 
erstellter Filesysteme entstanden sind oder entstanden sein knnten.

Sollte jemand einen Fehler gefunden haben, bitte ich um eine 
detailierte Mitteilung, meine Adresse steht in Abschnitt 5.

Wer eigene Filesysteme erstellt hat, die auf dem Pure-C-Interface 
basieren, kann diese nach seinen Vorstellungen vermarkten, also als 
Freeware, Shareware, Lhnware, etc. Allerdings mssen folgende 
Bedingungen strikt eingehalten werden:

1. In der Startmeldung des Filesystems und in der Dokumentation mu 
   deutlich sichtbar der Hinweis erscheinen, da es mit Hilfe des Pure-
   C-Interfaces von Thomas Binder erstellt wurde.
2. Die Dokumentation mu ebenso deutlich klarstellen, da ich nicht fr 
   die korrekte Funktion des Filesystems verantwortlich gemacht werden 
   kann und keine Haftung bernehme.

Auerdem fnde ich es sehr nett, wenn ich in diesem Fall eine kleine 
Mitteilung samt Spende erhielte. Nheres im bernchsten Abschnitt.


4. Kopierbedinungen
-------------------

Das Pure-C-Interface darf frei kopiert und benutzt werden, solange alle 
Dateien (atarierr.h, mgx_xfs.inc, pc_xfs.h, pc_xfs.inc, pc_xfs.s und 
sogehts.txt) komplett und unverndert weitergegeben werden 
(Archivierung ist erlaubt).

Die Originaldistribution erfolgt immer im Rahmen meines Ramdisk-
Filesystems fr MagiC >= 3, zusammen mit einem PGP-Signaturfile, damit 
man sicherstellen kann, unvernderte Originaldateien zu haben. Meinen 
ffentlichen Schlssel gibt es auf Anfrage.


5. Kontakt mit dem Autor
------------------------

Wer Fehler gefunden oder Fragen hat, meinen ffentlichen PGP-Schlssel 
haben will, Vorschlge oder Kritik loswerden mchte oder einfach nur 
mit mir "reden" will, kann diese Adresse benutzen:

Thomas Binder
Johann-Valentin-May-Strae 7
64665 Alsbach-Hhnlein
Deutschland

Per EMail bin ich im InterNet ber folgende Adressen erreichbar:

binder@rbg.informatik.th-darmstadt.de
gryf@hrz.th-darmstadt.de (wird nicht so oft geprft)
Thomas Binder @ HD (ich tausche nur Mittwochs und Samstags)

Wer ab und zu (oder hufiger ;) ) im IRC hngt, sollte nach Gryf gucken.

Wer eigene Filesystem erstellt hat, die das Pure-C-Interface benutzen, 
sollte so fair sein und mir meine Arbeit durch eine Spende honorieren. 
Meine Bankverbindung:

Dresdner Bank AG Frankfurt am Main
Konto-Nummer: 9 024 050 00
Bankleitzahl: 500 800 00

Vielen Dank!


6. History
----------

Entfllt hier, bitte in den einzelnen Dateien nachlesen.

