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


     0. Introduction
     ---------------

     General:
       With PEACEBUG-Config, you can easily configure PEACEBUG via its cookie
       interface. You can either configure a residently installed debugger or
       PEACEBUG.PRG (on disk).

       For more details on the parameters mentioned in the following chapters,
       consult the PEACEBUG readme, under the chapter "Interface".

       PBUGCONF works as an accessory or program, on all known and unknown
       TOS versions, ST(E)/TT/F030 and all possible and impossible config-
       urations.
       The resource file is included in the program.

     Dialogs:
       All dialogs are in a window and are non modal.
       "Cancel" discards all changes.
       "OK" accepts all changes.
       Some dialogs additionally have a "Set" button, which has the same
       effect as "OK" but does not close the dialog. You cannot undo chan-
       ges with "Cancel" that have been "Set".
       UNDO has the same effect as "Cancel".
       RETURN has the same effect as "OK".
       Control q closes all windows and terminates the program. The changes
       of all opened windows are discarded.
       Control w or the closer of the window closes the top window and
       accept the changes.
       When the program is started or the accessory is called, the main
       menu appears, which allows you to call the other dialogs.

     Modes:
       Basically there are two different working modes, the patch mode and
       the config mode:
       - config mode: every time a dialog is opened, the parameters which
         can be manipulated in this dialog will be copied from the resident
         debugger, and if the dialog is exited by "OK", copied back. The con-
         fig mode is the default mode of operation if a debugger is installed
         when PBUGCONF is started.
         Since PBUGCONF version 1.16 it has been possible to configure
         several resident installed debuggers with the same PBUGCONF.
       - patch mode: the parameters are neither taken from a resident
         debugger nor copied back. This allows you to manipulate and save
         the parameters afterwards in PEACEBUG.PRG or PBUGCONF.PRG/ACC.
       As not all of the parameters have the state p(=patch) (PEACEBUG readme,
       chapter "Interface"), some of them can't be manipulated in
       the patch mode.

     If you are interested in the source code, please send me a formatted
     disk or an e-mail. You will then receive the newest version in the
     same way. Bug reports and suggestions are also welcome.

     The following chapters describe every single dialog which can be
     called from the main menu.


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

     This dialog doesn't need any explanations, does it?


     2. Vectors
     ----------

     This dialog allows you to configure two things:
     1. How PEACEBUG reacts if a certain exception occurs.
     2. How the routine VEKTOR (PEACEBUG readme, chapter "Vectors")
        reacts (VEKTOR is called if PEACEBUG is called and if a F1-F20 or
        RETURN/ENTER is pressed within the debugger).

     Here is the standard way to proceed:
     1. First you choose the vector you want to configure on the left side
        "Exceptions".
     2. Then you choose on the right side ("Action"), how the debugger
        should react if the choosen exception occurs. There are three
        possibilities:
        - Debugger: the debugger is called and the occurance of the
          exception is reported.
        - Original: the debugger ignores the exception and just calls the
          routine following the debugger's one (normally the OS).
        - Ignore: the exception is corrected, that means it jumps to the
          opcode following the one that caused the exception.
        On all MC680x0 with x>0, a privilege violation exception occurs if
        a move sr,<ea> is executed, as this addressing mode is only allowed
        in supervisor mode. For this reason, two additional buttons appear
        if you configure the "Privileg"(=Privilege Violation) exception:
        - SR,<ea>: the command is executed in supervisor mode and the
          program doesn't realize it. In contrast to the TOS routine, the
          debugger's routine works with any opcodes e.g.:
          move sr,([-1,A7,D0.l*8],-1).
        - CCR,<ea>: the SR in the opcode is modified directly to a CCR,
          that means e.g. a move sr,d0 is modified to a move ccr,d0 (in the
          program code).
        If vector "Reset" is selected, two more buttons will appear:
        - Always: means that a reset within the debugger is always caught.
        - Once a Sec: means that a reset within the debugger is caught
          only once a second. This means that if you reset twice within one
          second, the reset is actually executed.
        If both buttons are disabled, a reset within the debugger is never
        caught.
        If the reset occurs outside the debugger:
        - Debugger: The debugger catches the reset, but since the PC gets
          lost, the program can't be continued.
        - Original: Just a normal reset.
        - Ignore: All programs hanging in the reset vector are ignored,
          that means a normal reset is performed without calling any pro-
          grams in the reset vector.
     3. Finally, you set how the routine VEKTOR should work (the values in
        brackets are equal to the ones described in the PEACEBUG readme,
        chapter "The More Significant Byte":
       - Untrap (0): the routine is untrapped if possible (if it can be
         found by the xbra links).
       - none (this means all three buttons are disabled) (2): the
         status quo remains untouched.
       - 1st Position (-2): the routine is untrapped if possible, and install
         the vector again.
       - Setup (1): the routine is searched and if not found, installed in
         the vector. If it's found, nothing happens.
       - 1st Position+Setup (-1): the routine is searched and if not found,
         installed in the vector. If it's found, it will be untrapped
         and installed again (so its position is always the first).

     ATTENTION: if you leave the dialog with "OK", the routine VEKTOR is
     called afterwards.


     3. Cache
     --------

     This dialog allows you to set the length of the cache and the history-
     buffer.

     - Cache:
        - Length each Entry: informs how many bytes one cache entry needs.
          This can vary from PEACEBUG version to PEACEBUG version.
        - Length Cache 1: number of entries of cache 1.
        - Length Cache 2: number of entries of cache 2.
        - Expand Cache 1 to: here you set how many entries cache 1 should
          contain.
        - Expand Cache 2 to: here you set how many entries cache 2 should
          contain.
     You can also choose values smaller than the actual ones. In this case
     entries are deleted, which means untrapped from the chain. If you
     add entries, only the new ones will be allocated, as it is organized
     as a ring.

     - History:
        - Length: this is the amount of bytes the historybuffer contains.
        - Actual Number: informs you how many entries are possible with
          the actual length of the buffer (Length/Length of one line).
        - New Length: here you choose the new length of the history buffer.


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

     Here you set the key combination to call the debugger.

     Any combination of shift keys (shift left/right, control, alternate,
     left/right mousebutton left) and one of the other keys is used. CapsLock
     is always ignored.
     The two mousebuttons are the ones under the cursor block, named with
     "l" and "r".

     - Call 1: key combination, which does not work if flock ($43E) is set.
       Default: alternate F10.

     - Call 2: key combination, which always works (hopefully).
       Default: alternate+control F10.


     5. Miscellanous
     ---------------

     - Cursor: insert- or overwrite mode, that's the question.

     - Symbols:
       1. All: PEACEBUG uses all symbols for disassembly, this means
          PEACEBUG's own ones and the ones the Resident Symbol Driver
          offers (PEACEBUG readme, Chapter "Symbols, "Resident Symbol
          Driver").
       2. Debugger: PEACEBUG only uses its own symbols for disassembly.
       3. None: PEACEBUG uses no symbols for disassembly.
       If RSD is installed, the program name is also printed. If you choose
       "None", this will be supressed.

     - Keyboard+Mouse: here you set the keyrepeat/delay and the same for
       the mouse.

     - Timeout: gives you the ability to set the timeouts for the different
       ports, that means the time the debugger waits until it can send data
       to a port (or cannot send).


     6. Screen
     ---------

     The many parameters of the screen interface can be configured in this
     dialog. Detailed explanations to each parameter are to be found in the
     PEACEBUG readme, chapter "Interface, Screen Interface".

     - Configure: this box will not appear in the patch mode, as the para-
       meters in it don't have the "p" state. It contains the current
       PEACEBUG screen parameters .

     - Prefer: in contrary to the parameters of "Configure", these are the
       parameters the debugger evaluates when it's loaded or if NEW_FORMAT
       is called.

     - Active Font: tells the debugger which font to use.

     - Load Font: you can load another font in tempus format (8*16 = 4096
       Bytes, 8*8 = 2048 Bytes).
       Sample fonts are in \PEACEBUG\PBUGCONF\FONTS.


     7. Precedence
     -------------

     In this dialog you can set the precedences of arithmetic operations.
     Higher values have greater priority than lower ones, e.g. a+b*c is equal
     to a+(b*c) but unequal to (a+b)*c, as the multiplication has higher priority.
     This function does not seem very useful to me, except to change the precedence
     of the pointer operation (p).


     8. User Routines
     ----------------

     This dialog gives you the ability to install the six routines
     USERTRACE, USERENTER, USERQUIT, USERSWITCH_ENTER, USERSWITCH_QUIT and 
     USERRESET (PEACEBUG readme, chapter "Interface, User Routines").
     Instead of writting a whole program which has to search PEACEBUG and
     has to install itself, you can use this function. The program must
     have a special format, with the following structure at the beginning:

     typedef struct {
             int null;           /* Dummy */
             long *us_message;   /* Pointer to the message */
             char xb_magic[4];   /* "XBRA" */
             char xb_id[4];      /* XBRA-ID */
             long *xb_oldvec;    /* old value of the vector */
     } USER;

     or in assembler:

     > dc.w 0
     > dc.l MESSAGE
     > dc.b 'XBRA'
     > dc.b 'PBUG'               ; e.g.
     > dc.l $XXXXXXXX

     After this structure the program follows.
     When loaded it will be relocated, memory will be released, the structure
     above will be initialized and last but not least it will be installed
     into the vector.
     Examples are in the folder PEACEBUG\PBUGCONF\USER. These are not really
     useful, but are mainly to illustrate the use of user routines.
     By the way, the dummy word at the beginning is necessary because
     otherwise *us_message would not be relocated as it would have the
     offset 0 to the text segment.


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

     This dialog allows you to configure the debugger's mouse accelerator.
     Single click on the arrow buttons to increment or decrement the coeffi-
     cients of the polynomial by 1/128, double click to increase by 10/128.


     10. Load Parameters
     -------------------

     This function loads parameters from the files PBUGCONF.ACC/PRG or
     PEACEBUG.PRG. The program recognizes if it's the debugger or the
     config program. If it loads from the config program then there are
     some additional parameters which are not part of the debugger.


     11. Save Parameters
     -------------------

     This function saves parameters into the files PBUGCONF.ACC/PRG or
     PEACEBUG.PRG. The program recognizes if it's the debugger or the
     config program. If it saves into the config program then there are
     some additional parameters which are not part of the debugger.


     12. Configure
     -------------

     This dialog offers you the utilities of \PEACEBUG\PEACEBUG\UTILLITY\.
     The functions are executed in two cases:
     1. If you select "OK" or "Set".
     2. If the program/accessory is loaded and the debugger is installed
        at that moment. Before you have to save the configuration in PBUG-
        CONF naturally.
     The functions which set certain values ("Cache" and "History") take
     these from the config program itself, this means Cache sets the number
     of entries to the value that you set in the dialog "Cache".

     - Cache: adds a certain number of entries to the two caches.
     - History: adds certain number of entries to the history buffer. It is
       bytes=entries*length of one line.
     - Invert: inverts the color palette of the debugger
     - Getrez: sets the resolution of the debugger according to Getrez
       (XBIOS 4). This is useful if you are working with virtual
       resolutions (e.g. with protos or bigscreen). As the debugger has its
       own screen, the screenexpander cannot come into action and the
       screen will be messed up. This can be fixed with this function, as
       it urges the debugger to use the real (physical) resolution.
     - Newfont: installs a new screen font.
     - NewFormat: adapts the debugger to the actual resolution, a practical
       function with gfx board driver, which are installed after the auto
       folder programs.
     - NewScreen: if a gfx board driver installs after the debugger, the
       debugger won't recognize it. With this function, PEACEBUG allocates
       a new screen.



     13. Config-/Patchmode
     ---------------------

     Until version 1.15 you could only switch between config- and patchmode.
     Now it's possible to configure several debuggers with only one
     config program. This function now switches from patchmode to PEACEBUG
     0 through 9 and back to patchmode.