@(#)XHDI/xhdispec.txt @(#)Julian F. Reschke, 22. M„rz 1992 Spezifikation des `XHDI'-Cookies, 22. M„rz 1992 ----------------------------------------------- Cookie-Kennung: "XHDI". Der Parameter zeigt auf die Adresse einer Routine, die massenspeicherbezogene Funktionen zur Verfgung 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! ALLE FUNKTIONEN MUESSEN IM SUPERVISOR-MODUS AUFGERUFEN WERDEN. Das Verhalten fr Aufrufe im User-Modus ist undefiniert. Bis auf D0 werden keine Prozessorregister ver„ndert. Undefinierte Opcodes fhren 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' fhren. Im Zweifel muž der `CEH' also vom Aufrufer abgeschaltet werden. Fr alle Funktionen seien folgende Return-Werte definiert: TOS-Fehlernummern: 0: OK (OK) -1: unspezifizierter Fehler (ERROR) -2: Ger„t nicht bereit (EDRVNR) -15: ungltige 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 Abschnitt 7.2.14 in `draft proposed American National Standard for information systems - SMALL COMPUTER SYSTEM INTERFACE - 2 (SCSI-2) March 9, 1990'). Hinweis: letztere Fehlerklasse kann logischerweise nur bei ACSI-/SCSI-Ger„ten auftreten. Bei andersartigen Ger„ten, wie zum Beispiel den IDE-Platten im ST-Book, k”nnen auch andere, hier noch nicht spezifizierte Error-Codes zurckgeliefert werden. Fr die Parameterbergabe gilt die GEMDOS-šbergabe-Konvention. Alle Parameter werden auf dem Stack abgelegt (der Opcode als 16-Bit-Wert), das Ergebnis wird in D0 zurckgeliefert. Folgende Datentypen seien vereinbart: UWORD: 16-Bit, unsigned LONG: 32-Bit, signed ULONG: 32-Bit, unsigned char *: 32-Bit, Zeiger auf eine nullterminierte Zeichenkette Termini: major: Major Device Number 0..7: Platten am ACSI-Bus mit Atari-kompatiblen Befehlssatz 8..15: Platten am SCSI-Bus 16..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 (fr 'major' 0..15: LUN des ACSI- oder SCSI-Ger„ts), maximal 255. key: Entweder ein 16-Bit-Schlssel, ermittelt von `XHReserve()', oder 0, wenn das Ger„t nicht reserviert wurde oder der Schlssel nicht bekannt ist. Die einzelnen Funktionen: ----------------------------------------------------------------------- Opcode 0: UWORD XHGetVersion (void); Liefert die Protokollversion zurck. Formatbeispiel: $0119 ist Version 1.19 (identisch mit GEMDOS-Sversion(), nur sind die beiden Bytes NICHT verdreht). Diese Version der XHDI-Spezifikation hat die Versionsnummer $0100. ----------------------------------------------------------------------- Opcode 1: LONG XHInqTarget (UWORD major, UWORD minor, ULONG *blocksize, ULONG *device_flags, char *product_name); 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 bercksichtigt. block_size: Blockgr”že auf dem Ger„t (fr `XHReadWrite()' sehr wichtig). Normalerweise 512. device_flags: (Bit gesetzt -> F„higkeit verfgbar): 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 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. 33 Zeichen inkl. Leerzeichen). Falls die Information nicht verfgbar ist, wird eine Zeichenkette der L„nge Null zurckgeliefert. Anmerkung: fr `blocksize', `device_flags' und `product_name' drfen auch Nullzeiger bergeben werden. ----------------------------------------------------------------------- Opcode 2: LONG XHReserve (UWORD major, UWORD minor, UWORD do_reserve, UWORD key); Reserviert ein Ger„t bzw. gibt es wieder frei. Auf reservierte Ger„te kann nur bei Angabe des korrekten Schlssels 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. Beim Reservieren des Ger„ts wird im Erfolgsfall ein 16-Bit-Schlssel zurckgeliefert. Dieser Schlssel muž bei allen weiteren Zugriffen auf das Ger„t angegeben sowie beim Wieder-Freigeben angegeben werden. do_reserve: (1) Reservieren oder (0) wieder freigeben. key: (nur beim Freigeben benutzt). ----------------------------------------------------------------------- Opcode 3: LONG XHLock (UWORD major, UWORD minor, UWORD do_lock, UWORD key); Verriegelt bzw. entriegelt den Auswurfknopf eines Ger„ts. Der Treiber hat sich darum zu kmmern, ob dieser Befehl an das Ger„t weitergeleitet wird oder nicht (falls das Medium nicht verriegelbar ist). Welchen Code man im Fehlerfall zurckerh„lt, ist undefiniert. Mehr Informationen werden allerdings auch nicht ben”tigt, da man ja mit `XHInqTarget()' vorher gezielt auf diese F„higkeit abtesten kann. do_lock: (1) Verriegeln oder (0) Entriegeln. key: Falls Ger„t reserviert, sonst Null bergeben. ----------------------------------------------------------------------- Opcode 4: LONG XHStop (UWORD major, UWORD minor, UWORD do_stop, UWORD key); Ger„t wird gestoppt (geparkt) bzw. gestartet (entparkt). Welchen Code man im Fehlerfall zurckerh„lt, ist undefiniert. Mehr Informationen werden allerdings auch nicht ben”tigt, da man ja mit `XHInqTarget()' vorher gezielt auf diese F„higkeit abtesten kann. do_stop: (1) Stoppen oder (0) Starten. key: Falls Ger„t reserviert, sonst Null bergeben. Anmerkung: Bei etwaigen Zugriffen auf das gestoppte Ger„t sollte der Treiber selbst fr das Wiederhochfahren sorgen. ----------------------------------------------------------------------- Opcode 5: LONG XHEject (UWORD major, UWORD minor, UWORD do_eject, UWORD key); Medium wird ausgeworfen oder eingezogen. Welchen Code man im Fehlerfall zurckerh„lt, ist undefiniert. Mehr Informationen werden allerdings auch nicht ben”tigt, da man ja mit `XHInqTarget()' vorher gezielt auf diese F„higkeit abtesten kann. do_eject: Medium auswerfen (1) oder einziehen (0). key: Falls Ger„t reserviert, sonst Null bergeben. ----------------------------------------------------------------------- Opcode 6: ULONG XHDrvMap (void); Liefert einen Bitvektor mit den ber das XHDI-Protokoll untersttzten BIOS-Ger„tenummern (wie etwa bei `Drvmap()'). ----------------------------------------------------------------------- Opcode 7: LONG XHInqDev (UWORD bios_device, UWORD *major, UWORD *minor, ULONG *start_sector, BPB *bpb); 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 zurckgesetzt). Anmerkung: es wird ein Zeiger auf eine vom Aufrufer bereitgestelle BPB-Struktur bergeben, die vom XHDI-Treiber gefllt wird. Return-Wert: 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', `minor' und `start_sector' korrekt zurckgeliefert 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 zurckgelieferte BPB ist ungltig, 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: fr `major', `minor', `start_sector' und `bpb' drfen auch Nullzeiger bergeben werden. ----------------------------------------------------------------------- Opcode 8: LONG XHInqDriver (UWORD bios_device, char *name, char *version, char *company, UWORD *ahdi_version, UWORD *maxIPL); Liefert Informationen ber den Treiber, der das angebebene Ger„t bedient. name: Zeiger auf Zeichenkette mit Treibernamen (max. 17 Zeichen). version: Zeiger auf Zeichenkette mit Versionsnummer (max. 7 Zeichen). company: Zeiger auf Zeichenkette mit Namen des Herstellers (max. 17 Zeichen). ahdi_version: AHDI-Versionslevel (wie PUN_INFO-Struktur). maxIPL: H”chster IPL, unter dem der Treiber fr das angegebene Ger„t arbeitsf„hig ist (Normalwert fr Treiber, die ihr Timing per _hz_200 erledigen: 5). Anmerkung: fr `name', `version', `company', `ahdi_version' und `maxIPL' drfen auch Nullzeiger bergeben werden. ----------------------------------------------------------------------- Opcode 9: LONG XHNewCookie (ULONG newcookie); - OPTIONALE Funktion, darf also mit EINVFN beantwortet werden - Installiert einen zus„tzlichen XHDI-Handler (Vorteil: der XHDI-Cookie zeigt nach wie vor auf die gleiche Adresse). Wer diese Funktion untersttzt 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 fhrt. 2. Anderenfalls den Cookie `per Hand' versetzen. ------------------------------------------------------------------------ Opcode 10: LONG XHReadWrite (UWORD major, UWORD minor, UWORD rwflag, ULONG recno, UWORD count, void *buf); Žquivalent zur BIOS-Funktion `Rwabs()' zum Lesen bzw. Schreiben physikalischer Blocknummern. 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. ------------------------------------------------------------------------ Installation mehrerer Programme im XHDI-Cookie ---------------------------------------------- (1) Bei der Installation feststellen, ob der Cookie schon gesetzt ist. Falls ja, mssen folgende zus„tzliche Aufrufkonventionen bercksichtigt werden: (2) Bei `XHGetVersion()' zun„chst durch den alten Vektor springen und dann das Minimun der dort erhaltenen und der eigenen Versionsnummer zurckliefern. (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.