Page Numbers: Yes First Page: 10 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading:

Debugger commands

Even Heading: Not-on-first-page

Debugger commands

Section 4: Debugger commands

The debugger provides facilities for managing breakpoints, examining user data symbolically, setting the context in which the user symbols are looked up, and directing program control. It also contains low-level utilities and a debugger nub used for debugging the debugger itself. The semantics of the commands are summarized below. (Section 3 contains further details regarding input conventions and Section 6 contains details of output conventions.)

Breakpoints

The break and trace commands apply to modules and procedures that are known within the current context. All breakpoints and tracepoints may be conditional; an optional command string can also be attached to each breakpoint/tracepoint which will be executed when the breakpoint/tracepoint is taken. A tracepoint is a breakpoint with a standard default command string. Tracepoints automatically invoke the normal Display Stack command processor (with subcommand p(arameters), v(ariables), or r(esults) as appropriate).

The three valid formats of a condition are: variable relation variable, variable relation number, and number. Conditions include relations in the set {<, >, =, #, <=, >=}. A number (multiple proceeds) means execute the break number times before invoking the debugger. The variables are interpreted expressions that are looked up in the context of the breakpoint. A variable may not be an expression that is more than one word long, dereferences a pointer (beware of the implicit derefence in record qualification), or indexes an array. See Attach Condition, below, for more information.

You may set breakpoints at the following locations in your program: entry (to a procedure), exit (from a procedure), and at the closest statement boundary preceding a specific text location within a procedure or module body. The debugger can set entry breakpoints on any procedure called from within a module. However, the fact that extra symbols are required to display the parameters or the breakpoint will not be discovered until they are needed. Breakpoints cannot be set on nested procedures (except with Wisk) unless the current context is the enclosing procedure. Note that breakpoints are set in all instances of a module. Breaks on a specific text location can be set only with the breakpoint commands of the Source Ops menu. When the source line of the breakpoint is displayed, the indicator <> appears to the left of the source where the breakpoint has actually been set (e.g., IF foo THEN <> some statement;). 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. An incorrect version is reported with the message Can’t use <module> of <time> instead of version created <time>. Since there is only one exit from a procedure, the debugger shows the beginning of the procedure for exit breaks instead of indicating a potentially incorrect RETURN statement. Local variables may be invisible if this RETURN has a PC that is not in the block with their declarations; use source breaks on the RETURN statements instead of an exit break.

When a break or trace is encountered during execution, a (possibly nested) instance of the debugger is created and control transfers to the command processor, from which you may access any of the facilities described in this document. The debugger types the name of the procedure containing the breakpoint, and the address and PC of the currently active frame. If the breakpoint has a condition associated with it, the break is taken only if the condition is satisfied. Note that the multiple proceed counter is reset after being satisfied; e.g. a condition of 5, will actually break on the fifth, tenth, fifteenth, ... times the breakpoint is reached. To continue execution of your Mesa program, execute the Proceed command; to stop execution of your program, execute the Quit command.

If you compile a module with the cross jumping switch turned on, be warned that when setting source breakpoints, the actual breakpoint may not end up where you expect (e.g., you may break in the code of an ELSE clause when you really want the THEN clause if they share some common code). The message Cross jumped! will appear before the source of a cross jumped module is displayed. Entry and exit breakpoints are not affected by cross jumping.

The warning Eval stack not empty! will be printed if the debugger is entered via either an interrupt or 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 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).

ATtach Condition [number, condition]

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.

ATtach Keystrokes [number, command]

adds an arbitrary command string to breakpoints/tracepoints; the characters from this string are executed by the Debugger when the breakpoint/tracepoint 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.

Break All Entries [module/frame]

sets a break on the entry point to each procedure in module or frame (cf. Break Entry).

Break All Xits [module/frame]

sets a break on the exit point of each procedure in module or frame (cf. Break Xit).

Break Entry [proc]

inserts a breakpoint at the first instruction in the procedure proc.

Break Xit [proc]

inserts a breakpoint at the last instruction of the procedure body for proc. This catches all RETURN statements in the procedure.

CLear All Breaks [confirm]

removes all breakpoints/tracepoints.

CLear All Entries [module/frame]

removes all entry breakpoints/tracepoints in module or frame.

CLear All Xits [module/frame]

removes all exit breakpoints/tracepoints in module or frame.

CLear All Traces [confirm]

removes all breakpoints/tracepoints; it is equivalent to CLear All Breaks.

CLear Break [number]

removes a breakpoint by number. Typing CR in place of a number will clear the current breakpoint, i.e., the one that got you into the Debugger.

CLear Condition [number]

changes a conditional breakpoint into a normal one. Typing CR in place of a number behaves as in CLear Break.

CLear Keystrokes [number]

clears any command string associated with the breakpoint. Typing CR in place of a number behaves as in CLear Break.

CLear Entry Break [proc]

converse of Break Entry.

CLear Entry Trace [proc]

converse of Trace Entry; it is equivalent to CLear Entry Break.

CLear Xit Break [proc]

converse of Break Xit.

CLear Xit Trace [proc]

converse of Trace Xit; it is equivalent to CLear Xit Break.

Display Break [number]

displays a breakpoint by number. Its type (entry, exit, source), the procedure and/or module name in which it is found are displayed; for source breakpoints, the source text is also displayed; any attached conditions or keystrokes is also shown. Typing CR in place of a number behaves as in CLear Break.

List Breaks [confirm]

lists all breakpoints, displaying the same information as Display Break.

Trace All Entries [module/frame]

sets a trace on the entry point to each procedure in module or frame (cf. Trace Entry).

Trace All Xits [module/frame]

sets a trace on the exit point of each procedure in module or frame (cf. Trace Xit).

Trace Entry [proc]

sets a trace on the entry of the procedure proc. When an entry tracepoint is encountered, display stack mode is entered and the parameters are displayed. (cf. Break Entry)

Trace Xit [proc]

sets a trace on the exit of the procedure proc. When an exit tracepoint is encountered, display stack mode is entered and the return values are displayed. (cf. Break Xit)

Display runtime state

The scope of variable lookup is limited to the current context (unless otherwise specified below to be the current configuration). What this means is the following: if the current context is a local frame, the debugger examines the local frame of each procedure in the call stack (and its associated global frame) following return links until the root of the process is encountered; if the current context is a module (global) context, just the global frame is searched. Global frames are searched in the order: declarations, imports, directory. If the variable you wish to examine is not within the current context, use the commands that change contexts.

AScii Read [address, n]

displays n (decimal) characters as a string starting at address (octal).

AScii Display [address, count]

interprets address as POINTER TO PACKED ARRAY OF CHARACTER and displays count characters.

Display Configuration

displays the name of the current configuration followed by the module name, corresponding global frame address, and instance name (if one exists) of each module in the current configuration.

Display Frame [address]

displays the contents of a frame, where address is its octal address (useful if you have several instances of the same module); display stack subcommand mode is entered.

Display GlobalFrameTable

displays the module name and corresponding global frame address, pc, codebase, and gfi of all entries in the global frame table.

Display Module [module]

displays the contents of a global frame, where module is the name of a program in the current configuration.

Display Process [process]

displays interesting things about a process. This command shows you the ProcessHandle and the frame associated with process, and whether the process is waiting on a monitor or condition variable (waiting ML or waiting CV). A * marks the current process. A process can be on one and only one queue (associated with a condition, monitor, ReadyList, etc.). Then you are prompted with a ">" and you enter process subcommand mode. A response of N displays the next process; S displays the source text and loads and positions the sourcefile in the source window; L just displays the source text; R displays the root frame of the process; P displays the priority of the process; space enters the interpreter; -- delimits a comment; and Q or DEL terminates the display and returns you to the command processor. Note that either a variable of type PROCESS (returned as the result of a FORK) or an octal ProcessHandle is acceptable as input to this command (process is an interpreted expression).

Display Queue [id]

displays all the processes waiting on the queue associated with id. If id is simply an octal number, you are asked whether it is a condition variable (i.e., Condition? [Y or N]). For each process, you enter process subcommand mode. The semantics of the subcommands remain the same as in Display Process, with the exception of N, which in this case follows the link in the process. This command accepts either a condition variable, a monitor lock, a monitored record, a monitored program, or an octal pointer.

Display ReadyList

displays all the processes waiting on the queue associated with the ReadyList, i.e., the list of processes ready to run. For each process, you enter process subcommand mode; the semantics of the subcommands are the same as in Display Queue.

Display Stack

displays the procedure call stack. At each frame, the corresponding procedure name and frame address are displayed. You are prompted with a ">". A response of V displays all the frame’s variables; G displays the global variables of the module containing the current frame; P displays the input parameters; R displays the return values ((anon) appears before those which are not named in the parameter lists); N moves to the next frame; J, n(10) jumps down the stack n (decimal) levels (if n is greater than the number of levels it can advance, the debugger tells you how far it was able to go); S displays the source text and loads and positions the sourcefile in a source window (It also sets the context for setting breakpoints in that window.); L just displays the source text; space enters the interpreter; -- delimits a comment; and Q or DEL terminates the display and returns you to the command processor. When the current context is a global frame, the Display Stack subcommands G, J, and, N are disabled. When the debugger cannot find the symbol table for a frame on the call stack, only the J, N, and Q subcommands are allowed. For a complete description of the output format, see Section 6.

Find variable [id]

displays the contents and module location of the variable named id, searching through only the GlobalFrames of all the modules in the current configuration.

Current context

The current context is used to determine the domain for symbol lookup. There are commands provided which make it simple to display the current context, to display all the configurations and processes, to restore the starting context, and to change contexts.

CUrrent context

displays the name and corresponding global frame address (and instance name if one exists) of the current module, the name of the current configuration, and the ProcessHandle for the current process.

LIst Configurations [confirm]

lists the name and instance name (if one exists) of each configuration that is loaded, beginning with the last configuration loaded. If you wish to see more information about a particular configuration, use the Display Configuration command.

LIst Processes [confirm]

lists all processes by ProcessHandle and frame. If you wish to see more information about a particular process, use the Display Process command.

ReSet context [confirm]

restores the context which this instance of the debugger had upon entering the session.

SEt Configuration [config]

sets the current configuration to be config, where config is nested within the root configuration that is current. This command is useful for "jumping" further into the nested block structure of a configuration.

SEt Module context [module/frame]

changes the context to the program module whose name is module (within the current configuration). If there is more than one instance of module, the debugger lists the frame address of each instance and does not change the context. Using a frame address has the same effect as SEt Octal context..

SEt Octal context [address]

changes the current context to the frame whose address is address. This is useful when there are several instances of the same module or in setting the current context to a specific local frame.

SEt Process context [process]

sets the current process context to be process and sets the corresponding frame context to be the frame associated with process. Upon entering the debugger, the process context is set to the currently running process. Note that either a variable of type PROCESS (returned as the result of a FORK) or an octal ProcessHandle is acceptable as input to this command.

SEt Root configuration [config]

sets the current configuration to be config, where config is at the outermost level (of its configuration). This command is sufficient for simple configurations of only one level. It is also useful in getting you to the outermost level of nested configurations, from which you may move "in" using SEt Configuration.

Program control

There are commands provided which allow you to determine the flow of control between the debugger and your program.

Kill session [confirm]

ends your debugging session, cleans up the state as much as possible, and returns to the Alto Executive. Use this command instead of SHIFT-SWAT or the boot button to leave the debugger.

Proceed [confirm]

continues execution of the program (i.e., proceeds from a breakpoint, resumes from an uncaught signal).

Quit [confirm]

returns control to the dynamically enclosing instance of the debugger (if there is one). Executing a Quit has the effect of cutting the runtime stack back to the nearest enclosing instance of the debugger. Quitting from the outermost level of the debugger returns you to the Mesa Executive if it is loaded; otherwise it returns you to the Alto Executive. Quitting from the Mesa Executive returns you to the Alto Executive.

STart [address] [Confirm]

starts execution of the module whose frame is address. If the module has already been started, a RESTART will be done. Unlike the START statement in the Mesa language, no parameters may be passed.

Userscreen [confirm]

swaps to the user world for a look at the screen. Control is returned to the debugger with the SWAT key.

Low-level facilities

There are additional commands provided which allow the user to examine (and modify) what is going on in the underlying system.

ATtach Image [filename]

specifies the filename to use as an image file when the debugger has been bootloaded. It is useful when the user core image has been clobbered. The default extension for filename is ".image".

ATtach Loadstate [filename]

like ATtach Image, except that the initial rather than the current loadstate of the image file is used; this command is for wizards only.

ATtach Symbols [globalframe, filename]

attaches the globalframe to filename. This is useful for allowing you to bring in additional symbols for debugging purposes not initially anticipated. The default extension for filename is ".bcd". Only compiler output bcds for program modules can be attached; neither interfaces nor symbols files may be attached. This command overrides version checking.

COremap [confirm]

prints the following information (in octal) about the segments currently in memory: memory page number, memory address, file page number (if it is a file), number of pages, state {busy, free, data, file}, serial number (if it is a file), class {code, other}, access {Read, Write, Append}, lock. If the class is code, the module name is also given. The types of data segments are also printed; 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); the unknown type is displayed as data(?). Holding down ↑DEL terminates the printout.

Display Eval-stack

displays the contents of the Mesa evaluation stack (in octal), useful for low-level debugging or for displaying the (un-named) return values of a procedure which has been broken at its exit point. This command is most useful at octal breakpoints because the eval-stack is empty between most statements.

LOgin [user, password]

sets the default user 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.

Octal Clear break [globalframe, bytepc]

converse of Octal Set break. (Note: these octal commands are low-level debugging aids for system maintainers who must diagnose the higher-level debugging aids and system.)

Octal Read [address, n]

displays the n (decimal) locations starting at address.

Octal Set break [globalframe, bytepc]

sets a breakpoint at the byte offset bytepc in the code segment of the frame globalframe.

Octal Write [address, rhs]

stores rhs (octal) into the location address; the default for rhs is the current contents of address.

ReMote debuggee [host] [confirm]

not implemented.

Worry on [confirm]

taking a breakpoint in worry mode brings you into the debugger with the user core image undisturbed (i.e., no cleanup procedures are invoked, no frames are allocated, and memory is left unchanged). All of the debugger commands are allowed, with the exception of STart, Quit, and calling procedures with the interpreter.

Worry off [confirm]

turns off worry mode (this is the default state upon entering the debugger).

-- [comment]

inserts a comment into the debugger’s typescript file. Input is ignored after the dashes until a carriage return (CR) is typed.

↑Debug [confirm]

invokes the debugger nub which prompts with a "//". See Debugger nub for further details about the capabilities of the nub.

Debugger nub

The nub is a part of the debugger that contains primitive facilities for debugging the debugger as well as providing a minimal signal catcher and interrupt handler.

Typing ↑D (to the command processor of the debugger) brings you into the nub with a "//" prompt. The following limited set of commands are available in the nub: New, Read, Write, Trace Stack, Proceed, Quit, and Start. The semantics of the New command are explained below; the other commands have already been explained above (Read and Write are the same as Octal Read and Octal Write).

New [filename]

is just like the New command in the Mesa Executive.

Trace Stack

should be used if 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.