This is an old version from the tos.hyp. The new is on GitHub!

HomeAnhangTOS ListeTypdefinitionen

16.8 XHDI - eXtended HardDisk Interface (Version 1.30)

Wie unschwer am Namen zu erkennen ist, soll die XHDI-Spezifikation die Möglichkeiten der Kommunikation mit Treibern für blockorientierte Massenspeicher verbessern. Ausgangspunkt war die Überlegung, einige zusätzliche Eigenschaften, die viele Treiber bereits haben, über eine dokumentierte Schnittstelle nach außen zu führen. Dies sollte speziell Virtual-Memory-Programmen die Möglichkeit geben, Wechselplatten zu verriegeln (wer wollte schon, daß die Swap-Partition während des Swappens entfernt werden kann).

Mit fortschreitender Diskussion hat sich herausgestellt, daß auch die durch die PUN_INFO-Struktur bereitgestellten Informationen nicht immer ausreichen und daher über die XHDI-Spezifikation erweitert werden sollten. Gründe:

Der Sinn und Zweck der XHDI-Spezifikation sieht damit so aus:

Nicht Sinn der Sache ist, völlig neue Anforderungen an Treiber festzulegen. Die XHDI-Spezifikation soll sich nach Möglichkeit auf einfache Weise in bestehende Treiber integrieren lassen.

Querverweis:
XHDI-Cookie   XHDI-Terminologie   Partitiontypen   Arbitration   XHDI-Funktionen   SCSI-Spezifikation

16.8.1 XHDI-Cookie

Cookie-Kennung: "XHDI". Der Parameter zeigt auf die Adresse einer Routine, die massenspeicherbezogene Funktionen zur Verfügung stellt. Zur Absicherung steht vor der Routine die Long-Konstante $27011992.

Der Wert des Cookies kann sich im laufenden Betrieb ändern (wg. Zweitinstallation). Daher ggfs. (z. B. in Accessories) den Cookie jedesmal NEU abfragen!

Installation mehrerer Programme im XHDI-Cookie:

(1) Bei der Installation feststellen, ob der Cookie schon gesetzt ist. Falls ja, müssen folgende zusätzliche Aufrufkonventionen berücksichtigt werden:
(2) Bei XHGetVersion() zunächst durch den alten Vektor springen und dann das Minimun der dort erhaltenen und der eigenen Versionsnummer zurückliefern.
(3) Bei XHDrvMap() zunächst den alten Vektor durchspringen und anschließend die eigenen Drive-Bits hineinodern.
(4) Bei den anderen Funktionen: wenn es das eigene Gerät ist, normal verfahren. Ansonsten: keinen Fehler melden, sondern durch den alten Vektor springen.

Querverweis: XHDI-Spezifikation   GEMDOS   BIOS   Cookie-Jar   SCSI-Spezifikation

16.8.2 XHDI-Terminologie

Folgende Datentypen seien vereinbart:

UWORD:  16 Bit, unsigned
LONG:   32 Bit, signed
ULONG:  32 Bit, unsigned
char *: 32 Bit, Zeiger auf eine nullterminierte Zeichenkette
major: Major Device Number
0..7: Platten am ACSI-Bus mit Atari-kompatiblen Befehlssatz
8..15: Platten am SCSI-Bus
16..17: Platten an der primären IDE-Schnittstelle
18..19: Platten an der sekundären IDE-Schnittstelle
20..23: Weitere IDE-Platten
24..63: Erweiterungen lt. PUN_INFO-Struktur (Feld: pun[])
64: Gerät am Floppycontroller
65..255: weitere eigene Erweiterungen jenseits dem, was AHDI abdeckt
minor: Minor Device Number (für 'major' 0..15: LUN des ACSI- oder SCSI-Geräts), maximal 255.
key: Entweder ein 16-Bit-Schlüssel, ermittelt von XHReserve(), oder 0, wenn das Gerät nicht reserviert wurde oder der Schlüssel nicht bekannt ist.

Notation:

Numerische Werte sind, wenn nicht anders angegeben, dezimal dargestellt. Hexadezimale Angaben (Basis 16) sind durch ein Dollarzeichen (`$') markiert.

Querverweis: XHDI-Spezifikation   GEMDOS   BIOS   SCSI-Spezifikation

16.8.3 Arbitration

Für Gerätetreiber, die den SCSI-Bus arbitrierend betreiben wollen, muß für den Rechner eine eigene Gerätekennung vergeben werden. Diese sollte natürlich einheitlich und nicht auf der Festplatte gespeichert sein. Atari hat dafür Byte 16 im NVM des Atari TT und Falcon reserviert. Die Bitbelegung ist:

Bit 0..2: Gerätenummer
Bit 7: Arbitration an (1) oder aus (0)

Die Abfrage der Gerätenummer könnte zum Beispiel wie folgt geschehen:

WORD arbitration_id (VOID)
{
   LONG ret = EINVFN;
   UBYTE nvmdata = 0;
   OSHEADER *Sys;
   LONG oldstack = Super(0L);
   Sys = *_sysbase;
   Super((VOID *)oldstack);

   host_id = -1;   /* no arbitration by default */

   if (Sys->os_version >= 0x300)
      ret = NVMaccess (0, 16, (WORD) sizeof (nvmdata), &nvmdata);

   if (ret == E_OK && (nvmdata & 0x80))
      host_id = nvmdata & 7;

   return host_id;
}

Querverweis: XHDI-Spezifikation   SCSI-Spezifikation   GEMDOS   BIOS

16.8.4 Empfohlene Partitiontypen

Typ Bedeutung
BGM GEMDOS-Partition > 16 MB
GEM GEMDOS-Partition < 16 MB
RAW Partitiontyp-RAW

Folgende Typen können optional unterstützt (zum Beispiel anhand einer konfigurierbaren Liste von Kennungen) werden.

Typ Bedeutung
F32 TOS-kompatible FAT32-Partition
LNX Linux-Ext2-Partition, sollte ggfs. wie RAW behandelt werden
MAC Mac-HFS-Partition, sollte ggfs wie RAW behandelt werden.
MIX Minix-Partition, sollte ggfs wie RAW behandelt werden.
QWA QDOS-Partition, sollte ggfs wie RAW behandelt werden.
SWP Swap-Partition, sollte ggfs wie RAW behandelt werden.
UNX ASV (Atari Systen V R4), sollte ggfs wie RAW behandelt werden.

Querverweis: XHDI-Spezifikation   GEMDOS   BIOS

16.8.4.1 Partitiontyp RAW

XHDI-1.10-kompatible Treiber müssen zusätzlich zu GEM und BGM den dritten Partitiontyp RAW unterstützen. Für Partitionen dieses Typs müssen folgende Eigenschaften unterstützt werden:

(1) Die Partitionlänge ist beliebig (im Rahmen der 32-Bit-Sektornummern).
(2) Die Partition ist als BIOS-Gerät ansprechbar; Getbpb() liefert einen Nullzeiger (damit GEMDOS keinen Zugriff versucht, zusätzlich wird auch der Media-Change-Status für das BIOS-Gerät zurückgesetzt).
(3) Es kann per Rwabs() (nicht nur im physikalischen Modus) und XHReadWrite() auf die Partition zugegriffen werden. Dabei wird die physikalische Blockgröße des Mediums benutzt (siehe XHInqTarget()).
(4) XHInqDev2() liefert im Gegensatz zu XHInqDev() auch die Länge und den Typ der Partition zurück.

Diese Erweiterungen sollen die Programmierung zuverlässiger Filesystemtreiber für MiNT (siehe zum Beispiel das Minix-FS) erleichtern.

Querverweis: XHDI-Spezifikation   GEMDOS   BIOS

16.8.5 XHDI-Funktionen

Alle Funktionen müssen im Supervisor-Modus aufgerufen werden. Das Verhalten für Aufrufe im User-Modus ist undefiniert. Bis auf D0 werden keine Prozessorregister verändert. Undefinierte Opcodes führen zur Fehlermeldung EINVFN.

Einige der Funktionsaufrufe - insbesondere XHReadWrite() - können zum Aufruf von BIOS- oder XBIOS-Routinen im Betriebssystem und damit zur Aktivierung des Critical Error Handler führen. Im Zweifel muß der CEH also vom Aufrufer abgeschaltet werden.

Für alle Funktionen seien folgende Return-Werte definiert:

TOS-Fehlernummern:

0: OK (OK)
-1: unspezifizierter Fehler (ERROR)
-2: Gerät nicht bereit (EDRVNR)
-15: ungültige Device/Targetnummer (EUNDEV)
-32: falsche Funktionsnummer (EINVFN)
-36: Gerät ist zur Zeit 'reserved' (EACCDN)
-46: BIOS-Device wird vom Treiber nicht bedient (EDRIVE)

SCSI-Fehlernummern (Bereich von -200..-455)

(-200 - N): SCSI-Errorcode N (der `Additional Sense Code' aus Byte 12 des `Extended Sense Format', siehe Anhang B in `draft proposed American National Standard for information systems - Revision 11a - SCSI-3 Primary Commands, 28 March 1997').

IDE-Fehlernummern (Bereich von -456..-711)

(-456 - N): IDE-Errorcode N (Wert des IDE-Fehlerregisters).

Hinweis: SCSI-Fehlercodes können logischerweise nur bei ACSI-/SCSI-Geräten auftreten. Für Platten am IDE-Interface des ST-Book oder Falcon030 (oder Maschinen, bei denen ein derartiges Interface nachgerüstet worden ist), kann auch optional folgende Zuordnung benutzt werden:

Bit im IDE-      
Fehlerregister Bedeutung SCSI-Fehler XHDI-Fehler
1 Track 0 not found $06 -206
0 DAM not found $13 -219
4 ID-Field not found $12 -218
7 Bad block mark $10 -216
6 Uncorrectable error $11 -217
2 Command aborted $20 -232
5 Media Change $28 -240
3 Media Change requested $5A -290

(Es empfiehlt sich, die einzelnen Bits in der angegebenen Reihenfolge zu testen).

Bei andersartigen Geräten, wie zum Beispiel Diskettenlaufwerken an der Floppy-Controller-Schnittstelle, können auch andere, hier noch nicht spezifizierte Error-Codes zurückgeliefert werden.

Für die Parameterübergabe gilt die GEMDOS-Übergabe-Konvention. Alle Parameter werden auf dem Stack abgelegt (zuletzt, also an der niedrigsten Adresse, der Opcode als 16-Bit-Wert). Das 32 Bit große Ergebnis wird in D0 zurückgeliefert.

Immer dann, wenn dokumentiert ist, daß der Aufrufer Nullzeiger übergeben darf, bedeutet die Übergabe eines Nullzeigers, daß der Aufrufer sich für den zurückzuliefernden Wert nicht interessiert. Treibersoftware muß also solche Zeiger vor einer Dereferenzierung immer überprüfen.

Querverweis: XHDI-Spezifikation   SCSI-Spezifikation   BIOS

16.8.5.1 XHDOSLimits

Name: »XHDOSLimits« - interne Limits von DOS erfragen/setzen
Opcode: 17
Deklaration: LONG XHDOSLimits ( UWORD which, ULONG limit );
Beschreibung: Diese Funktion erfragt beim Treiber die interne Limits des laufenden DOS bzw. setzt sie. Sie kann zum Beispiel von einem FAT-Dateisystemtreiber benutzt werden, um den Harddisktreiber mitzuteilen, daß sich einige Limits geändert haben. which gibt an, welches Limit erfragt wird, limit gibt den neuen Wert an (Null steht für: nicht ändern).

Ab XHDI-Version 1.30 muß ein XHDI-Treiber bei seiner Initialisierung versuchen, die Limits von einem vorhandenen Treiber zu übernehmen. Wird während des Betriebs ein Limit gesetzt, dann muß der Aufruf anschließend an andere Treiber weitergereicht werden.

which Bedeutung
XH_DL_SECSIZ (0) maximale Sektorgröße auf BIOS-Ebene
XH_DL_MINFAT (1) minimale Anzahl von FATs
XH_DL_MAXFAT (2) maximale Anzahl von FATs
XH_DL_MINSPC (3) Sektoren/Cluster minimal
XH_DL_MAXSPC (4) Sektoren/Cluster maximal
XH_DL_CLUSTS (5) maximale Clusterzahl einer 16-Bit-FAT
XH_DL_MAXSEC (6) maximale Zahl von Sektoren
XH_DL_DRIVES (7) maximale Zahl der vom DOS unterstützen BIOS-Laufwerke
XH_DL_CLSIZB (8) maximale Clustergröße


- Ab XHDI-Version 1.30 -
XH_DL_RDLEN (9) max. (bpb->rdlen * bpb->recsiz / 32)
XH_DL_CLUSTS12 (12) maximale Clusterzahl einer 12-Bit-FAT
XH_DL_CLUSTS32 (13) maximale Clusterzahl einer 32-Bit-FAT
XH_DL_BFLAGS (14) unterstützte Bits in bpb->bflags


Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: Die Funktion liefert den Wert des bisherigen Limits.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.2 XHDriverSpecial

Name: »XHDriverSpecial« - treiberspezifische Erweiterungen nutzen
Opcode: 13
Deklaration: LONG XHDriverSpecial ( ULONG key1, ULONG key2, UWORD subopcode, VOID *data );
Beschreibung: Dieser Opcode kann für treiberspezifische Erweiterungen benutzt werden. Auf welche Art und Weise die Daten in subopcode und data interpretiert werden, hängt ausschließlich vom betroffenen Treiber ab. key1 und key2 dienen zur Identifikation des anzusprechenden Treibers:

key1 sollte dabei aus vier druckbaren ASCII-Zeichen bestehen, key2 aus einem möglichst willkürlich gewählten Longwert (etwa dem Datum der Definition im BCD-Format).

Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.3 XHDrvMap

Name: »XHDrvMap« - Bitvektor mit BIOS XHDI-Gerätenummern liefern
Opcode: 6
Deklaration: ULONG XHDrvMap ( VOID );
Beschreibung: Die Funktion liefert einen Bitvektor mit den über das XHDI-Protokoll unterstützten BIOS-Gerätenummern (wie etwa bei Drvmap()).
Ergebnis: Der Rückgabewert ist der entsprechende Bitvektor.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.4 XHEject

Name: »XHEject« - Medium auswerfen bzw. wieder einziehen
Opcode: 5
Deklaration: LONG XHEject ( UWORD major, UWORD minor, UWORD do_eject, UWORD key );
Beschreibung: Medium wird ausgeworfen oder eingezogen.
Parameter Bedeutung
   
do_eject
(1) Medium auswerfen
(0) Medium einziehen
key Falls Gerät reserviert, sonst Null übergeben.
Ergebnis: Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr Informationen werden allerdings auch nicht benötigt, da man ja mit XHInqTarget() vorher gezielt auf diese Fähigkeit abtesten kann.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.5 XHGetCapacity

Name: »XHGetCapacity« - Anzahl der adressierbaren Sektoren und deren Größe ermitteln
Opcode: 14
Deklaration: LONG XHGetCapacity ( UWORD major, UWORD minor, ULONG *blocks, ULONG *blocksize );
Beschreibung: Diese Funktion liefert in blocks die Anzahl der adressierbaren Sektoren auf dem Medium und in blocksize ihre Größe zurück (Vorsicht: je nach verwendeter Hardware kann die Ausführung dieser Funktion mehrere Sekunden dauern!).

Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.6 XHGetVersion

Name: »XHGetVersion« - Protokollversion erfragen
Opcode: 0
Deklaration: UWORD XHGetVersion ( VOID );
Beschreibung: Die Funktion liefert die Protokollversion zurück. Formatbeispiel: $0119 ist Version 1.19 (identisch mit GEMDOS-Sversion(), nur sind die beiden Bytes NICHT verdreht).
Ergebnis: Der Rückgabewert beschreibt die Versionsnummer des XHDI-Protokolls. Dabei enthält das High-Byte die Versionsnummer und das Low-Byte die Revision.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.7 XHInqDev

Name: »XHInqDev« - Major, Minor Device Number, Startsektor und Bios-Parameter-Block (BPB) eines BIOS-Geräts ermitteln
Opcode: 7
Deklaration: LONG XHInqDev ( UWORD bios_device, UWORD *major, UWORD *minor, ULONG *start_sector, BPB *bpb );
Beschreibung: Liefert Major Device Number, Minor Device Number, Startsektor und BPB eines BIOS-Geräts (im Gegensatz zu Getbpb() wird dadurch der Media-Change-Status des Geräts NICHT zurückgesetzt).

Anmerkung: es wird ein Zeiger auf eine vom Aufrufer bereitgestellte BPB-Struktur übergeben, die vom XHDI-Treiber gefüllt wird.
Ergebnis: E_OK, EDRVNR (Gerät kann zur Zeit nicht angesprochen werden, zum Beispiel Medium nicht eingelegt), EDRIVE (falsche Gerätenummer) oder eine andere Fehlernummer. Bei EDRVNR darf man sich darauf verlassen, daß major und minor korrekt zurückgeliefert werden.

Ein start_sector mit Wert $FFFFFFFF soll auf eine Partition hinweisen, die zur Zeit vom Treiber nicht bedient wird (zum Beispiel, wenn ein Wechselmedium mit 'zu wenig' Partitionen eingelegt ist).

Der zurückgelieferte BPB ist ungültig, wenn das Element recsiz Null ist.

Hinweis: ein Dateisystem ist durch major- und minor Gerätenummer sowie Startsektor (mit der obigen Einschränkung) exakt spezifiziert. Über die Art des Dateisystems (FAT oder etwas anderes) ist damit nichts ausgesagt!

Anmerkung: für major, minor, start_sector und bpb dürfen auch Nullzeiger übergeben werden.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.8 XHInqDev2

Name: »XHInqDev2« - Major, Minor Device Number, Startsektor und Bios-Parameter-Block (BPB) eines Geräts erfragen
Opcode: 12
Deklaration: LONG XHInqDev2 ( UWORD bios_device, UWORD *major, UWORD *minor, ULONG *start_sector, BPB *bpb, ULONG *blocks, BYTE *partid );
Beschreibung: Liefert Major Device Number, Minor Device Number, Startsektor, BPB (im Gegensatz zu Getbpb() wird dadurch der Media-Change-Status des Geräts NICHT zurückgesetzt), Länge und Partitionkennung (maximal drei Zeichen zzgl. terminierender Null) eines BIOS-Geräts.

Anmerkung: es wird ein Zeiger auf eine vom Aufrufer bereitgestelle BPB-Struktur übergeben, die vom XHDI-Treiber gefüllt wird.

Die Funktion steht erst ab XHDI-Version 1.10 zur Verfügung.
Ergebnis: E_OK, EDRVNR (Gerät kann zur Zeit nicht angesprochen werden, zum Beispiel Medium nicht eingelegt), EDRIVE (falsche Gerätenummer) oder eine andere Fehlernummer. Bei EDRVNR darf man sich darauf verlassen, daß major und minor korrekt zurückgeliefert werden.

Ein start_sector mit Wert $FFFFFFFF soll auf eine Partition hinweisen, die zur Zeit vom Treiber nicht bedient wird (zum Beispiel, wenn ein Wechselmedium mit 'zu wenig' Partitionen eingelegt ist).

Der zurückgelieferte BPB ist ungültig, wenn das Element recsiz Null ist.

Wenn die Partitionkennung nicht verfügbar ist (keine Atari-Partitionierung oder überhaupt keine Partitionierung, beispielsweise bei normal formatierten Disketten in SCSI-Diskettenlaufwerken), wird als Partitionkennung eine leere Zeichenkette zurückgegeben.

Bei MSDOS-kompatibel partitionierten Medien wird ab XHDI-Version 1.20 die ein Byte lange Partitionkennung wie folgt in partid abgelegt: partid[0] = '\0' (Nullbyte), partid[1] = 'D' (für DOS), partid[2] = Kennung.

Hinweis: ein Dateisystem ist durch major- und minor- Gerätenummer sowie Startsektor (mit der obigen Einschränkung) exakt spezifiziert. Über die Art des Dateisystems (FAT oder etwas anderes) ist damit nichts ausgesagt!
Anmerkung: für major, minor, start_sector, bpb, blocks und partid dürfen auch Nullzeiger übergeben werden.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.9 XHInqDriver

Name: »XHInqDriver« - Informationen über den Treiber erfragen
Opcode: 8
Deklaration: LONG XHInqDriver ( UWORD bios_device, BYTE *name, BYTE *version, BYTE *company, UWORD *ahdi_version, UWORD *maxIPL );
Beschreibung: Die Funktion liefert Informationen über den Treiber, der das angesprochene Gerät bedient.
Ergebnis:
Parameter Bedeutung
   
name Zeichenkette mit Treibernamen (max. 17 Zeichen).
version Zeichenkette mit Versionsnummer (max. 7 Zeichen).
company Zeichenkette mit Namen des Herstellers (max. 17 Zeichen).
ahdi_version AHDI-Versionslevel (wie PUN_INFO-Struktur).
maxIPL: Höchster IPL, unter dem der Treiber für das angegebene Gerät arbeitsfähig ist (Normalwert für Treiber, die ihr Timing per _hz_200 erledigen: 5).
Anmerkung: für name, version, company, ahdi_version und maxIPL dürfen auch Nullzeiger übergeben werden.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.10 XHInqTarget

Name: »XHInqTarget« - Informationen über ein Gerät liefern
Opcode: 1
Deklaration: LONG XHInqTarget ( UWORD major, UWORD minor, ULONG *blocksize, ULONG *device_flags, BYTE *product_name );
Beschreibung: Liefert Informationen über das durch major und minor spezifizierte Gerät (in (device_flags: ein Attributvektor). Mit XHReserve() vorgenommene Reservierungen werden dabei berücksichtigt.
Ergebnis:
Bit Bedeutung
   
block_size Blockgröße auf dem Gerät (für XHReadWrite() sehr wichtig). Normalerweise 512.
device_flags (Bit gesetzt -> Fähigkeit verfügbar):
0 Gerät kann gestoppt werden (XH_TARGET_STOPPABLE (0x00000001L))
1 Gerät hat wechselbare Medien (XH_TARGET_REMOVABLE (0x00000002L))
2 Auswurf des Geräts kann verriegelt werden (XH_TARGET_LOCKABLE (0x00000004L))
3 Medium kann per Kommando ausgeworfen werden (XH_TARGET_EJECTABLE (0x00000008L))
29 Auswurf des Geräts ist vom Treiber blockiert worden (XH_TARGET_LOCKED (0x20000000L), ab XHDI 1.25).
30 Gerät ist vom Treiber gestoppt worden (XH_TARGET_STOPPED (0x40000000L), ab XHDI 1.25).
31 Gerät ist zur Zeit blockiert (XH_TARGET_RESERVED (0x80000000L)).

Alle weiteren Bits sind reserviert und sollten vom Treiber auf Null gesetzt werden.
product_name Produktbezeichnung des Geräts (max. 33 Zeichen inkl. Leerzeichen). Falls die Information nicht verfügbar ist, wird eine Zeichenkette der Länge Null zurückgeliefert.
Anmerkung:
- für blocksize, device_flags und product_name dürfen auch Nullzeiger übergeben werden.
- für IDE-Geräte wird bei product_name gegebenenfalls auf 32 Zeichen gekürzt. Siehe auch die neue Funktion XHInqTarget2.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.11 XHInqTarget2

Name: »XHInqTarget2« - Informationen über Gerät liefern
Opcode: 11
Deklaration: LONG XHInqTarget2 ( UWORD major, UWORD minor, ULONG *blocksize, ULONG *device_flags, BYTE *product_name, UWORD stringlen );
Beschreibung: Liefert Informationen über das durch major und minor spezifizierte Gerät (in device_flags: ein Attributvektor, in product_name: optional die Produktbezeichnung des Geräts). Mit XHReserve () vorgenommene Reservierungen werden dabei berücksichtigt.

Die Funktion steht erst ab XHDI-Version 1.01 zur Verfügung.
Ergebnis:
Parameter Bedeutung
   
block_size Blockgröße auf dem Gerät (für XHReadWrite() sehr wichtig). Normalerweise 512.
device_flags (Bit gesetzt -> Fähigkeit verfügbar):
Bit 0: Gerät kann gestoppt werden (XH_TARGET_STOPPABLE)
Bit 1: Gerät hat wechselbare Medien (XH_TARGET_REMOVABLE)
Bit 2: Auswurf des Geräts kann verriegelt werden (XH_TARGET_LOCKABLE)
Bit 3: Medium kann per Kommando ausgeworfen werden (XH_TARGET_EJECTABLE)
Bit 29: Auswurf des Geräts ist vom Treiber blockiert worden (XH_TARGET_LOCKED, ab XHDI 1.25)
Bit 30: Gerät ist vom Treiber gestoppt worden (XH_TARGET_STOPPED, ab XHDI 1.25)
Bit 31: Geräte ist zur Zeit blockiert (XH_TARGET_RESERVED)

Alle weiteren Bits sind reserviert und sollten vom Treiber auf Null gesetzt werden.
product_name Produktbezeichnung des Geräts (max. stringlen Zeichen inkl. Leerzeichen). Falls die Information nicht verfügbar ist, wird eine Zeichenkette der Länge Null zurückgeliefert.
stringlen Länge der product_name übergebenen Zeichenkette.
Anmerkung: für blocksize, device_flags und product_name dürfen auch Nullzeiger übergeben werden. Produktbezeichnungen von IDE-Geräten können bis zu 40 Zeichen lang sein.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.12 XHLastAccess

Name: »XHLastAccess« - Anzahl der Millisekunden seit dem letzten Zugriff ermitteln
Opcode: 18
Deklaration: LONG XHLastAccess ( UWORD major, UWORD minor, ULONG *ms );
Beschreibung: Liefert in ms zurück, wieviele Millisekunden seit dem letzten erfolgreichen Lese- oder Schreibzugriff auf das Gerät vergangen sind.

Diese Funktion steht erst ab XHDI-Version 1.25 zur Verfügung.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.13 XHLock

Name: »XHLock« - Auswurfknopf verriegeln bzw. entriegeln
Opcode: 3
Deklaration: LONG XHLock ( UWORD major, UWORD minor, UWORD do_lock, UWORD key );
Beschreibung: Verriegelt bzw. entriegelt den Auswurfknopf eines Geräts. Der Treiber hat sich darum zu kümmern, ob dieser Befehl an das Gerät weitergeleitet wird oder nicht (falls das Medium nicht verriegelbar ist).
Parameter Bedeutung
   
do_lock
(1) Verriegeln
(0) Entriegeln
key Falls Gerät reserviert, sonst Null übergeben.
Ergebnis: Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr Informationen werden allerdings auch nicht benötigt, da man ja mit XHInqTarget() vorher gezielt auf diese Fähigkeit abtesten kann.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.14 XHMediumChanged

Name: »XHMediumChanged« - Treiber über Mediumwechsel informieren
Opcode: 15
Deklaration: LONG XHMediumChanged ( UWORD major, UWORD minor );
Beschreibung: Diese Funktion informiert den Treiber darüber, daß das Medium in dem angegebenen Gerät gewechselt worden ist. Der Treiber sollte daraufhin so vorgehen, als habe das Gerät selbst einen Medienwechsel gemeldet.

Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: OK wird nur dann zurückgeliefert, wenn die Information richtig verarbeitet wurde (also alle logischen Laufwerke auf dem Gerät entweder deaktiviert sind oder benutzt werden können).
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.15 XHMiNTInfo

Name: »XHMiNTInfo« - MiNT spezifische Informationen setzen bzw. abfragen
Opcode: 16
Deklaration: LONG XHMiNTInfo ( UWORD opcode, VOID *data );
Beschreibung: Diese Funktion setzt MiNT-spezifische Informationen bzw. fragt diese ab.

Folgende Opcodes sind definiert (unbekannte Opcodes werden mit EINVFN quittiert, E_OK wird genau dann zurückgeliefert, wenn die verlangte Funktion korrekt ausgeführt werden konnte):

XH_MI_SETKERINFO (0) [struct kerinfo *data]

Übermittelt in data dem Treiber einen Zeiger auf die MiNT-Kernel-Info-Struktur. Der Treiber kann diese benutzen, um beispielsweise direkt Kernelfunktionen aufzurufen.

XH_MI_GETKERINFO (1) [struct kerinfo **data]

Erfragt beim Treiber die eventuell schon bekannte Adresse der MiNT-Kernel-Info-Struktur. Der Zeiger auf die Struktur wird in die in data angegebene Adresse geschrieben (wenn kein Treiber bekannt ist, wird ein Nullzeiger zurückgeliefert).

Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.16 XHNewCookie

Name: »XHNewCookie« - zusätzlichen XHDI Handler installieren
Opcode: 9
Deklaration: LONG XHNewCookie ( ULONG newcookie );
Beschreibung: Installiert einen zusätzlichen XHDI-Handler. Vorteil: der XHDI-Cookie zeigt nach wie vor auf die gleiche Adresse. Wer diese Funktion unterstützt muß also folgendes tun:
1. Falls dies der erste Aufruf dieser Art ist: anschließend so vorgehen, als hätte der XHDI-Cookie bei der Installation bereits auf newcookie gezeigt.
2. Falls nicht: Funktion an 'nächsten' Handler weiterleiten.


Wer eine Mehrfachinstallation vornehmen möchte, sollte so vorgehen:
1. Testen, ob XHNewCookie() zum Erfolg führt.
2. Anderenfalls den Cookie `per Hand' versetzen.


Achtung: Diese Funktion ist optional, daher darf ein Aufruf mit EINVFN beantwortet werden.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.17 XHReaccess

Name: »XHReaccess« - Gerät auf Mediachange überprüfen
Opcode: 19
Deklaration: LONG XHReaccess ( UWORD major, UWORD minor );
Beschreibung: Ein Aufruf dieser Funktion veranlaßt den Treiber, das angegebene Gerät auf einen Mediachange zu überprüfen und gegebenenfalls die Partitioninformationen entsprechend zu aktualisieren. Die Funktion entspricht im wesentlichen XHMediumChanged(), nur daß der Treiber selbst das Gerät befragt, ob ein Medienwechsel stattgefunden hat.

Diese Funktion steht erst ab XHDI-Version 1.25 zur Verfügung.
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.18 XHReadWrite

Name: »XHReadWrite« - physikalische Blocknummern lesen/schreiben
Opcode: 10
Deklaration: LONG XHReadWrite ( UWORD major, UWORD minor, UWORD rwflag, ULONG recno, UWORD count, VOID *buf );
Beschreibung: Äquivalent zur BIOS-Funktion Rwabs() zum Lesen bzw. Schreiben physikalischer Blocknummern.
Parameter Bedeutung
   
rwflag
Bits 0..2: wie in den AHDI-Release-Notes (3.00, 18. April 1990) beschrieben.
Bit 3: (physikalischer Modus) wird ignoriert.

Alle weiteren Bits sind reserviert und auf Null zu setzen.
recno Sektornummer
count Anzahl der Blöcke
buf Zeiger auf Puffer
Ergebnis: XHDI-Fehlercodes
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.19 XHReserve

Name: »XHReserve« - Gerät reservieren bzw. wieder freigeben
Opcode: 2
Deklaration: LONG XHReserve ( UWORD major, UWORD minor, UWORD do_reserve, UWORD key );
Beschreibung: Reserviert ein Gerät bzw. gibt es wieder frei. Auf reservierte Geräte kann nur bei Angabe des korrekten Schlüssels per XHLock(), XHStop() oder XHEject() zugegriffen werden.

Sinn: man möchte nicht, daß man eine Wechselplatte per CPX-Modul entriegeln kann, nachdem sie gerade von einer virtuellen Speicherverwaltung verriegelt worden ist. Dies sollte nur die Speicherverwaltung selbst machen können.
Parameter Bedeutung
   
do_reserve
(1) Reservieren
(0) wieder freigeben
key nur beim Freigeben benutzt
Ergebnis: Beim Reservieren des Geräts wird im Erfolgsfall ein 16-Bit Schlüssel zurückgeliefert. Dieser Schlüssel muß bei allen weiteren Zugriffen auf das Gerät angegeben sowie beim Wieder-Freigeben angegeben werden.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

16.8.5.20 XHStop

Name: »XHStop« - Gerät stoppen bzw. wieder starten
Opcode: 4
Deklaration: LONG XHStop ( UWORD major, UWORD minor, UWORD do_stop, UWORD key );
Beschreibung: Gerät wird gestoppt (geparkt) bzw. gestartet (entparkt).
Parameter Bedeutung
   
do_stop
(1) Stoppen
(0) Starten
key Falls Gerät reserviert, sonst Null übergeben.


Anmerkung: Bei etwaigen Zugriffen auf das gestoppte Gerät sollte der Treiber selbst für das Wiederhochfahren sorgen.
Ergebnis: Welchen Code man im Fehlerfall zurückerhält, ist undefiniert. Mehr Informationen werden allerdings auch nicht benötigt, da man ja mit XHInqTarget() vorher gezielt auf diese Fähigkeit abtesten kann.
Gruppe: XHDI-Funktionen
Querverweis: Arbitration   _drvbits   Partitiontypen   Systemvariablen   XHDI-Cookie   XHDI-Funktionen   XHDI-Terminologie

HomeAnhangTOS ListeTypdefinitionen