     **********************************************************************
     *                                                                    *
     *                 PEACEBUG, Config                                   *
     *                 ----------------                                   *
     *                                                                    *
     * written by:     Emanuel Mcklin                                    *
     *                 Zschokkestrasse 7                                  *
     *                 CH-8037 Zrich                                     *
     *                 FREDDY@ezrz1.vmsmail.ethz.ch                       *
     *                                                                    *
     * written with:   Turboassembler 1.xx                                *
     *                                                                    *
     **********************************************************************


     0. Einleitung
     -------------

     Allgemeines:
       PEACEBUG-Config dient dazu, die Schnittstelle von PEACEBUG komforta-
       bel bedienen zu knnen. Sie knnen damit entweder einen resident
       installierten Debugger oder aber PEACEBUG.PRG (auf Disk/Platte) kon-
       figurieren.
       Weitere Erklrungen zu den einstellbaren Variablen, die in den
       folgenden Kapiteln erwhnt werden, finden Sie im Liesmich zu PEACE-
       BUG, Kapitel "Schnittstelle".
       Es luft als Accessory und als Programm, auf allen mir bekannten und
       unbekannten TOS-Versionen, Rechnern der ST(E)/TT/FALCON Reihe und
       allen sonstigen mglichen und unmglichen Rechnerkonfigurationen.
       Das Resourcefile ist im Programm integriert.

     Dialoge:
       Smtliche Dialoge liegen in Fenstern und sind nicht modal.
       Das Anklicken des "Abbruch"-Buttons verwirft die nderungen.
       Das Anklicken des "OK"-Buttons bernimmt die nderungen.
       Einige Dialoge haben zustzlich den  Button "Setzen", welcher die
       Einstellungen bernimmt, aber im Gegensatz zu "OK" den Dialog nicht
       beendet. nderungen, die mit "Setzen" bernommen wurden, knnen mit
       "Abbruch" nicht mehr rckgngig gemacht werden.
       UNDO hat den gleichen Effekt, wie das Anklicken des "Abbruch"-
       Buttons.
       RETURN hat den gleichen Effekt, wie das Anklicken des "OK"-Buttons.
       Control Q schliesst alle Fenster und beendet das Programm. Die
       nderungen aller geffneten Fensters werden verworfen.
       Control W und der Closebutton des Fensters schliessen das oberste
       Fenster und bernehmen die nderungen.
       Bei Programmstart oder bei Aufruf des Accessories erscheint das
       Hauptmen, das es Ihnen erlaubt, die brigen Dialoge aufzurufen.

     Arbeitsmodi:
       Es wird grundstzlich zwischen zwei verschiedenen Arbeitsmodi unter-
       schieden, dem Patchmodus und dem Konfigurationsmodus:
       - Konfigmodus: Bei jedem Aufruf des Dialogs werden die Parameter,
         die sich in diesem Dialog verndern lassen, vom resident instal-
         lierten Debugger kopiert und wieder zurckgeschrieben, falls Sie
         den Dialog mittels "OK" beenden. Der Konfigmodus wird default-
         mssig eingestellt, wenn ein Debugger bei Programmstart oder bei
         Aufruf des Accessories installiert ist.
         Seit Version 1.16 von PBUGCONF ist es mglich, mehrere Debugger
         mit einem einzigen PBUGCONF zu konfigurieren.
       - Patchmodus: Die Parameter werden nicht aus dem Debugger geholt und
         auch nicht zurckgeschrieben. Dies erlaubt es Ihnen, die Parameter
         zu ndern und anschliessend in PEACEBUG.PRG oder PBUGCONF.PRG/ACC
         zu speichern.
       Weil nicht alle Parameter den Status p(=patch) haben (---> Liesmich
       PEACEBUG, Kapitel "Schnittstelle"), sind einige Parameter im Patch-
       modus nicht vernderbar.

     Wenn Sie sich fr den Sourcecode interessieren, schicken Sie mir eine
     formatierte Diskette oder eine E-Mail. Sie erhalten dann die neuste
     Version auf gleichem Weg zurck. Fehlerreports oder Anregungen sind
     natrlich ebenfalls willkommen.

     Die folgenden Kapitel beschreiben der Reihe nach die einzelnen
     Dialoge, die Sie vom Hauptmen aus aufrufen knnen.


     1. Information
     --------------

     Dieser Punkt braucht wohl keine weiterfhrenden Erklrungen...


     2. Vektoren
     -----------

     Dieser Dialog erlaubt es Ihnen, zwei Dinge festzulegen:
     1. Wie PEACEBUG reagiert, wenn eine bestimmte Exception auftritt.
     2. Wie die Routine VEKTOR (---> Liesmich PEACEBUG, Kapitel "Vektoren")
        bei Aufruf reagieren soll (VEKTOR wird bei jedem Einsprung und bei
        Drcken einer Funktionstaste oder RETURN/ENTER aufgerufen).

     So gehen Sie vor:
     1. Zuerst whlen Sie auf der linken Seite unter "Exceptions" den Vek-
        tor, den Sie konfigurieren wollen.
     2. Anschliessend whlen Sie unter "Aktion", wie der Debugger bei
        Auftreten der ausgewhlten Exception reagieren soll. Drei Mglich-
        keiten stehen Ihnen zur Verfgung:
        - Debugger: Der Debugger wird aufgerufen und das Auftreten der
          Exception angezeigt.
        - Original: Der Debugger ignoriert die Exception und leitet Sie
          unverndert weiter (normalerweise das OS).
        - Ignorieren: Die Exception wird korrigiert, d.h. es wird der
          Befehl angesprungen, der demjenigen folgt, der die Exception
          ausgelst hat.
        Bei Auftreten eines move sr,<ea> erfolgt bei allen MC680x0 mit x>0
        eine Privilegsverletzung, weil diese Adressierungsart nur im Super-
        visormodus erlaubt ist. Aus diesem Grund erscheinen bei der Excep-
        tion "Privileg"(=Privileg Violation) zwei weitere Buttons, die es
        Ihnen erlauben, auf diesen Fall zu reagieren:
        - SR,<ea>: Der Befehl wird im Supervisormodus ausgefhrt, ohne dass
          das Programm etwas davon merkt. Im Gegensatz zur TOS eigenen
          Routine funktioniert dies mit der debuggereigenen bei allen
          Befehlen wie z.B.:
          move sr,([-1,A7,D0.l*8],-1).
        - CCR,<ea>: Das SR im Befehl wird direkt in ein CCR umgewandelt,
          also z.B. move sr,d0 in ein move ccr,d0 (d.h. der Programmcode
          wird direkt gepatcht).
        Beim Vektor Reset erscheinen zwei zustzlichen Punkte:
        - Immer: bedeutet, dass ein Reset innerhalb des Debuggers immer
          abgefangen wird.
        - 1mal/Sek.: bedeutet, dass der Reset innerhalb des Debuggers ein-
          mal pro Sekunde abgefangen wird. D.h. wenn Sie innerhalb einer
          Sekunde zweimal reseten, wird der Reset nicht mehr abgefangen.
        Sind beide Punkte nicht angewhlt, dann wird ein Reset innerhalb
        des Debuggers nie abgefangen.
        Ausserhalb des Debuggers bedeutet:
        - Debugger: Der Debugger fngt den Reset ab, aber da der PC
          verloren geht, kann das Programm nicht fortgesetzt werden.
        - Original: Der Reset wird "weitergeleitet".
        - Ignorieren: Die Programme, die im Resetvektor hngen werden nicht
          angesprungen und ein Kaltstart wird ausgelst.
     3. Schliesslich legen Sie noch fest, wie die Routine VEKTOR arbeiten
        soll (die Werte in Klammern entsprechen denjenigen im Liesmich
        PEACEBUG, Kapitel "Das hherwertige Byte"):
       - aushngen (0): Die Routine wird aus der XBRA-Verkettung ausge-
         hngt, falls sie gefunden wird.
       - keine Auswahl, d.h. alle drei Buttons sind disabled (2): Der
         status quo wird nicht verndert.
       - 1. Position (-2): Die Routine wird aus der XBRA-Verkettung ausge-
         hngt, falls sie gefunden wird, und anschliessen neu eingehngt.
       - einhngen (1): Die Routine wird gesucht und falls sie nicht gefun-
         den wird, neu eingehngt. Wird sie gefunden, geschieht nichts.
       - 1. Position+einhngen (-1): Die Routine wird gesucht und falls sie
         nicht gefunden wird, neu eingehngt. Wird sie gefunden, wird sie
         ausgehngt und neu eingehngt, damit sie an erster Stelle hngt.

     ACHTUNG: Wenn Sie den Dialog ber "OK" verlassen wird anschliessend
     die Routine VEKTOR aufgerufen.


     3. Cache
     --------

     Dieser Dialog erlaubt es Ihnen die Cache- und die Historylnge festzu-
     legen.

     - Cache:
        - Lnge pro Eintrag: gibt an, wie lange ein einzelner Cacheeintrag
          in Bytes ist. Dies kann von PEACEBUGversion zu PEACEBUGversion
          variieren.
        - Lnge Cache 1: gibt an, wieviele Eintrge Cache 1 momentan
          umfasst.
        - Lnge Cache 2: gibt an, wieviele Eintrge Cache 2 momentan
          umfasst.
        - Erweitern Cache 1: gibt an, auf wieviele Eintrge Cache 1 erwei-
          tert werden soll.
        - Erweitern Cache 2: gibt an, auf wieviele Eintrge Cache 2 erwei-
          tert werden soll.
     Es knnen auch Werte kleiner als die momentane Anzahl angegeben wer-
     den, dann werden Eintrge gelscht. Da die Caches als Ringe organi-
     siert sind, kann immer soviel Speicher reserviert werden, wie die zu-
     stzlichen Eintrge bentigen.

     - History:
        - Historylnge: gibt an wieviele Bytes der Historypuffer lang ist.
        - Aktuelle Anzahl: gibt an, wieviele Eintrge im Historypuffer
          "Platz" haben (Historylnge/Zeilenlnge).
        - Neue Lnge: Hier whlen Sie die neue Pufferlnge in Bytes.


     4. Keyboard
     -----------

     Hiermit knnen Sie die Tastenkombinationen zum Aufruf des Debuggers
     bestimmen.

     Erlaubt sind eine beliebige Kombination von Shifttasten (Shift links,
     Shift rechts, Control, Alternate, Maustaste links, Maustaste rechts)
     und einer oder keiner der brigen Tasten. CapsLock wird grundstzlich
     immer ignoriert.
     Die beiden mit l und r angeschriebene Tasten unterhalb des Cursor-
     blocks reprsentieren die beiden Maustasten.

     - Einsprung 1: Tastenkombination, die durch flock ($43E) gesperrt wer-
       den kann. Default: Alternate F10.

     - Einsprung 2: Tastenkombination, mit der man flock umgehen kann.
       Default: Alternate+Control F10.


     5. Diverses
     -----------

     - Cursor: Hier whlen Sie zwischen Einfg- oder berschreibmodus.

     - Symbole:
       1. Alle: PEACEBUG benutzt fr Disassemlies alle Symbole, d.h. die
          eigenen und diejenigen, die der Resident Symbol Driver zur Verf-
          gung stellt (---> Liesmich PEACEBUG, Chapter "Symbole, Resident
          Symbol Driver").
       2. Debugger: PEACEBUG benutzt fr Disassemblies nur die eigenen Sym-
          bole.
       3. Keine: PEACEBUG benutzt fr Disassemblies keine Symbole.
          Im Listmodus wird bei installiertem RSD auch der Programmname
          ausgegeben. Nur wenn None eingestellt ist, wird dies unterdrckt.

     - Tastatur+Maus: Hier knnen Sie Keyboardrepeat/-delay und Mausrepeat/
       -delay bestimmen.

     - Timeout: Hier knnen Sie das Timeout fr verschiedene Schnittstellen
       bestimmen, d.h. die Zeit, die der Debugger wartet bis die Schnitt-
       stelle verfgbar ist (oder auch nicht).


     6. Bildschirm
     -------------

     Hiermit knnen Sie die diversen Parameter der Bildschirmschnittstelle
     konfigurieren. Detailierte Erluterungen zu den einzelnen Parametern
     finden Sie im Liesmich PEACEBUG, Kapitel "Schnittstelle, Bildschirm-
     schnittstelle".

     - Einstellungen: Diese Box ist nicht zugnglich, wenn Sie im Patch-
       modus arbeiten, da die darin enthaltenen Parameter nicht den Status
       p haben. Sie enthlt die Parameter der aktuellen Einstellung.

     - Vorgaben: Im Gegensatz zu den Parametern von "Einstellungen", sind
       dies die Parameter, die der Debugger bei Programmstart oder bei
       Aufruf von NEW_FORMAT auswertet.

     - Font aktiv: Whlt den vom Debugger benutzten Font.

     - Font laden: Hier knnen Sie einen neuen, im Tempusformat vorlieg-
       enden, Font whlen (8*16 = 4096 Bytes, 8*8 = 2048 Bytes).
       Einige Beispielfonts befinden sich in \PEACEBUG\PBUGCONF\FONTS.


     7. Prioritten
     --------------

     In diesem Dialog knnen Sie die Prioritten der Arithmetikoperationen
     einstellen. Hhere Werte binden die Operatoren strker als niedrigere,
     z.B. ist a+b*c gleich a+(b*c) und nicht (a+b)*c, weil die Multiplika-
     tion strker bindet. Sinnvoll erscheint mir ein Verndern der
     vorgegebenen Werte allerdings nur fr die Pointeroperation (p).


     8. Userroutinen
     ---------------

     Hier knnen Sie die sechs Routinen USERTRACE, USERENTER, USERQUIT,
     USERSWITCH_ENTER, USERSWITCH_QUIT und USERRESET installieren (--->
     Liesmich PEACEBUG, Kapitel "Schnittstelle, Userroutinen"). Sie spa-
     ren sich so die Arbeit, ein ganzes Programm zu schreiben, das sich
     selber einhngen muss.
     Dazu klicken Sie einfach den entsprechenden Button an und laden das
     einzuhngende Programm.
     Ein solches Programm muss ein bestimmtes Format haben. Zu Beginn muss
     folgende Struktur stehen:

     typedef struct
     {
             int null;           /* Dummywert */
             long *us_message;   /* Zeiger auf Einsprungmessage */
             char xb_magic[4];   /* "XBRA" */
             char xb_id[4];      /* XBRA-ID */
             long *xb_oldvec;    /* Wert des Vektors vor dem einhngen */
     } USER;

     oder in Assembler:

     > dc.w 0
     > dc.l MESSAGE
     > dc.b 'XBRA'
     > dc.b 'PBUG'               ; z.B.
     > dc.l $XXXXXXXX

     Dahinter folgt dann das Programm.
     Beim Laden wird es reloziert, der berflssige Speicher freigegeben,
     obige Struktur initialisiert und last but not least wird es auch noch
     in den Vektor eingehngt.
     Beispiele dazu finden Sie im Ordner PEACEBUG\PBUGCONF\USER. Diese
     sollen nicht irgendeine sinnvolle Aufgabe erfllen, ausser Ihnen als
     Illustration zu dienen.
     Die Null am Anfang muss brigens stehen, weil MESSAGE sonst den Offset
     0 zum TEXT-Anfang htte und nicht reloziert wrde.


     9. Accelerator
     --------------

     Damit knnen Sie den Mausbeschleuniger des Debuggers konfigurieren.
     Einfachklicks auf die Pfeilbuttons inkrementieren bzw. dekrementieren
     den entsprechenden Koeffizienten um 1/128stel, Doppelklicks um
     10/128stel.


     10. Parameter laden
     -------------------

     Diese Funktion erlaubt es Ihnen, aus einer PBUGCONF Datei oder einer
     PEACEBUG Datei die Parameter zu laden. Das Programm erkennt selbstn-
     dig, ob es sich um den Debugger oder das Konfigprogramm handelt.
     Es werden nur die Parameter geladen, die in der entsprechenden Datei
     auch vorhanden sind, denn es gibt welche, die nur in PBUGCONF vorhan-
     den sind.


     11. Parameter speichern
     -----------------------

     Diese Funktion erlaubt es Ihnen die Parameter in einer PBUGCONF Datei
     oder einer PEACEBUG Datei zu speichern. Das Programm erkennt selbstn-
     dig, ob es sich um den Debugger oder das Konfigprogramm handelt.
     Es werden nur die Parameter gespeichert, die in der entsprechenden
     Datei auch vorhanden sind, denn es gibt welche, die nur in PBUGCONF
     vorhanden sind.


     12. Konfigurieren
     -----------------

     Dieser Dialog stellt eine Sammlung aller Utillities im Ordner \PEACE-
     BUG\PEACEBUG\UTILLITY\ dar.
     Die angebotenen Funktionen werden in zwei Fllen aufgerufen:
     1. Beim Anklicken von "OK" bzw. "Setzen".
     2. Wenn das Programm/Accessory gestartet wird und der Debugger zu
        diesem Zeitpunkt installiert ist. Damit dies geschieht, mssen Sie
        die Einstellungen zuvor in PBUGCONF gespeichert haben.
     Die Funktionen, die bestimmte Werte setzen ("Cache" und "History"),
     bernehmen diese aus dem Konfigprogramm, d.h. Cache setzt die Anzahl
     Eintrge auf den Wert, den Sie im Dialog "Cache" eingestellt haben.

     - Cache: erweitert die beiden Caches um eine Anzahl Eintrge.
     - History: erweitert die Anzahl Historyeintrge um eine bestimmte An-
       zahl. Es gilt Bytes=Eintrge*Zeilenlnge.
     - Invert:  invertiert die Farbpalette des Debuggers.
     - Getrez: setzt die Auflsung des Debuggers gemss Getrez (XBIOS 4).
       Dies ist sinnvoll, wenn Sie mit virtuellen Auflsungen arbeiten
       (z.B. Protos, Bigscreen etc.). Da der Debugger einen eigenen Bild-
       schirm installiert, kann die virtuelle Screenverwaltung nicht ein-
       greifen, es kommt zu Bildschirmmll, was mit diesem Programm verhin-
       dert werden kann, da es den Debugger zwingt, die tatschlich vorhan-
       dene (physikalische) Auflsung zu benutzen.
     - NewFont: installiert einen neuen Screenfont.
     - NewFormat: Passt den Debugger an die aktuelle Auflsung an, prak-
       tisch bei Grafikkarten, die nach den Autoordnerprogrammen instal-
       liert werden.
     - NewScreen: Wenn sich Grafikkarten erst nach allen Autoordnerprogram-
       men installieren, erkennt dies der Debugger nicht. Dann kann mit
       dieser Funktion ein neuer Screen installiert werden.


     13. Konfig-/Patchmodus
     ----------------------

     Bis Version 1.15 konnte hier zwischen Konfig- und Patchmodus hin und
     her geschaltet werden. Ab Version 1.16 ist das Programm nun fhig,
     mehrere Debugger zu konfigurieren. Sie schalten jetzt mit diesem Men-
     punkt nicht mehr nur zwischen den beiden Modi hin und her, sondern
     auch sozusagen von Debugger zu Debugger, falls mehrere installiert
     sind.
