Swat Introduction: 5.3 Essential Commands: Breakpoints and Code Stepping

| Up: GEOS SDK TechDocs | Up | Prev: 5.2 Attaching and Detaching | Next: 5.4 Examining and Modifying Memory

The commands in this group are used to stop at specified breakpoints in an application's code and then step through the code line by line if necessary. These commands are often used with each other to examine critical areas in the application source code.

Breakpoints

stop, brk, go, cbrk, spawn

The stop , brk and cbrk commands are used to set breakpoints. The breakpoint commands have many subcommands controlling the actions and attributes of a particular breakpoint.

The cbrk command sets breakpoints to be evaluated by the Swat stub; brk sets them to be evaluated by Swat. The Swat stub can evaluate the conditions much faster than Swat, but cbrk has certain limitations: only a limited number of breakpoints can be set using cbrk , and these breakpoints can only compare registers when the breakpoint is hit with a given set of criteria.

stop

stop in <class>::<message> [if <expr>]
stop in <procedure> [if <expr>]
stop in <address-history-token> [if <expr>]
stop at [<file:]<line> [if <expr>]
stop <address> [if <expr>]

This is the main command to use when setting breakpoints in C programs. The "stop in" command will set a breakpoint at the beginning of a procedure, immediately after the procedure's stack frame has been set up. The "stop at" command will set a breakpoint at the first instruction of the given source line. If no <file> is specified, the source file for the current stack frame is used. If a condition is specified by means of an "if <expr>" clause, you should enclose the expression in curly braces to prevent any nested commands, such as a "value fetch" command, from being evaluated until the breakpoint is hit.

brk

brk [<sub-command>]

The brk (breakpoint) command is used for setting nearly all breakpoints in an application's code. The simplest way to use it is to type brk with a single addr argument. The address is usually a routine name for a suspect procedure, and when the breakpoint is reached the code-stepping commands can be used to examine it carefully. The brk command can also create conditional breakpoints which will only be taken if certain conditions are satisfied. Once set, a breakpoint is given an integer number which can be obtained using the list subcommand (see Breakpoints ).

brk <addr> [<command>]
The brk command without any subcommands sets an unconditional breakpoint at the address specified in addr . If the command argument is passed, the given swat command will be carried out when the breakpoint is hit.
brk delete <break>*
Deletes the given breakpoint(s), just as clear , above.
brk enable <break>*
Enables the given breakpoint(s). Has no effect on previously enabled breakpoints. If no breakpoint is given, all breakpoints for the current patient are enabled.
brk disable <break>*
Disables the given breakpoint(s). It has no effect on previously disabled breakpoints. If no breakpoint is given, it disables all breakpoints for the current patient.
brk list [<addr>]
Lists all the breakpoints, whether they are enabled, where they are set, their conditions, and what actions they will take if encountered. If addr is given, it returns the breakpoint numbers of all breakpoints set at the given address.

Breakpoints

(geos:0) 4 => brk list
Num S Address Patient Command/Condition
1   E loader::kcode::LoaderError all echo Loader death due to [penum
					LoaderStrings [read-reg ax]]
					expr 1
2   E kcode::FatalError all
 					why
 					assign kdata::errorFlag 0
 					expr 1
3   E kcode::WarningNotice all why-warning
4   E kcode::CWARNINGNOTICE all why-warning
(geos:0) 5 => stop in Mess1Draw
brk5
(geos:0) 6 => brk list
Num S Address Patient Command/Condition
1   E loader::kcode::LoaderError all echo Loader death due to [penum
					LoaderStrings [read-reg ax]]
 					expr 1
2   E kcode::FatalError all
 					why
 					assign kdata::errorFlag 0
 					expr 1
3   E kcode::WarningNotice all why-warning
4   E kcode::CWARNINGNOTICE all why-warning
5   E <ss1::MESS1_TEXT::Mess1Draw+10 all halt
(geos:0) 7 => brk dis brk4
(geos:0) 8 => brk list
Num S Address Patient Command/Condition
1   E loader::kcode::LoaderError all echo Loader death due to [penum
					LoaderStrings [read-reg ax]]
 					expr 1
2   E kcode::FatalError all
 					why
 					assign kdata::errorFlag 0
 					expr 1
3   E kcode::WarningNotice all why-warning
4   D kcode::CWARNINGNOTICE all why-warning
5   E <ss1::MESS1_TEXT::Mess1Draw+10 all halt
(geos:0) 9 =>

go

go [<address-expressions>]

The go command sets a one-time breakpoint and resumes execution on the target PC. The net effect of this is to let the target go until it hits a given address, then stop.

cbrk

cbrk [<sub-command>]

The cbrk (conditional breakpoint) command is used to set fast conditional breakpoints. This command is very similar to the brk command above, except that the condition is evaluated by the Swat stub--this increases the speed of the evaluation. There are, however, certain restrictions on the cbrk command: only a limited number of breakpoints can be set (eight), and the scope of the evaluation is limited to comparing word registers (or a single word of memory) to a given set of values.

In the following descriptions, criteria stands for a series of one or more arguments of the form:

<register> <op> <value>
register
One of the machine's registers or "thread," which corresponds to the current thread's handle.
op
One of the following ten comparison operators: = (equal), != (not equal), > (unsigned greater-than), < (unsigned less-than), >= (unsigned greater-or-equal), <= (unsigned less-or-equal), +> (signed greater-than), +< (signed less-than), +>= (signed greater-or-equal), +<= (signed greater-or-equal). These correspond to the 8086 instructions JE, JNE, JA, JB, JAE, JBE, JG, JL, JGE, JLE, respectively.
value
A standard Swat address expression. The resulting offset is the value with which the register will be compared when the breakpoint is hit.
cbrk <addr> <criteria>*
The basic cbrk command sets a fast conditional breakpoint at the address specified in addr .
cbrk cond <break> <criteria>*
Changes the criteria for the breakpoint. If no criteria is given the breakpoint becomes a standard, unconditional breakpoint.

spawn

spawn <patient-name> [<addr>]

The spawn command is used to set a temporary breakpoint in a process or thread which has not yet been created. The arguments are

patient-name
The permanent name, without extension, as specified by the name directive in the .gp file; this is the name of the patient in which to set a temporary breakpoint. A unique abbreviation is sufficient for this argument.
addr
A particular address at which to place the breakpoint. If no address is given, Swat will stop as soon as the given geode is loaded.

This command is used to stop the geode before any of its code can be run, allowing breakpoints to be set in the desired routines. If you could not stop the machine in this manner, the application could hit a buggy routine before a breakpoint could be set in that routine. The spawn command can also be used to catch the spawning of new threads which is useful to keep track of the threads being used by an application (see The spawn Command ).

Swat Display 3-5 The spawn Command

(geos:1) 12 => spawn mess1 Mess1Draw
Re-using patient math
Re-using patient borlandc
Re-using patient mess1
Thread 0 created for patient mess1
Interrupt 3: Breakpoint trap
Stopped in Mess1Draw, line 211, "C:OMNIGO/Appl/SDK_C/MESS1/MESS1.GOC"
Mess1Draw(GStateHandle gstate) 				/* GState to draw to */
(mess1:0) 13 =>

Code Stepping

srcwin, istep, sstep

Once an application is stopped at a breakpoint and you want to examine the code line by line, you can use the commands istep (instruction step) and sstep (source step). These enter the instruction step mode or source step mode to examine and execute the application code line by line.

The subcommands for both istep and sstep are nearly the same and are used for actions including stepping to the next line, skipping the next instruction, or exiting the step mode and continuing the execution of the application. The istep and sstep commands are very similar except that istep is used when stepping through assembly source code (thus stepping through instructions), and sstep is used for stepping through C source code.

srcwin

srcwin <numlines> [view]

The srcwin command will display the source code surrounding the presently executing code any time execution is stopped. The presently executing line will be highlighted. You may set breakpoints with the mouse by clicking on the line numbers which appear to the side. To scroll the srcwin buffer use the arrow keys, the <PgUp> key, and the <PgDn> key.

istep, sstep

istep [<default subcommand>]
sstep [<default subcommand>]

These two commands are used to single-step through code, executing one or more instructions at a time. The default subcommand argument determines the action taken by Swat when the Return key is pressed. For example, the command

[hello3:0] 7 => istep n

will enter instruction step mode, and subsequently pressing the Return key will have the same effect as pressing n . If no default command is given, pressing Return has the same effect as pressing s .

The subcommands to the istep and sstep commands are

s (single step)
Step one instruction. This is the most frequently used subcommand.
n, o (next, over)
Continue to the next instruction but do not display any procedure calls, repeated string instructions, or software interrupts. They will stop when GEOS returns to the same frame as the previous displayed instruction. The frame is the same when the stack pointer and current thread are the same as when the n subcommand was given. o differs from n in that it executes all instructions in a macro without further interpretation and can only be used with istep . If a breakpoint other than for the next instruction is hit, it will take effect as long as the above conditions are met.
N, O (Next, Over)
These are like n and o but will stop whenever a breakpoint is hit even if the frame is different. O will execute all instructions in a macro without further interpretation, and it can only be used with istep . If a breakpoint other than one for the next instruction is hit, it will take effect as long as the above conditions are met.
q, Esc, <space> (quit)
These stop istep/sstep and return to the command level. These subcommands are used when a point in the code is reached where another command needs to be used--to examine memory, for example.
c (continue)
This exits istep and continues the execution of the application. When GEOS next stops, Swat will return to the command prompt.
M (message)
This will continue until the next handled message is received. When the handler is invoked, Swat will return to step mode. This subcommand is often used with the ObjMessage() and ObjCallInstanceNoLock() assembly routines.
F (finish message)
This finishes the current message, stops when execution returns to a frame that is not part of the kernel, and remains in step mode.
f (finish frame)
This finishes the current stack frame, stops, and remains in step mode.
S (skip instruction)
This skips the current instruction, does not execute it, and goes on to the next instruction in step mode.
| Up: GEOS SDK TechDocs | Up | Prev: 5.2 Attaching and Detaching | Next: 5.4 Examining and Modifying Memory