@width 80
@author "Emanuel Mcklin"
@database "PBUGCONF Documentation English"
@subject Debugger
@$ver: 1.42 (13.03.94)
@default "Menu"
@help %PBUGCONF
@toc Menu

@node Menu
@symbol ar menu

@box 5 23 16 0
      Information       ^I
    @{G}-----------------------@{g}
      Vectors           ^V
      Cache             ^C
      Keyboard          ^K
      Miscellanous      ^D
      Screen            ^B
      Precedence        ^P
      User Routines     ^R
      Accelerator       ^A
    @{G}-----------------------@{g}
      Load Parameters   ^O
      Save Parameters   ^S
    @{G}-----------------------@{g}
      Configurate       ^E
      Peacebug 0        ^T
@endnode

@node Information
     @{U}1  Information@{u}


     @{U}General@{u}

     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 this hyptertext,
     consult the PEACEBUG hypertext, 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 configu-
     rations. The resource file is included in the program.


     @{U}Dialogs@{u}

     - 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.


     @{U}Modes@{u}

     Basically there are two different working modes, the patch mode and
     the config mode:
     1. 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
        config 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.
     2. 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
        hypertext, chapter "Interface"), some of them can't be mani-
        pulated in the patch mode.


@symbol ari Shareware
     @{U}Shareware@{u}

     PEACEBUG is shareware and can be copied as many times you want. If you
     regulary use it you have to pay me the fee of 30 SFr.
     IMPORTANT: Don't send me any checks in a foreign currency, but only in
     Swiss Francs (SFr.), because otherwise I have to pay a fee of 10 SFr.,
     which is a third of the shareware fee.
     Registered users can send me a disc and a stamped envelope and they
     will get back the newest release of PEACEBUG.

@symbol ari "Author"
     Shareware fee to:
         Emanuel Mcklin
         Rainfussweg 7
         CH-8038 Zrich

@symbol ari "E-Mail"
     Critics and suggestions to:
         Internet: peace@@soziologie.unizh.ch
         Decnet: ezinfo::peace
@endnode

@node Vectors
     @{U}2  Vectors@{u}


     @{U}Purpose of this dialog@{u}

     1. How does PEACEBUG react if a certain exception occurs?

     2. How does the routine VEKTOR (PEACEBUG hypertext, chapter "Vectors")
        react (VEKTOR is called if PEACEBUG is called and if a F1-F20 or
        RETURN or ENTER is pressed within the debugger).


     @{U}Procedure@{u}

     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:
        1. Debugger: the debugger is called and the occurance of the
           exception is reported.
        2. Original: the debugger ignores the exception and just calls the
           routine following the debugger's one (normally the OS).
        3. 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:
        1. 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).
        2. 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:
        1. Always: means that a reset within the debugger is always caught.
        2. 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:
        1. Debugger: The debugger catches the reset, but since the PC gets
           lost, the program can't be continued.
        2. Original: Just a normal reset.
        3. 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 hypertext,
        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 in-
         stall 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.
@endnode

@node Cache
@symbol ari History
     @{U}3  Cache@{u}


     @{U}Cache@{u}

     - 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.


     @{U}History@{u}

     - 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.
@endnode

@node Keyboard
     @{U}4  Keyboard@{u}


     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. Caps-
     Lock 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.
@endnode

@node Miscellanous
     @{U}5  Miscellanous@{u}


     @{U}Cheat@{u}

     With this button you can switch the debugger to the so-called cheat-
     mode. It's called like this because in earlier versions it could only
     be switched on by a secret key combination (shift left + shift right +
     alternate + control + escape).
     In this mode the debugger runs with interrupt level 7, so it can't be
     interrupted except by an NMI. Also any routine is installed at the
     first position if the more significant configuration byte is not set
     to zero (untrap routine). Last but not least any reset is catched.


     @{U}Cursor@{u}

     Insert- or overwrite mode, that's the question.


     @{U}Symbols@{u}

     - All: PEACEBUG uses all symbols for disassembly, this means
       PEACEBUG's own ones and the ones the Resident Symbol Driver offers
       (PEACEBUG hypertext, Chapter "Symbols, "Resident Symbol Driver").
     - Debugger: PEACEBUG only uses its own symbols for disassembly.
     - 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.


     @{U}@{Keyboard+Mouse ignore}@{u}

     Here you set the keyrepeat/delay and the same for the mouse.


     @{U}Timeout@{u}

     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).
@endnode

@node Screen
     @{U}6  Screen@{u}


     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 hypertext, chapter "Interface, Screen Interface".


     @{U}Configuration@{u}

     This box will not appear in the patch mode, as the parameters in it
     don't have the "p" state. It contains the current PEACEBUG screen
     parameters .


     @{U}Preferences@{u}

     In contrary to the parameters of "Configuration", these are the para-
     meters the debugger evaluates when it's loaded or if NEW_FORMAT is
     called.

     @{U}Buffer-Preferences@{u}

     These three values accord to _BILDSCHIRM_LENGTH, _ZEICHEN_LENGTH
     and _MAUS_LENGTH. The three buttons "ST", "F030" and "TT" set them to
     values according to the ST, Falcon or TT resolutions. That means you
     can then switch between any of the ST, Falcon or TT resolutions with-
     out installing a new screen (F030 resolutions without true color, even
     if this mode is supported by the debugger).


     @{U}Active Font@{u}

     Tells the debugger which font to use.


     @{U}Load Font@{u}

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


     @{U}Switch@{u}

     Tells the debugger whether to switch to color registers and the video
     registers or not. The debugger does always switch the videobase regi-
     sters (video registers are e.g. the shiftmode registers).
@endnode

@node Precedence
     @{U}7  Precedence@{u}


     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).
@endnode

@node "User Routines"
     @{U}8  User Routines@{u}


     This dialog gives you the ability to install the six routines
     USERTRACE, USERENTER, USERQUIT, USERSWITCH_ENTER, USERSWITCH_QUIT and
     USERRESET (PEACEBUG hypertext, 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:

     in C:

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

     in Assembly:

                  dc.l MESSAGE
                  dc.l 'XBRA'
                  dc.l 'PBUG'
     OLD_ROUTINE: dc.l $xxxxxxxx
     ROUTINE: ...

     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.
@endnode

@node Accelerator
     @{U}9  Accelerator@{u}


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

@node "Load Parameters"
     @{U}10  Load Parameters@{u}


     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.
@endnode

@node "Save Parameters"
     @{U}11  Save Parameters@{u}


     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.
@endnode

@node Configurate
     @{U}12  Configurate@{u}


     @{U}Purpose@{u}

     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".


     @{U}Functions@{u}

     - 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.
@endnode

@node "Peacebug 0"
@next "Peacebug 0"
@symbol ari "config mode" "patch mode"
     @{U}13  Config-/Patchmode@{u}


     Until version 1.15 you could only switch between config- and patch-
     mode. 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.
@endnode

@node %PBUGCONF
@prev Menu
@next Menu
     This hypertext describes the functions and the handling of PBUGCONF, a
     program to configure PEACEBUG.

     This documentation is written in a kind which allows you to read it in
     two different manners:
     1. As hypertext, that means you can go to the page you are interessted
     in by using the links.
     2. As normal manual, that means you read page by page.

     More information are to be found in the menu.
@endnode

@pnode RSD "Resident Symbol Driver"
The Resident Symbol Driver (RSD) is a
program written by Robert Federle, which
creates symbol tables of executed programs.
These symbol tables can be accesed by other
programs by the RSD's cookie interface.
Moreover programs can also get informations
about the executed programs like the length
of the text segment and some more stuff.
@endnode
