[Indigo]<Mesa>Doc>Debugger60.bravo!1

This memo outlines changes made in the Mesa Debugger since the last release (Mesa 5.0, April 9, 1979); it is intended as a concise guide to conversion, not a detailed specification of the changes. Complete documentation on the Mesa 6.0 Debugger can be found in the Mesa Debugger Documentation.

The Debugger’s user interface incorporates changes made in Tajo (the Tools Environment); the window package Wisk has been converted to use Vista, the new window package. For more complete documentation on the Tajo design, see the Tajo User’s Guide and the Tajo Functional Specification.

The assignment of some function keys and mouse buttons has changed. The menu button is now YELLOW (formerly BLUE). FL4 is no longer the stuff key; use FR4 (Spare2), Keyset2, or ↑S. The following function keys are implemented (see the section on editing for an explanation of the functions):

CutDELDELKeyset5↑C
PasteLFLFKeyset1↑F
NextFL3(none)Keyset3↑N
ReplaceFL4(none)Keyset4↑R
SwatFR1Spare3(none)(none)
StuffFR4Spare2Keyset2↑S
Back WordBWSpare1(none)↑W
Replace/NextFR5(none)(none)↑K

Typein is directed to the Debugger if the cursor is not in any window. Source windows will accept input until a file is loaded; they then direct typein to the Debugger (unless they are editable; see below).

The selection scheme has changed. Clicking RED once selects a character, clicking twice selects a word, three times a line, etc. The selection can be extended to the left or right with BLUE; a character selection is extended by characters, a word selection by words, and so on. The current selection is now video reversed.

Scrollbars no longer occupy a dedicated part of the window, but instead come up on top of the left edge. They are twice as wide as before, and you can "see through" them. To obtain a scroll bar, move left just past the edge of the window, then move right slightly, back into the window.

The name stripe and tiny windows now video reverse when the cursor is in the sections that function as accelerators for the window manager menu commands (Move, Grow, Size, Top, Bottom, and Zoom).

This command deactivates the selected window; it will no longer appear on the screen and the resources used by it will be freed. The window’s name is added to a menu of deactivated windows, which is available outside all windows. The window may be made active again by selecting its menu item.

A new Text Ops menu is now supplied with the Debug.log and source windows in addition to the Window Manager menu. It contains Find, Position, Split, Normalize Insertion, Normalize Selection, and Wrap; the following commands are new:

The Debugger’s wisk window has been replaced by the more general Split window command. Feedback is similar to that in Laurel: the split line can be picked up using RED and moved vertically. The subwindow is destroyed by moving the split line off the top or bottom of the (sub)window.

For windows containing an insert point (Debug.log and editable source windows), this command will position the text in the (sub)window so that the line containing the insert point is at the top.

A separate Debugger menu no longer exists; the Alter Bitmap function has been deleted, Move Boundary has been superseded by Split (see above), and Stuff It is now available only on the keyboard.

In addition to the standard menus, the source window has two additional menus, Source Ops and File Ops. The Source Ops menu contains the following commands, which are unchanged: Create, Destroy, SetBreak, SetTrace, and ClearBreak; the last three commands are available only if a file has been loaded into the window. The Source Ops menu contains the following new command:

Causes the Debugger to ignore the creation date of the current source file when setting breakpoints or positioning to a source line. This command is essentially a LOOPHOLE; because the source-object correspondence may not be correct, it should be used with caution. If, after using Attach, the Debugger sets breakpoints in strange places, chances are that the source file does not match the version of the object in the system you are debugging.

Enables editing of the currently loaded read only file (see below). Empty windows are always editable, but because they have no backing store (until they are Saved or Stored on a file), the amount of information in the window should be kept small.

Outputs the contents of the window to its current file; overwriting the file requires confirmation. A backup "$" file is created that is a copy of the unedited version. After the Save command completes, access reverts to read only.

Outputs the contents of the window to the file named by the current selection; if the file already exists, overwriting it requires confirmation. After the Store command completes, access reverts to read only.

Discards all edits that have been made to the window (during this session) and resets access to read only. If the file is not editable, the window is made empty.

The Edit command is available only if a file has been associated with the window (by a previous Load, Store, or Save); Store and Save apply only if the window has been edited.

The standard source window facilities now provide a simple cut and paste editor. Editing is modeless and is accomplished by moving the insert point and typing the desired text. (Note that unlike Bravo, the insert point is independent of the location of the current selection.) Backspace and backword functions (BS and BW) are always available. The following functions are provided:

Caution: The editing facilities are designed not to alter the original file until it is Saved or Stored, much like Bravo; the original contents are copied to a file with "$" appended to its name. This is however, a new facility and should be used with caution. It is designed to support a moderate number of localized changes to programs, not to replace your favorite document creation system.

Changes in Debugger commands are relatively minor. The Debugger’s interpreter is more generally available and more consistent with the language. Tracepoints have been re-implemented as a minor extension of the standard breakpoint facilities.

Break and trace points can no longer be set by typing a source line, and the Break Module and Break Procedure commands and corresponding Trace and Clear commands have been deleted; the menu commands must be used.

The distinction between trace and breakpoints has been removed. An optional command string can now be attached to each breakpoint which will be executed when the breakpoint is taken. A tracepoint then becomes a breakpoint with a standard default command string. LIst Breaks lists both break and tracepoints (List Traces has been deleted). Clear All Entries/Xits clears both break and tracepoints.

Tracepoints automatically invoke the normal Display Stack command processor (with subcommand p(arameters), v(ariables), or r(esults) as appropriate). The q(uit) subcommand (not b(reak)) exits to the Debugger’s command level, where the normal Proceed command continues execution of the client.

When an exit break is set, the Debugger breaks on any return of the procedure by setting the actual breakpoint on a common return instruction. The Debugger has no way of telling which return was taken if there is more than one. When asked to display the source line when at an exit break, the Debugger now shows the declaration line of the procedure instead of the last return statement.

Typing ↑DEL will now abort the display of long arrays and strings, as well as most searches. This key combination no longer has to be held down to be recognized.

This command now prints more information about some data segments; the (system-assigned) types currently recognized are heap, system, frame, table, bitmap, stream buffer, and Pup buffer. Unrecognized types (assigned by the user) are displayed as data(t); an unknown type is displayed as data(?).

The new subcommand "g" displays the global variables of the module containing the current procedure. A space (SP) invokes the interpreter. If the source window is loaded with the s(ource) subcommand, the window will remember the appropriate context for setting breakpoints.

The Interpret Call command has been deleted; the Debugger’s interpreter should be used. There are no longer any restrictions on when the interpreter may be called.

This command replaces old style conditional breaks; it changes a normal breakpoint into a conditional one. Arguments are a breakpoint number and a condition, which is evaluated in the context of the breakpoint. The breakpoint number is displayed when the break/tracepoint is set, and may also be obtained using the LIst Breaks command.

Arbitrary command strings can now be attached to break and tracepoints; they are executed by the Debugger when the breakpoint is taken. Arguments are a breakpoint number and a command string terminated with a CR. A CR can be embedded in the command string by quoting it with ↑V.

This command clears breakpoints by number. Typing CR in place of a number will clear the current breakpoint, i.e., the one that transferred control into the Debugger.

This command sets the default user name and password for the debugging session. The new user name and password are not written into the client’s core image or onto the disk.

This command is used when the Debugger breaks and enters the debugger nub ("//" mode); it dumps the Debugger’s call stack in octal to the log. Change requests reporting Debugger problems that result in an uncaught signal or other problem should be accompanied by a Debug.log which includes the output of this command.

The interpreter provides support for all of the new language features introduced in Mesa 6. All commands requiring numeric input now invoke the interpreter automatically (e.g., Octal Read: @p, n: SIZE[r]).

A summary of the revised grammar is attached. The constructs ABS, ERROR, LONG, LOOPHOLE, MAX, MIN, NIL, POINTER TO, PROC, PROCEDURE, SIGNAL, WORD, and open and half open intervals have been added to the interpreter’s grammar; type REAL has been added for output only. Type expressions following % must be enclosed in parentheses. The interpreter syntax Expression? has replaced the Interpret Expression command; it prints the value of the expression in several formats including octal and decimal.

The interpreter now does a much better job of target typing. As a result, arguments to procedure calls and right hand sides of assignments are type checked. In addition, assignments to enumerated types now work correctly.

Even if a module has compressed symbols, the debugger will first look for the file modulename.bcd to see if it is the original compiler output for that module (by checking the version stamp). If so, it will use those symbols. Thus, there is no need to Attach Symbols if the proper file is on the disk. It makes sense to use compressed symbols for large systems and to also have present the complete symbol files for the specific modules undergoing detailed debugging.

A "?" in a variable display now uniformly means that the value is out of range; ". . ." indicates that there are additional fields present which cannot be displayed due to lack of symbol table information.

When the debugger refers to a program module, it usually gives the address of its global frame, e.g., "G: nnnnnB". If the module has not been started, the debugger now prints a "~" after the B. If a module has not been started, the user should not modify the global variables of that module, nor should they be displayed, as they are uninitialized.

The warning Eval stack not empty! will be printed if the debugger is entered via either an interrupt or a breakpoint with variables still on the evaluation stack; this indicates that the current value of some variables may not be in main memory, where the interpreter normally looks. Exceptions to this are at entry and exit breaks; the debugger has enough information to decode the argument records that are on the stack in this case (if the appropriate symbol tables are available).

Before the debugger permits any breakpoints to be set using the source window, the creation date in the source file is checked against the corresponding date recorded by the compiler in the BCD. The message Can’t use <module> of <time> instead of version created <time> will result if the versions do not match (but see the Attach source menu command above).

The message Resetting symbol table! is displayed when the interpreter’s scratch symbol table overflows; the command is retried automatically. The Debugger’s performance decreases somewhat until the symbol table is reinitialized.

The Debugger now requires a strike font named MesaFont.strike or SysFont.strike; a version of Gacha10 is available on <Mesa>MesaFont.strike. Additional strike fonts are stored on [Maxc]<AltoFonts>. (Strike fonts which include kerning are not supported.)

When running on machines with more than 64K of memory, the client system supplies space to the Debugger for its bitmap (unless all but one bank has been disabled; see below); the client can disable this option by using the /k switch or by calling a system procedure before the Debugger is first invoked (see the Mesa 6.0 System Update).

It is also possible for the Debugger to be installed with more than one bank of memory available for code swapping; this is done by reducing the amount of memory available to the client using the RunMesa bank switches or the Alto Executive MesaBanks.~ command (in Executive version 11 or later).

This command establishes the default memory allocation available to client programs. Arguments can be in two forms: a sixteen bit octal mask (followed by an optional /b switch) indicating the available banks; a one in bit position n of the mask (counting from the left) indicates that bank n is available. Form two is a series of decimal bank numbers each followed by the /x switch; each bank mentioned is excluded from use by the client. Note that a request to exclude bank zero will be ignored. If no argument is present, the command will display the current value of the bank mask.

The MesaBanks.~ command establishes the available memory for each .image or .bcd program invoked directly by the Alto Executive. The default may be overridden by explicitly using RunMesa to invoke the program and optionally specifying bank switches on its command line, before the .image file name. The bank switches have the same format as the arguments to MesaBanks.~ (except that the /b switch is required in the case of a bitmask). In the absense of any bank switches, RunMesa always assumes that all banks are available to the client.

Using these facilities, it is possible to set up the defaults so that the Debugger has extra banks of memory at the expense of the client program. For example, on a three bank Alto, the following commands might be used to set the default and then install the Debugger:

Under this arrangement, the client would use banks zero and one, and the Debugger would use banks zero and two (because bank zero is swapped onto Swatee, it can be used by both). Actually, because the client (by default) is also allocating space for the Debugger’s display bitmap, the client actually has only one-and-one-half banks, and the Debugger has two-and-one-half; this can be changed by running the client with the /k switch, resulting in two banks available to each.

Note that the MesaBanks.~ command affects all Mesa programs invoked by the Alto Executive, including the Compiler and Binder. So the above example would run the Compiler in only two banks, not three; this can be changed by saying RunMesa Compiler on the command line, which, because there are no bank switches specified, defaults to all banks available (not really necessary in this case, since the Compiler runs almost as well in two banks as in three). On the next new session, the Debugger is smart enough to notice that the Compiler (or whoever) has smashed what it thought was in bank two. (It is also smart enough not to use any memory that the client owns, so that the 1/x switch on the command line above is actually unnecessary.)

Two Banks: Normally, do nothing; client and Debugger will each have one-and-one-half banks. For small clients and better Debugger performance, use RunMesa 1/x Mesa.image Client.bcd, which will give the client one bank and the Debugger two. (If you were to use MesaBanks.~ 1/x in this case, the Compiler would also be restricted to one bank).

Four Banks: Use MesaBanks.~ 3/x to give the client and the Debugger two-and-one-half banks each and the Compiler three; use MesaBanks.~ 2/x 3/x and Client/k to increase the Debugger’s allocation to three banks and restrict the client to two. Obviously, this can be adjusted based on the size of the client and the desired performance of the Debugger.

Nearly all of Alto/Tajo is now included in the Debugger (Librarian support and communications are not). Accordingly, there is little (if any) distinction between UserProcs and Tools, and Fetch (the FileTool plus communications) which runs in the Debugger is the same as the FileTool provided by Alto/Tajo. A copy of section 10 of the Tajo User’s Guide describing the FileTool is attached to this memo.