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 debug external (dot) commands include the following:

.? Help for external commands
.B COM port Baud rate
.C Dump ABIOS Common data area
.D Dump DOS data structures
.I Swap In page
.IT Swap In TSD
.K User stack trace
.LM Print MTE segment table
.MA Memory Arena record dump
.MC Memory Context record dump
.ML Memory ALias record dump
.MO Memory Object record dump
.MP Memory Page frame dump
.MV Memory Virtual page structure dump
.P Print Process information
.R User Register
.REBOOT Restart the system
.S Task context change
.T RAS Trace buffer print

Debug Support - The Help (.?) Command

##.?

This command prints the help menu for the external debugger commands.

Debug Support - The COM Port BAUD Rate (.B) Command

##.B <baud rate> [<port addr>]

This command sets the baud rate of the debugging port. Valid values for the baud rate are 150, 300, 600, 1200, 2400, 4800, 9600, and 19200. Because the default base of numbers for the debugger is 16, you must add the suffix T to a decimal (base 10) number to indicate a decimal value. For example, if you want to debug over a 1200-baud line, the correct command is:

.B 1200T

The port address option can be 1 for COM1, or 2 for COM2. Anything else is taken as a base port address. During initialization, if there is no COM2, the debugger checks for COM1 and then any other COM port address in the ROM data area, and uses it as the console.

Debug Support - The Dump ABIOS Common Data Area (.C) Command

##.C

This command dumps the ABIOS common data area.

Debug Support - The Dump OS/2 Data Structures (.D) Command

##.D [<addr>]

This command displays a few common OS/2 data structures. The data structures supported are:

Name	Description
SFT	System file table entry
VPB	Volume parameter block
DPB	Disk parameter block
CDS	Current Directory Structure
KSEM	Internal Kernel Semaphore
DT	Disk Trace
DEV	Device driver header
REQ	Device driver request packet
MFT	Master file table entry
BUF	File system buffer
BPB	BIOS parameter block
SEM32	32-bit Semaphore structure
MUXQ	32-bit Semaphore MuxQ chain
OPENQ	32-bit Semaphore OpenQ chain

Debug Support - The Swap in TSD or Page (.I/.IT) Commands

##.I[D|B] [<addr>]

If only .I is given, the page enclosing that address is swapped in. The address may include an optional task slot number override, as in %3|20000.

##.IT[D|B] [<slot>]

The .IT command swaps in the corresponding task's TSD. The D option queues a single swap-in request to be acted upon at task time by the KDB daemon thread. If the D option is not given, this command is restricted to being executed in user mode (ring 3 or ring 2) or in kernel mode if it is not interrupt time, and if the thread is not blocked when swapping or leaving the kernel (InDos is 0). The .I[T] command checks for all these conditions, and prints an error.

Debug Support - The User Stack Trace (.K) Command

##.K[<slot> | # | *]

This command threads through the BP chain on the user stack of the slot specified, and prints the address, 4 words or doublewords of parameters, and any symbol found for the address. The default starting point is taken from the user SS:EBP and CS:EIP of the debugger's default slot (the one selected with .S). 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 user's CS.

Debug Support - The Print Module Table Entry Segment Table (.LM) Command

##.LM[O][L|P|V|X] [<hobmte|laddr|"modulename">]

This command prints module table entries (MTEs) and their associated object and segment table entries.

The O option suppresses the object or segment table display.

The L option displays only library (.DLL) MTEs.

The P option displays only Physical Device Driver (PDD) MTEs.

The V option displays only Virtual Device Driver (VDD) MTEs.

The X option displays only executable (.EXE) MTEs.

If a nonzero HOBMTE is given, only those MTEs with a matching HOBMTE are printed. If a nonzero linear address is given, only the MTE pointed to by the linear address is printed. If a quoted string is given, only those MTEs with a matching module name are printed. The module names for A:\BAR.DLL and C:\FOO\BAR.EXE are both BAR. No drive, path, or extension information should be given.

Debug Support - The Memory Arena Record Dump (.MA) Command

##.MA[A|B|C|F|H|L|M|R] [<har|laddr>] | [<har|laddr> L<number of entries>]

This command displays the virtual memory manager's arena records. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered a pointer to an arena record. One record or a range of records can be displayed.

The A option displays all contexts (the default is the current context only).

The B option displays only busy (allocated) entries. This is the default.

The F option displays only free (unallocated) entries.

The C option finds the corresponding object record, and displays the arena, object, alias, and context record chains.

The H option follows hash links, displaying entries.

The L option follows forward links, displaying entries.

The R option follows reverse links, displaying entries.

The M option causes all arena records whose linear address range encloses the given linear address to be displayed. A linear address must also be given, and no count is allowed. Context information is ignored, so if the linear address is valid in multiple contexts, multiple arena records are displayed. A physical address may be given instead of a linear address to allow non-present linear addresses to get past the debugger's expression analyzer. If a selector address type is used, it must be converted to a linear address on the command line.

If you ever need to find out what option owns a selector because of a GP fault in some unknown LDT or GDT segment or memory object, one of the following commands is useful:

``` .M ```

or

``` .MAMC CS:EIP ```

The .MAMC CS:EIP command displays the arena record and memory object record (and the owner) of the code segment. It also follows the context record chains and displays them. The CS can be substituted with any selector, and the EIP with any offset. This command converts the selector:offset into a linear address automatically, so the resulting address can be used to find and interpret the arena records and memory object records.

Since .M defaults to .MAMC when no options are given, and since specifying the M option to any .M command uses CS:EIP for the default, .M is the same as .MAMC CS:EIP.

Debug Support - The Memory Context Record Dump (.MC) Command

##.MC[B|C|F] [<hco|laddr>] | [<hco|laddr> L<number of entries>]

This command displays the virtual memory manager's context records. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered to be a pointer to a context record. One record or a range of records can be displayed.

The B option displays only busy (allocated) entries. This is the default.

The F option displays only free (unallocated) entries.

The C option also follows context record chains and displays them.

Debug Support - The Memory Alias Record Dump (.ML) Command

.ML[C] [<hal|laddr>] | [<hal|laddr> L<number of entries>]

This command displays the virtual memory manager's alias records. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered to be a pointer to an alias record. One record or a range of records can be displayed.

The B option displays only busy (allocated) entries. This is the default.

The F option displays only free (unallocated) entries.

The C option finds the corresponding object record, and displays the arena, object, alias, and context record chains.

Debug Support - The Memory Object Record Dump (.MO) Command

##.MO[B|C|F|M|N|P|S|V] [<hob|laddr>] | [<hob|laddr> L<number of entries>]

This command displays the virtual memory manager's memory object records. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered a pointer to an object record. One record or a range of records can be displayed.

This command attempts to display which process, MTE, or PTDA owns the segment. It displays the owner as a short ASCII string when appropriate. It displays the PID of the process and, if possible, the name of the module that owns this segment. Code segments normally have only the module name and no process ID. If the segment is an MTE, PTDA, or LDT, this command displays the object name, the process ID (if the segment is a PTDA), and the module name, if possible.

Here are a few examples of the owners that this command can display:

Owner	Description
free	Free memory
devhlp	Allocated by the AllocPhys devhlp
idevice	Installable device driver memory
system	System-owned memory
dosexe	The initial memory arena when the operating system started. This includes all of the system code and data segments
mte	A module table entry
ptda	A per task data arena
ldt	A local descriptor table

If it only has a PID or a module name, then this piece of memory is owned by the process or module.

The B option causes in-use (busy) object records to be displayed.

The F option causes free object records to be displayed.

The C option displays the arena, object, alias, and context record chains.

The M option causes all pseudo object records with an exactly matching linear address to be displayed. A linear address must also be given, and no count is allowed. If a selector address type is used, it must be converted to a linear address on the command line. A physical address may be given instead of a linear address to allow non-present linear addresses to get past the debugger's expression analyzer.

The N option causes non-pseudo object records to be displayed.

The P option causes pseudo object records to be displayed.

The S option causes object records with the semaphore busy or wanted to be displayed.

The V option causes object record linear addresses to be displayed. It also disables the owner interpretation.

Debug Support - The Memory Page Frame Dump (.MP) Command

##.MP[B|F|H|L|R|S] [<frame|laddr>] | [<frame|laddr> L<number of entries>]

This command displays the page manager's page frame structures. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered to be a pointer to a page frame structure. One record or a range of records can be displayed.

The B option displays only busy (allocated) entries. This is the default.

The F option displays only free (unallocated) entries.

The H option follows hash links, displaying entries.

The L option follows forward links, displaying entries.

The R option follows reverse links, displaying entries.

This data structure contains per-physical-page information. To find out the owner of a particular physical page, issue .MP FrameNumber, where FrameNumber is the physical address shifted right by 12 bits (take off 3 hex zeros). If the page is not free, the pVP field contains a flat pointer to the virtual page structure. Issue .MV %pVP, where pVP is the value from the .MP dump, to get the contents of the VP. The Hob field of the VP is a handle to the Object Record. Issue .MO Hob to dump it. This displays a readable string for the owner on the right of the display (see the .MO command). Issuing the .MA command for the Har field in the object record gives the base virtual address of the object containing the page (under va). Use the HobPg field of the VP to get the page offset within the object.

Debug Support - The Memory Virtual Page Frame Dump (.MV) Command

##.MV[B|F|L|R] [<vpid|laddr>] | [<swapid|laddr> L<number of entries>]

This command displays the swap manager's swap frame structures. If no handle or linear address is given, the entire table is displayed. If a linear address is given, it is considered to be a pointer to a swap frame structure. One record or a range of records can be displayed.

See the .MP command for an example.

The B option displays only busy (allocated) entries. This is the default.

The F option displays only free (unallocated) entries.

The L option follows forward links, displaying entries.

The R option follows reverse links, displaying entries.

Debug Support - The Print Process Status (.P) Command

##.P[B|U] [<slot> | # | *]

This command displays the current status of the process and thread. The asterisk (*) by the slot number denotes the currently executing task or the last task to have blocked. The number sign (#) marks what the debugger recognizes as the current task is (set by the .S command). If #, *, or a slot number is used on the command line, only the corresponding slot's information is displayed.

Without the B or U option, this command prints the PID, parent PID, command subtree number, thread number, state, priority, block ID, PTDA address, TCB offset, dispatch ESP, screen group, and name of the process or thread.

The B option displays the detailed blocked information. The handlesem entry is for the current virtual memory manager handle semaphores owned by this process. The child entry is for a child process that is being executed. It is printed after all the threads in the executing task (and their handlesem entries) have been printed.

The U option displays user state information, which includes the CS:EIP and SS:ESP at the time the kernel was entered, along with the number of arguments that were passed, their PTDA offset, and the offset of the register stack frame.

Debug Support - The User Register (.R) Command

##.R [<slot> | # | *]

The .R command displays the contents of the user's CPU registers, flags, and the next instruction to be executed for a specified slot. This command is available to the user at the time of entry to the kernel.

If no parameter is given, or if (#) is on the command line, the debugger's current slot (selected by the .S command) is used. If (*) is on the command line, the currently scheduled slot (or the last one to block) is used. Alternatively, if there is a number on the command line, it is taken as the slot to use.

Debug Support - The REBOOT (.REBOOT) Command

##.REBOOT

This command warm-starts the machine. The whole string .REBOOT must be typed.

Debug Support - The Task Context Change (.S) Command

##.S[S] [<slot> | *]

This command changes what the debugger thinks the current task context is. If no slot number is passed, it prints the current task number. This allows dumping of some process-specific data (the LDT or stack) for a task other than the current task. The S option also changes the SS and ESP to the new task's PTDA selector and dispatch ESP value. The original SS and ESP are automatically restored when the debugger stops, or when the .SS command is used to switch back to the current task. The (*) slot number changes the debugger's current task number to the real system task number.

Debug Support - The RAS Trace Buffer Print (.T) Command

##.T [<count>] [maj=<xx> [min=<yy>]]

This command dumps the RAS trace buffer, optionally dumping only events with the specified major and minor event codes.