View source for KernelDebugRef - The Breakpoint (BP) Command

{{IBM-Reprint}}
{{KernelDebugRef}}

A breakpoint command is a string of any debugger commands that are executed when that breakpoint is hit. Semicolons (''';''') separate commands from one another. All command text is forced to uppercase unless surrounded by single quotation marks. Two single or double quotation marks remove their special meaning.

There are two kinds of breakpoints in the Kernel Debugger: temporary (sometimes called GO breakpoints) and sticky. Temporary breakpoints are set when the GO command is executed, and are removed when the debugger is entered again for any reason (hitting a GO or sticky breakpoint, a trap or fault, and so on). Sticky breakpoints are created, removed, and disabled with the commands defined below.

If a passcount greater than 0 is used, the breakpoint must be executed that many times before the debugger actually breaks. The default for passcount is 0.

If you set a breakpoint in an LDT segment when a thread other than thread 1 is running, that breakpoint will be moved to thread 1 when the current thread ends (so that it can still be addressed). When thread 1 ends, the breakpoint will be disabled, and its address will be marked as invalid. When that task slot is reused, the breakpoint can be enabled again.

On an 80386 processor, the debug registers can be used in a sticky breakpoint. See the BR command.

* '''BP[n] [<address>] [<passcount>] [<breakpoint commands>]'''

This command sets a new breakpoint, or changes an old sticky breakpoint. The '''n''' is an optional breakpoint number to select an old breakpoint for changing or forcing a new breakpoint to a certain number. If the breakpoint number is omitted, the first available breakpoint number is used. The number must be just after the '''BP''', with no intervening space. It must be a digit from ''0'' to ''9''. There must be a space after the number. Up to 10 breakpoints can be set. The address is required for all new breakpoints. Either an address or a breakpoint number can be used to change an existing breakpoint. A breakpoint command or passcount can be added or changed with commands such as '''BP0 "DB DS:ESI;R"''' or '''BP2 5'''.

* '''BR[<bp>] E|W|R|1|2|4 [<addr>] [<passcnt>] ["<bp cmds>"]'''

This command sets an 80386 debug register. Debug registers can be used to break on data reads and writes, and instruction execution. This is the same action used by a regular breakpoint. Up to 4 debug registers can be set and enabled at one time. Disabled BR breakpoints no longer occupy a debug register. The flag definitions are:

{| class="wikitable"
! Flag !! Description
|-
| 1 || One-byte length (default)
|-
| 2 || Word length on a word boundary
|-
| 4 || Doubleword length on a doubleword boundary
|-
| E || Break on instruction execution only (one-byte length only)
|-
| W || Break on writes only
|-
| R || Break on reads and writes
|}

For one-byte breakpoints, the linear address alignment can be anywhere; however, for word-length breakpoints the linear address must be on a word boundary. For a doubleword-length breakpoint, the linear address must be on a doubleword boundary. The debugger converts the address to linear, and prints an error message if the alignment is incorrect.

Only addresses that can be converted to linear (segment, selector, and linear, but not physical) can be used in the BR command address. The rest of the arguments are exactly like a BP command.

* '''BT[<n>] [<address>]'''

Sets a time-stamping breakpoint.

* '''BS'''

Shows the time-stamp entries.

* '''BL'''

This command lists the currently set breakpoints along with the current and original passcount and the breakpoint command, if any. An '''e''' after the breakpoint number means that the breakpoint is enabled; a '''d''' means that it is disabled. After either one of those, there may be an '''i''' which indicates that the address was invalid the last time the debugger tried to set or clear the breakpoint.

* '''BC[n],[n],...'''

Removes (clears) the list of breakpoint numbers from the debugger's breakpoint table.

* '''BE[n],[n],...'''

Enables the list of breakpoint numbers.

* '''BD[n],[n],...'''

Disables the list of breakpoint numbers, so the breakpoint is not actually put into the code but is saved until it is enabled.