     Die Hardware-Debugger-Schnittstelle von Turbo Debugger
     ======================================================

Mit einer Hardware-Debugger-Platine wird die Arbeit mit bestimmten Break-
points wesentlich beschleunigt, besonders bei Breakpoints, die ausgelst
werden, wenn eine Variable oder Objekt im Speicher verndert wird. Turbo
Debugger ist in der Lage, mit solchen Platinen zusammenzuarbeiten.

In dieser Datei wird beschrieben, wie ein Gertetreiber fr Turbo Debugger
aussehen mu, um die Mglichkeiten einer solchen Hardware-Debugger Platine
nutzen zu knnen. Diese Informationen sind auch fr Hersteller von
Hardware-Debuggern gedacht, die wollen, da ihr Produkt den Turbo Debugger
untersttzt.

Voraussetzung ist, da Sie den allgemeinen Aufbau eines DOS-Gertetreibers
kennen. Weitere Informationen zum Schreiben von Gertetreibern erhalten Sie
im DOS-Handbuch Technical Reference.


TDH386.SYS: Der Gertetreiber fr den 80386-Prozessor
-----------------------------------------------------
Der auf den Disketten enthaltene Gertetreiber TDH386.SYS dient dazu, die
Debug-Register des 80386 Prozessors fr Turbo Debugger zur Verfgung zu
stellen. Um den Treiber zu installieren, fgen Sie folgende Zeile in der
Datei CONFIG.SYS ein:

    DEVICE = TDH386.SYS

Wenn der TDH386.SYS-Treiber nicht im Stammverzeichnis, sondern in einem
anderen Verzeichnis liegt, mssen Sie den entsprechenden Verzeichnispfad
mit dem Dateinamen angeben.

Turbo Debugger wird, wann immer mglich, die Debug-Register des 80386
Prozessors verwenden, um die Arbeit mit Breakpoints zu beschleunigen.

Dies bedeutet, da Sie diesen Gertetreiber nur dann verwenden knnen,
wenn Ihr Rechner mit einem 80386-Prozessor oder hher ausgestattet ist.


Setzen von Hardware-Breakpoints
-------------------------------
Weitere Informationen ber das Hardware-Debuggen mit dem Turbo Debugger
erhalten Sie in der Datei HDWDEBUG.TD.

berblick ber den Hardware-Debugger
------------------------------------
Die Gertetreiberschnittstelle bietet einen gerteunabhngigen Zugriff auf
die Mglichkeiten verschiedener Hardware-Debugger. Um dies zu erreichen,
wurden viele allgemein verbreitete Eigenschaften von Hardware-Debuggern zu
einem allgemeinen Hardware-Debugger-Modell kombiniert. Turbo Debugger ver-
wendet dieses abstrakte Modell bei seinen Zugriffen auf den Gertetreiber.

Es hngt von den Fhigkeiten der speziellen Debugger-Platine ab, ob alle
Operationen, die in der abstrakten Schnitttstelle vorhanden sind, unter-
sttzt werden. Wenn das nicht der Fall ist, kann der Gertetreiber
Turbo Debugger informieren, da die angeforderte Operation nicht ausgefhrt
werden kann. Eine Debugger-Platine kann auch mehr bieten, als in der ab-
strakten Schnittstelle definiert ist. In diesem Fall kann Turbo Debugger 
die zustzlichen Mglichkeiten der Platine nicht ausntzen.

Da wir erwarten, da die Gertetreiberschnittstelle in zuknftigen 
Versionen neue Eigenschaften aufweisen wird, haben wir ein Statusfeld fr
die Implementationsebene definiert, das der Gertetreiber auf Anfrage
zurckgibt. Damit erfhrt Turbo Debugger, was der Gertetreiber alles kann.
Auf diese Weise bleibt die Kompatibilitt mit den alten Gertetreibern er-
halten, whrend trotzdem die Vorteile neuerer Versionen dieser Schnitt-
stelle gentzt werden knnen.

Die Hardware-Debugger-Schnittstelle teilt die Mglichkeiten einer Debugger-
Platine in drei Funktionsbereiche ein:

1.  Breakpoints fr Speicherbereiche und Ein-/Ausgabeports;

2.  Befehlsrckverfolgung;

3.  Zustzlicher Speicher fr Symboltabellen auf der Platine.

Diese Version der Schnittstelle untersttzt nur die erste Kategorie. In
zuknftigen Versionen wird eine Schnittstelle definiert, die auch auf die
anderen Mglichkeiten zurckgreift. Wenn Sie einen Gertetreiber schreiben,
drfen Sie nicht vergessen, da diese Fhigkeiten zu einem spteren Zeit-
punkt noch untersttzt werden.

Die Schnittstelle des Gertetreibers
------------------------------------
TDH386.SYS ist ein gewhnlicher Gertetreiber auf der Basis einzelner 
Zeichen,
im Gegensatz zu den Blockgertetreibern. Sie mssen folgende Anweisung in 
Ihre CONFIG.SYS-Datei aufnehmen, damit der Treiber beim Systemstart geladen
werden kann:

    DEVICE = TrbrName.Ext

wobei TrbrName.Ext der Name des Gertetreibers ist, den Sie erzeugt haben.
Der Gertetreiber mu die folgenden Funktionsaufrufe untersttzen:

INIT-Befehl (Code = 0)
Dieser Befehl wird nur einmal, nmlich beim Laden des Gertetreibers,
aufgerufen. Der Programmcode in dieser Funktion mu sicherstellen, da die
Hardware-Platine ausgeschaltet ist und nichts macht.

READ-Befehl (Code = 4)
Dieser Befehl wird von Turbo Debugger aufgerufen, um den Statusblock zu
lesen, der beim letzten Befehl an den Gertetreiber geschickt wurde. Sie 
sollten den letzten Statusblock in einem Datenbereich innerhalb des Treibers
speichern und soviele Byte, wie angefordert wurden, zurckgeben. Jedesmal,
wenn ein READ-Befehl kommt, mssen Sie den Statusblock von Beginn an 
zurcksenden, auch wenn bei einer vorhergehenden READ-Anforderung nicht genug 
Zeit blieb, um den gesamten Block zu senden.

Im nchsten Abschnitt werden die verschiedenen Statusblcke, die der 
Gertetreiber bei den einzelnen Befehlen zurckliefern kann, beschrieben.

READNOWAIT-Befehl (Code = 5)
Bei diesem Befehl wird das erste Byte des Statusblocks zurckgegeben. Das
Busy-Bit sollte immer auf 0 gesetzt sein, damit angezeigt wird, da Daten
jederzeit verfgbar sind.

READSTATUS-Befehl (Code = 6)
Setzt das Busy-Bit immer auf 0. Damit wird angezeigt, da ein nachfolgender
READ-Zugriff sofort durchgefhrt werden kann.

READFLUSH-Befehl (Code = 7)
Setzt das Done-Bit im Return-Status.

WRITE-Befehl (Code = 8)
Dieser Befehl wird von Turbo Debugger aufgerufen, um einen Befehl an den
Gertetreiber zu senden. Der Befehl hat eine variable Lnge, die vom je-
weiligen Befehlstyp abhngt. Sie knnen entweder die Daten in den Arbeits-
bereich des Gertetreibers kopieren oder direkt ber einen Zeiger, der
Bestandteil des Aufrufes des Gertetreiber ist, zugreifen.

Die folgenden Funktionsaufrufe sind Befehlsblcke, die Turbo Debugger dem
Gertetreiber senden kann:

WRITEVERIFY (Command code = 9)
Macht dasselbe wie WRITE (Befehlscode 8).

WRITESTATUS (Command code = 10)
Setzt lediglich das Done-Bit im Return-Status.

WRITEFLUSH (Command code = 11)
Setzt nur das Done-Bit im Return-Status.

Alle anderen Funktionsaufrufe sollten das Fehler-Bit (Bit 15) im Return-
Status setzen und den Fehler-Code 3 fr Unknown command im niederwertigen
Byte des Statusworts angeben.


Befehlsblcke, die zum Gertetreiber geschickt werden
-----------------------------------------------------

Alle Befehlsblcke, die mit der WRITE-Funktion zum Gertetreiber geschickt
werden, beginnen mit einem Byte, das die Operation, die ausgefhrt werden
soll, beschreibt. Das nachfolgende Byte enthlt zustzliche Informationen
zum jeweiligen Befehl.

Wenn Sie einen Hardware-Breakpoint setzen, dann liegt es in der Verant-
wortung des Gertetreibers, zu berprfen, ob ein akzeptabler Parameter-
block bergeben wurde. Der Treiber kann nicht einfach ein Feld ignorieren,
in dem eine Operation angefordert wurde, die er nicht ausfhren kann. Sie
mssen jedes einzelne Feld berprfen und sicherstellen, da die Hardware
die angeforderte Operation untersttzt, und wenn dies nicht der Fall ist,
mu der entsprechende Return-Code zurckgegeben werden. Das erste Byte kann
einen der folgenden Befehlscodes enthalten:

0   Vektoren installieren
1   Leistungsumfang der Hardware ermitteln
2   Hardware-Breakpoints einschalten
3   Hardware-Breakpoints ausschalten
4   Hardware-Breakpoint setzen
5   Hardware-Breakpoint lschen
6   E/A-Basisadresse festlegen, Hardware-Reset
7   Vektoren entfernen

Die folgenden Befehle senden zustzliche Daten hinter dem Befehlscode.


Vektoren installieren (Code 0)

4 Byte  FAR-Zeiger auf Vektor-Routine

        Dies ist ein 32-Bit-Zeiger, in dem der Offset im ersten und das
        Segment im zweiten Wort steht. Sie mssen diese Adresse speichern,
        damit sie der Gertetreiber anspringen kann, wenn ein Hardware-
        Breakpoint auftritt. Diese Routine sollte auch alle Interrupt-
        Vektoren installieren, die der Gertetreiber bentigt. Turbo
        Debugger ruft diese Routine nur einmal beim Start auf. Die
        Funktion Vektoren entfernen (Code 7) wird ebenfalls nur einmal
        aufgerufen, wenn Turbo Debugger den Gertetreiber nicht mehr
        bentigt. Dann sollten Sie alle Vektoren, die Sie beim Aufruf der
        Funktion Vektoren installieren (Code 0) belegt hatten, wieder
        freigeben und sicherstellen, da die Hardware ausgeschaltet wird.


Hardware-Breakpoint setzen (Code 4)

1 Byte  Breakpoint-Typ

        Bit  Funktion

        0    Speicher lesen
        1    Speicher beschreiben
        2    Speicher lesen oder beschreiben
        3    E/A lesen
        4    E/A schreiben
        5    E/A lesen oder schreiben
        6    Befehlszugriff

1 Byte  Gesuchte Adressen

        Bit  Funktion

        0    alle Adressen
        1    Gleich dem Testwert
        2    Ungleich dem Testwert
        3    Grer als der Testwert
        4    Kleiner als der Testwert
        5    Kleiner als der Testwert oder gleich
        6    Grer als der Testwert oder gleich
        7    Innerhalb des Bereichs
        8    Auerhalb des Bereichs

4 Byte  Niederwertige Adresse

        Eine lineare 32-Bit-Speicheradresse. Wenn der Adressierungsmodus
        eine oder mehrere Adressen zum Vergleich bentigt, wird hier der
        erste oder aber der niederwertige Teil der Adresse(n) abgelegt.

4 Byte  Hherwertige Adresse

        Eine lineare 32-Bit-Speicheradresse. Wenn der Adressierungsmodus
        zwei Adressen fr den Vergleich eines Bereichs bentigt, dann wird
        die zweite oder aber die hherwertige Adresse angegeben.

2 Byte  Durchlaufzhler

1 Byte  Gesuchte Datengre 

        1   Byte
        2   Wort
        4   Doppelwort

1 Byte  Quelle des gesuchten Bus-Zyklus:

        1   CPU
        2   DMA
        3   Entweder DMA oder CPU

1 Byte  Gesuchte Daten

        Bit  Funktion

        0    Alle Daten
        1    Gleich dem Testwert
        2    Ungleich dem Testwert
        3    Grer als der Testwert
        4    Kleiner als der Testwert
        5    Kleiner als der Testwert oder gleich
        6    Grer als der Testwert oder gleich
        7    Innerhalb des Bereichs
        8    Auerhalb des Bereichs

4 Byte  Niederwertige Datenangabe
        Wenn fr die gesuchten Daten ein oder mehrere Werte bentigt
        werden, dann wird in diesem Feld der erste oder einzige Wert
        angegeben. ber die Gre der gesuchten Daten wird festgelegt,
        wieviele Bytes in diesem Feld signifikant sind.

4 Byte  Hherwertige Datenangabe

        Wenn fr die gesuchten Daten zwei Werte bentigt werden, dann ent-
        hlt dieses Feld den zweiten Wert. ber die Gre der gesuchten 
        Daten wird festgelegt, wieviele Bytes in diesem Feld signifikant
        sind.

4 Byte  Datenmaske

        Wenn die Hardware die berprfung einzelner Bits untersttzt, 
        steuert dieses Feld, welche Bits in den Daten fr die
        Vergleichsmaske verwendet werden.


Hardware-Breakpoint lschen (Code 5)

1 Byte  Das Handle des Breakpoint, der gelscht werden soll. Das Handle
        wurde Turbo Debugger beim Befehl Hardware-Breakpoints setzen
        (Code 4) bergeben.


E/A-Basis-Adresse setzen (Code 6)

2 Byte  Die Basisadresse des Hardware-Debuggers.


Statusblcke, die vom Gertetreiber zurckgegeben werden
--------------------------------------------------------
Beim Aufruf der READ-Funktion wird der Statusblock vom Gertetreiber zu-
rckgegeben. Verschiedene Befehle, die an den Gertetreiber geschrieben
werden, bewirken, da verschiedene Statusblcke angelegt werden msssen,
in denen mitgeteilt wird, was passiert ist. Der Statusblock wird mit einem 
Byte eingeleitet, in dem das Gesamtresultat der angeforderten Operation
mitgeteilt wird. Die nachfolgenden Byte liefern zustzliche Informationen
fr den jeweiligen Befehl, der den Statusblock erzeugt hat. Die folgenden
Statuscodes knnen im ersten Byte zurckgegeben werden:

0   Befehl war erfolgreich

1   Ungltiges Handle

2   Es knnen keine weiteren Breakpoints mehr gesetzt werden.

3   Der Breakpoint konnte nicht gesetzt werden. Die Hardware ist nicht in
    der Lage, die geforderte Kombination aus Parametern fr Bus-Zyklus,
    Adresse und Daten zu untersttzen.

4   Befehl kann wegen der Beschrnkungen nicht durchgefhrt werden, die 
    dem Hardware-Debugger durch einen vorausgegangenen Befehl auferlegt 
    wurden.

    Der Befehl htte im Grunde genommen ausgefhrt werden knnen, wenn dies
    nicht durch einen vorausgegangenen Befehl verhindert worden wre. Das
    kann zum Beispiel passieren, wenn die Hardware nur einen Datenwert
    berwachen kann, Turbo Debugger aber einen zweiten Breakpoint mit einem
    anderen Wert als dem ersten setzen will.

5   Der Gertetreiber findet den Hardware-Debugger nicht.

6   Es ist ein Hardware-Fehler aufgetreten.

7   Ein unzulssiger Befehlscode wurde an den Gertetreiber geschickt.

8   Der Treiber wurde noch nicht mit der Funktion Vektoren installieren
    (Code 0) initialisiert, so da nichts gemacht werden kann.

Die folgenden Befehle geben zustzliche Statusinformationen hinter dem
Statuscode-Byte zurck:

Hardware-Mglichkeiten ermitteln (Code 1)

2 Byte  Die Versionsnummer der Gertetreiberschnittstelle. 
        Die aktuelle Version ist 1, nachfolgende Versionen werden eine 
        hhere Nummer haben.

2 Byte  Die Versionsnummer der Gertetreiber-Software. 
        Da sich jede Version eines Gertetreibers anders verhlt, sollte
        dieses Feld die entsprechende Versionsnummer enthalten. Ausgehend
        von diesem Feld kann Turbo Debugger eventuell besondere Manahmen
        ergreifen.

1 Byte  Maximale Anzahl an Hardware-Breakpoints, die von dieser
        Treiber/Platinen-Kombination untersttzt werden.

1 Byte  Konfigurationsbits

        Bit  Funktion
        ---  --------
        0    zwischen CPU- und DMA-Zugriffen wird unterschieden
        1    DMA-Transfers werden erkannt
        2    Datenmasken werden untersttzt
        3    Durchlaufzhler existiert in Hardware
        4    Test auf Werte und auf Adressen mglich

1 Byte  Untersttzte Breakpoint-Arten (Bitmaske)

        Bit  Funktion
        ---  --------
        0    Speicher lesen
        1    Speicher schreiben
        2    Speicher lesen oder schreiben
        3    E/A lesen
        4    E/A schreiben
        5    E/A lesen oder schreiben
        6    Befehlszugriff

2 Byte  Untersttzte Adre-Modi (Bitmaske)

        Bit  Funktion
        ---  --------
        0    alle Adressen
        1    Gleich dem Testwert
        2    Ungleich dem Testwert
        3    Grer als der Testwert
        4    Kleiner als der Testwert
        5    Kleiner als der Testwert oder gleich
        6    Grer als der Testwert oder gleich
        7    Innerhalb des Bereichs
        8    Auerhalb des Bereichs

2 Byte  Gesuchte Daten (Bitmaske)

        Bit  Funktion
        ---  --------
        0   Alle Daten
        1   Gleich dem Testwert
        2   Ungleich dem Testwert
        3   Grer als der Testwert
        4   Kleiner als der Testwert oder gleich
        5   Kleiner als der Testwert oder gleich
        6   Grer oder gleich dem Testwert
        7   Innerhalb des Bereichs
        8   Auerhalb des Bereichs

1 Byte  Maximale Lnge der gesuchten Daten

        Dieses Byte wird auf den Wert 1, 2 oder 4 gesetzt, je nach
        der Datengre oder der Gre der Suchmaske, die von der Hard-
        ware untersttzt wird.

2 Byte  Speicher in KByte auf der Platine

2 Byte  Anzahl der Ereignisse, die zurckverfolgt werden knnen

2 Byte  Adresse des Byte, das anzeigt, ob Hardware-Breakpoints ein-
        geschaltet sind

        Gibt die Segment-Adresse einer Speicherstelle an, in die Turbo
        Debugger den Wert 1 eintrgt, um hardware-untersttzte Breakpoints
        einzuschalten. Diese Speicherstelle mu den Wert 0 enthalten, wenn
        der Treiber diese Mglichkeit nicht untersttzt. Wird sie unter-
        sttzt, dann nutzt Turbo Debugger dieses Byte dazu, dem Treiber
        mitzuteilen, da er den Zugriff auf den Datenbereich des zu debug-
        genden Programms beendet hat, und ein folgender Zugriff einen
        Hardware-Breakpoint auslsen kann.


Hardware-Breakpoint setzen (Code 4)

1 Byte  Ein Handle, mit dem Turbo Debugger auf diesen Breakpoint zugreifen
        kann. Der Gertetreiber verwendet diesen Handle auch, wenn er an
        Turbo Debugger zurckmeldet, da ein Hardware-Breakpoint ausgelst
        wurde. Der Handle mu grer oder gleich 0 sein. Negative Werte 
        (bei denen das oberste Bit gesetzt ist), zeigen einen Spezialfall 
        an, wenn der Gertetreiber den Debugger mit einem Hardware-
        Breakpoint aufruft.


Rekursiver Aufruf (Code -2)

1 Byte  Der Spezialcode FEh kann vom Hardware-Gertetreiber zurckgegeben
        werden, wenn whrend der Ausfhrung eines Hardware-Breakpoint der
        Gertetreiber rekursiv aufgerufen wurde. Dies kann dann der Fall
        sein, wenn der Hardware-Breakpoint 6 Byte unterhalb der Spitze des
        aktuellen Stack im Programm gesetzt wurde. Wenn Turbo Debugger
        diesen Eintritts-Code erhlt, gibt das Programm eine Fehlermeldung
        aus, die besagt, da der Gertetreiber nicht weitermachen kann,
        weil ein Breakpoint in der Nhe der Stackspitze gesetzt wurde.


Gertetreiber-Aufruf an Turbo Debugger
--------------------------------------
Wenn die Debugger-Hardware und die Gertetreiber-Software auf einen
Hardware-Breakpoint gestoen sind, wird die Kontrolle an die Adresse
in Turbo Debugger bergeben, die mit dem Befehlscode 0 (Set Hardware Break-
point Vector) angegeben wurde.

Die Vektoradresse mu mit demselben CPU-Status angesprungen werden, wie zu
dem Zeitpunkt, als der Hardware-Breakpoint auftrat, wobei jedoch das 
AX-Register des Programms auf den Stack gelegt wird und ein neuer 
Eintrittscode im AH-Register steht. Der Eintrittscode kann folgenden Werte
annehmen:

    >=  0     Handle des ausgelsten Breakpoints
    -1  (FF)  Breakpoint-Taste wurde gedrckt

Turbo Debugger kehrt zu einem Gertetreiber nicht mehr zurck, wenn er
einmal von einem Hardware-Breakpoint aus angesprungen wurde.


                                - ENDE -