KernelDebugRef - Breakpoint Commands

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Kernel Debugger Reference

Introduction Installing the Kernel Debugger The T Terminal Emulator Entering the Debugger Expressions Operator Precedence Binary Operators Unary Operators Numbers Strings Symbol Files Using Kernel Debugger Commands The Breakpoint (BP) Command Breakpoint Commands External Commands Using Default Commands External Debugger Commands Setting Useful Breakpoints Debugging Kernel Device Drivers Debugging VM Start Sessions Debugging a Remote System Notices

The following is a list of breakpoint commands:

• ? Help (?)
• BC Break Clear
• BD Break Disable
• BE Break Enable
• BL Break List
• BP Breakpoint
• BR Break Register
• BS Break Show time stamps
• BT Break Time stamp
• C Compare
• D Dump memory
• DB Dump memory in Bytes
• DD Dump memory in Dwords
• DG Dump GDT entries
• DI Dump IDT entries
• DL Dump LDT entries
• DW Dump memory in Words
• E Enter
• F Fill
• GO Go
• H Hex
• I Input
• J Conditional Execution
• K Stack trace
• LA List Absolute symbols
• LG List active Groups
• LM List Maps
• LN List Near symbols
• LS List all Symbols
• M Move
• O Output
• P Ptrace
• R Register
• S Search
• T Trace Point
• U Unassemble
• VC Clear Interrupt and trap Vector
• VL List Interrupt and trap Vector
• VT Add Interrupt and trap Vector
• VS Add Interrupt and trap Vector
• WA Add active map
• WR Remove active map
• Y Debugger option

Debug Support - The HELP/PRINT (?) Command

• ?[<expr>]|'string

This command prints help if no arguments are given. If an expression is given, it prints the value of the evaluated expression in all bases. If a string is given, it prints the string on the console.

The Breakpoint (BP) Command

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:

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.

Debug Support - The Compare (C) Command

• ##C <range> <addr>

This command compares the bytes in the memory location specified by <range> with the corresponding bytes in the memory locations beginning at <addr>. If all corresponding bytes match, the Kernel Debugger displays its prompt and waits for the next command. If one or more corresponding bytes do not match, each pair of mismatched bytes is displayed.

Debug Support - The DUMP (D) Command

• ##D [<range>]

Dumps memory in the last format used.

• ##DA [<range>]

Dumps memory in ASCII format only.

• ##DB [<range>]

Dumps memory in bytes and ASCII.

• ##DW [<range>]

Dumps memory in words.

• ##DD [<range>]

Dumps memory in doublewords.

• ##DG[A] [<range>]

This command dumps the global descriptor table (GDT). The A option causes all the entries to be dumped (not just the valid entries). The default is to display only the valid GDT entries. A range of entries or just one GDT entry can be displayed. If the command is passed an LDT selector, it displays LDT and the appropriate LDT entry.

• ##DI[A] [<range>]

This command dumps the interrupt descriptor table. The A option causes all the entries to be dumped (not just the valid entries). The default is to display just the valid IDT entries. A range of entries or just one IDT entry can be displayed.

• ##DL[A|P|S|H] [<range>]

This command dumps the local descriptor table. The A option causes all the entries to be dumped (not just the valid entries). The default is to display just the valid LDT entries. A range of entries or just one LDT entry can be displayed. If the command is passed a GDT selector, it displays GDT and the appropriate GDT entry.

The options P, S, and H are used to dump private, shared, or huge segment selectors respectively. To dump the huge segment selectors, give the shadow selector, followed by the maximum number of selectors reserved for that segment, plus 1.

• ##DP[A|D] [<range>]

This command dumps the page directory and page tables. Page tables are always skipped if the corresponding page directory entry is not present. Page directory entries appear with an asterisk next to the page frame, and are dumped once preceding a 4-megabyte region. As a general rule, you can ignore any lines beginning with an asterisk.

The A option dumps all present page directory and page table entries; the default is to skip page directory and page table entries that are zero. A zero page table entry means that the page is uncommitted.

The D option dumps only page directory entries. If a count is given as part of the optional range, it is interpreted as a page directory entry count. For example:

 ##dp ff000 l4
  linaddr   frame   pteframe  state res Dc Au CD WT Us rW Pn state
 %000ff000* 00343  frame=00343  2    0  D  A        U  W  P  resident
 %000ff000  000ff  frame=000ff  1    0  c  A        U  W  P  uvirt
 %00100000  002ae  frame=002ae  0    0  c  A        U  W  P  pageable
 %00101000  00215  vp id=0083c  0    0  c  u        U  W  n  pageable
 %00102000         vp id=0083d  0    0  c  u        U  W  n  pageable

                       bit   bit
                       set  clear
                       ---  -----
                key:    D    c    Dirty / clean
                        A    u    Accessed / unaccessed
                        U    s    User / supervisor
                        W    r    Writable / read-only
                        P    n    Present / not-present

The pteframe field contains the contents of the high-order 20 bits in the PTE. If the page is present, that value is the high-order 20 bits of the physical address that the page maps. To find out information about that physical address, you can issue the .MP command. If the page is not present, the pteframe field contains an index into the Virtual Page (VP) structure. The .MV command can dump information from that structure. A non-present page might still be cross-linked to a page of physical memory via the VP, and if it is, that physical address is in the frame column.

An exception is that uvirt pages (noted in the state column) are direct mappings of physical memory, without any other page manager structures associated with them.

• ##DT [<addr>]

This command dumps the TSS. If no address is given, it dumps the current TSS pointed to by the TR register, extracting the type (16-bit or 32-bit) from the descriptor access byte. If an address is given, the type is extracted from the 386env flag.

• ##DX

This command dumps the 80286 loadall buffer.

Debug Support - The ENTER (E) Command

• ##E <addr> [<list>]

This command enters one or more byte values into memory at the specified <addr>. If the optional <list> is given, the command replaces the byte at the given address and the bytes at each subsequent address until all values in the list have been used. If no <list> is given, the command prompts for a replacement value.

If an error occurs, all byte values remain unchanged.

If you do not supply a <list>, the Kernel Debugger prompts for a new value at <addr> by displaying this address and its current value followed by a dot (.). You can then replace the value, skip to the next value, return to a previous value, or exit the command by following these steps:

• To replace the byte value, simply type the new value after the current value. Make sure you type a 1-digit or 2-digit hexadecimal number. The command ignores extra trailing digits or other characters.
• To skip to the next byte, press the Spacebar. Once you have skipped to the next byte, you can change its value or skip to the next byte. If you skip beyond an 8-byte boundary, the Kernel Debugger starts a new display line by displaying the new address and value.
• To return to the preceding byte, type a hyphen (-). When you return to the preceding byte, the Kernel Debugger starts a new display line with the address and value of that byte.
• To exit the E command, press Return. You can exit the command at any time.

Debug Support - The FILL (F) Command

• ##F <range> <list>

This command fills the addresses in the given <range> with the values in the <list>. If the range specifies more bytes than the number of values in the list, the list is repeated until all bytes in the range are filled. If <list> has more values than the number of bytes in the range, the command ignores any extra values.

Debug Support - The GO (G) Command

• ##G[S][T][=<start-address>][<break-address>],,,

This command passes execution control to the program at the given <start-address>. Execution continues to the end of the code or until a <break-address> is encountered. The debug code also stops at any breakpoints set using the Breakpoint Set command.

If no <start-address> is given, the command passes execution to the address specified by the current values of the CS and IP registers. The equal sign (=) can be used only when a <start-address> is given.

If a <break-address> is given, it must specify an instruction address (that is, the address must contain the first byte of an instruction opcode). Up to ten addresses can be given at one time. The addresses can be given in any order. Only the first address encountered during execution causes a break. All others are ignored. If you attempt to set more than ten breakpoints, an error message is displayed.

The S option prints the time (in PERFVIEW timer ticks) from when the system is started with GS until the next entry is made in the debugger. No attempt is made to calculate and remove debugger overhead from the measurement.

The T option allows trapped exceptions to resume at the original trap handler address without having to unhook the exception. Instead of issuing the vcp d; t; and vsp d commands, you can use the T option of the GO command.

When execution of the debug code reaches a breakpoint, the kernel debugger normally displays the current values of the registers and flags. It also displays the next instruction to be executed. If the default command (Z) has been changed to something other than the REGISTER (R) command, the debugger executes the command list set by the last ZS command.

Debug Support - The Hex (H) Command

• ##H <value1> <value2>

This command displays the sum and difference of two hexadecimal numbers. The debugger adds <value1> to <value2> and displays the result. It then subtracts <value2> from <value1> and displays that result. The results are displayed on one line and are always hexadecimal. See the Help/Print Expression command for a more general expression display.

Debug Support - The INPUT (I) Command

• ##I <port>

This command reads and displays 1 byte from the given input <port>. The <port> can be any 16-bit port address.

Debug Support - The Conditional Execution (J) Command

• ##J <expr> [<command list>]

This command executes the command list if the expression evaluates to TRUE (nonzero). Otherwise, it continues to the next command in the command line (not including the ones in the command list). The command list must be in single or double quotation marks if there is more than one command (separated by ; ). A single command, or no command, can also be used without quotation marks. This command can be used in breakpoint commands to conditionally break when an expression becomes true, or even in the default command (Z).

The command BP 167:1454 "J AX == 0; G" breaks when AX equals 0 when this breakpoint is hit.

The command BP 167:1452 "J BY (DS:SI+3) == 40 'R; G';DG DS" prints the registers and continues execution, if when this breakpoint is hit the byte pointed to by DS:SI+3 is equal to 40. Otherwise, it prints the descriptor table entry in DS.

The command BP 156:1455 "J (MSW AND 1) == 1 'G'" breaks when the breakpoint is reached in real mode. BP 156:1455 "J (MSW AND 1)" is a shortcut that does the same thing (like C Boolean expressions).

See the default command (Z) for more examples.

Debug Support - The Stack Trace (K) Command

• ##K[S|B] [<SS:EBP>] [<CS:EIP>]

This command threads through the BP chain on the stack and prints the address, 4 words or doublewords of parameters, and any symbol found for the address. The starting stack frame address (SS:EBP) and the initial code segment (CS:EIP) can be specified. Defaults are SS:EBP and CS:EIP. The S (Small) option indicates that the frame is 16 bits wide, and the B (Big) option indicates that the frame is 32 bits wide. The default depends on the D bit in the CS selector.

Debug Support - The List Near Symbol Command (LN) Command

• ##LN [<addr>]

This command lists the nearest symbol both forward from and backward to the address passed. The default is the current disassembly address. All the active maps are searched.

There is the possibility that there will be duplicates when <addr> is specified as a selector:offset. Make sure that you have selected the correct slot (with the .S command) before you issue the LN command with a selector:offset.

Debug Support - The List Groups (LG) Command

• ##LG [<mapname>]

This command lists the selector or segment and the name for each group in the active maps or the specified map.

Debug Support - The List Maps (LM) Command

• ##LM

This command lists all the current symbol files that are loaded and shows which ones are active.

Debug Support - The List Absolute Symbols (LA) Command

• ##LA [<mapname>]

This command lists all the absolute symbols in the active maps or the specified map.

Debug Support - The List Symbols (LS) Command

• ##LS <addr>

This command lists all the symbols in the group that the address is in.

Debug Support - The Add/Remove Active Map (WA/WR) Commands

• ##WA <mapname> | *
• ##WR <mapname> | *

WA adds a map to the active list. WR removes it.

Debug Support - The Move (M) Command

• ##M <range> <addr>

This command moves the block of memory specified by <range> to the location starting at <addr>.

All moves are guaranteed to be performed without data loss, even when the source and destination blocks overlap. This means the destination block is always an exact duplicate of the original source block. If the destination block overlaps some portion of the source block, the original source is changed.

To prevent data loss, this command copies data from the source block's lowest address first whenever the source is at a higher address than the destination. If the source is at a lower address, this command copies data from the source's highest address first.

Debug Support - The Output (O) Command

• ##O <port> <byte>

This command sends the given <byte> to the specified output <port>. The <port> can be any 16-bit port address.

Debug Support - The Ptrace (P) Command

• ##P[N|T] [=<start-address>] [<count>]

This command executes the instruction at the given <start-address>, and then displays the current values of all the registers and flags (or whatever the Z command has been set to).

The difference between PTRACE and TRACE commands is that PTRACE stops after instructions such as CALL, REP MOVSB, and so on, instead of tracing into the call or each rep string operation.

If the optional <start-address> is given, the command starts execution at the given address. Otherwise, it starts execution at the instruction pointed to by the current CS and IP registers. The equal sign (=) may be used only if a <start-address> is given.

If the optional <count> is given, the command continues to execute <count> instructions before stopping. The command displays the current values of the registers and flags for each instruction before executing the next.

The N option suppresses the register display, so that only the assembly line is displayed. This only works if the default command (see the Z command) is an R (the normal setting).

The T option allows the original trap handler address to be traced into without having to unhook the exception. Instead of issuing the vcp d; t; vsp d commands, you can use the T option of the PTRACE command.

Debug Support - The Register (R) Command

• ##R[T][<register-name> [<value>]]

This command displays the contents of a CPU register and allows the contents to be changed to a new value.

The T option toggles the regterse flag (see the Y command).

If no <register-name> is given, the command displays all the registers, flags, and the instruction at the address pointed to by the current CS and IP register values.

If a <register-name> is given, the command displays the current value of the given register, and prompts for a new value. If both a <register-name> and <value> are given, the command changes the register to the given value.

The <register-name> can be any one of the following names:

• AX, BX, CX, DX, SI, DI, BP, SP, IP, PC - general registers
• DS, ES, SS, CS - segment registers
• GDTB - GDT base as a linear address
• GDTL - GDT limit
• IDTB - IDT base as a linear address
• IDTL - IDT limit
• TR, LDTR - TR, LDTR registers
• IOPL - input/output privilege level portion of flag registers
• F - flag register
• MSW - Machine status word

The 80386 <register-names> are the following (in addition to the above):

• EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP - extended general registers
• FS, GS - segment registers
• EF - extended flag register
• CR0, CR2, CR3 - control registers
• DR0, DR1不变, DR2, DR3, DR6, DR7 - debug registers
• TR6, TR7 - test registers

IP and PC name the same register - the Instruction Pointer. F is a special name for the Flags register.

To change a register value, supply the name of the register when you enter the REGISTER command. If you do not also supply a value, the command displays the name of the register, its current value, and a colon prompt. Type the new value, and press Return. If you do not want to change the value, just press Return. If you enter a name that is not allowed, the command displays an error message.

To change a flag value, supply the register name F when you enter the REGISTER command. The command displays the current value of each flag as a two-letter name. The following is a table of flag values: L (Plus) Zero ZR NZ Aux Carry AC NA Parity PE (Even) PO (Odd) Carry CY NC Nested Task NT (toggles)

At the end of the list of values, the command displays a hyphen (-). When you see the hyphen, enter new values for the flags you want to change, and then press Return. You can enter flag values in any order. Spaces between values are not required. Flags for which new values are not entered remain unchanged. If you do not want to change any flags, just press Return.

If you enter a name other than those shown above, the command prints an error message. The flags up to the error are changed; flags at and after the error are not changed.

Changing the MSW (Machine Status Word) is the same as changing the flag registers, but with the following flag names:

FLAG	SET	CLEAR
Protected Mode	PM	(toggles)
Monitor Processor Extension	MP	(toggles)
Emulate Processor Extension	EM	(toggles)
Task Switched	TS	(toggles)

Toggles means that if the flag is set, using the flag name in the REGISTER command clears it. If the flag is clear, using the flag name in the REGISTER command sets it.

Debug Support - The Search (S) Command

• ##S <range> <list>

This command searches the given <range> of memory locations for the byte values given in <list>. If the bytes in the list are found, the command displays the address of each occurrence of the list. Otherwise, it displays nothing.

The <list> can have any number of bytes. Each must be separated by a space or comma. If the list contains more than one byte, this command does not display an address unless the bytes beginning at that address exactly match the value and order of the bytes in the list.

Debug Support - The Trace (T) Command

• ##T[A|C|N|S|T|X][=<start-address>][<count>][<addr>]

This command executes the instruction at the given <start-address>, and then displays the current values of all the registers and flags.

If the optional <start-address> is given, the command starts execution at the given address. Otherwise, it starts execution at the instruction pointed to by the current CS and IP registers. The equal sign (=) may be used only if a <start-address> is given.

If the optional <count> is given, the command continues to execute a number of instructions equal to <count> before stopping. The command displays the current values of the registers and flags for each instruction before executing the next instruction.

The A option allows the user to specify an ending address for the trace. Instructions are traced until [<addr>] is reached.

The C option suppresses all output, and counts instructions traced. An end address is required for this command.

The N option suppresses the register display, so that only the assembly line is displayed. This only works if the default command (see the Z command) is an R (the normal setting).

The S (special trace) option is identical to the C option, except that the instruction and count are displayed for every call and the return from that call.

The T option allows the original trap handler address to be traced into without having to unhook the exception. Instead of issuing the vcp d; t; and vsp d commands, you can use the T option of the TRACE command.

The X option forces the debugger to trace regions of code known to be untraceable (such as, _PGSwitchContext).

Debug Support - The Unassemble (U) Command

• ##U [<range>]

This command displays the instructions in a mnemonic format. All the 80386 and 80387 opcodes can be displayed.

If given a <range>, the specified address is displayed for the number of bytes specified. If the <range> contains the L option (for example, u 90:234 l3), this specifies the number of lines to display.

Debug Support - The Interrupt and Trap Vector (VL) Command

• ##VL[N | P | V | R | F]

This command lists the real- and protected-mode vectors that the debugger intercepts. Vectors that have been set with VT (rather than with VS) are printed with an asterisk following the vector number. VLR lists only the real mode vectors, and VLP lists only the protected mode vectors. VL lists both, as follows:

``` R 0 1 2 3 4 5 6 V 0 1 2 P 0 1 2 3 4 5 6 7 8* 9 A B ```

The N (Noisy) option lists the traps that beep when hit.

The F (Fatal) option causes the kernel to route the faults that are fatal to a process to the debugger instead of displaying the popup message. For GP faults, VSF D is the same as VSP D. For page faults, VSP E traps all ring 3 and ring 2 page faults, and VSF E traps only the invalid page faults.

• ##VT[N | P | V | R | F] n[,n,...]

This command adds a new vector that the debugger intercepts. VTR installs a debugger handler in the real mode IDT. VTP installs a debugger handler in the protected mode IDT. VSV or VTV intercepts V86 mode exceptions or traps.

The N option causes the intercepted traps to beep when hit.

The F (Fatal) option causes the kernel to route the faults that are fatal to a process to the debugger instead of displaying the popup message. For GP faults, VSF D is the same as VSP D. For page faults, VSP E traps all ring 3 and ring 2 page faults, and VSF E traps only the invalid page faults.

• ##VS[N | P | V | R | F] n[,n,...]

This command is the same as VT, except that VS does not intercept ring 0 interrupts. The VSV and VTV commands intercept V86 mode exceptions or traps.

The N option causes the intercepted traps to beep when hit.

The F (Fatal) option causes the kernel to route the faults that are fatal to a process to the debugger instead of displaying the popup message. For GP faults, VSF D is the same as VSP D. For page faults, VSP E traps all ring 3 and ring 2 page faults, and VSF E traps only the invalid page faults.

• ##VC[N | P | V | R | F] n,[n],...

This command clears the vectors indicated, reinstalling whatever address was in the vector before the debugger obtained the vector.

The N option causes the affected traps to not beep when hit. It does not clear the trap itself.

The F (Fatal) option causes the kernel to route the faults that are fatal to a process to the debugger instead of displaying the popup message. For GP faults, VSF D is the same as VSP D. For page faults, VSP E traps all ring 3 and ring 2 page faults, and VSF E traps only the invalid page faults.

Note: If you want to intercept general protection faults before the operating system does, then you can issue VTP D before the fault is hit, examine the information about the fault, and issue VCP D and G to let the system GP handler get control and end the process. Alternatively, you can issue the VCP D command after hitting the fault, and trace into the exception handler. The TT and GT commands do this automatically.

Debug Support - The Debugger Option (Y) Command

• ##Y[?] [386env|dislwr|regterse]

This command allows the debugger configuration to be changed. The ? prints the current options supported. The Y command by itself prints the current state of the options. The Y command and a flag name sets or toggles an options flag. The flags are as follows:

• 386env 32-bit environment (toggles)
• dislwr lowercase disassembly (toggles)
• regterse terse register set (toggles)

All these flags toggle their state when set, and are printed only when the option is on.

The 386env flag controls the size of addresses, registers, and so on when displayed. When this option is on, addresses, registers, and so on are printed in 32-bit formats; otherwise they are printed in 16-bit formats. This flag has nothing to do with the processor in which the debugger is executing. It only concerns the display sizes.

The dislwr flag controls the disassembler's lowercase option. When the flag is on, disassembly is in lowercase.

The regterse flag controls the number of registers displayed in the register dump command. In the 32-bit format, when the regterse flag is on, only the first three lines are displayed (instead of the normal six-line plus disassembly-line display). In the 16-bit format (386env off), only the first two lines of the normal three-line display (plus the disassembly line) are printed.