Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > K

kwdb(1M)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

kwdb — invoke KWDB, the source level kernel debugger and crash dump analyzer

SYNOPSIS

kwdb [options] kernel_file

  • Run KWDB on a copy of the target kernel executable file on your host system.

kwdb -q4 [options] [kernel_file] [crash_dump_directory]

  • Run KWDB for crash dump analysis.

kwdb -q4 [options] kernel_file [remote_system:port]

  • Run KWDB for remote crash dump analysis.

kwdb -q4 [options] kernel_file /dev/[k]mem

  • Run KWDB for live memory analysis

DESCRIPTION

kwdb is a kernel debugging tool based on the HP WDB Source-Level Debugger, gdb. For complete information about this debugger and its commands, see HP KWDB Kernel Debugger Guide, Debugging with GDB, and Getting Started with HP WDB.

Use kwdb for the following tasks:

  • Perform source level debugging of HP-UX kernel and Dynamically Loadable Kernel Modules from a remote host system.

  • Analyze a crash dump.

  • Analyze the behavior of a running system.

Options

-b BAUDRATE

Set serial port baud rate for remote debugging. BAUDRATE is 19200 for PA-RISC systems or 57600 for Itanium-based systems.

-batch

Run in batch mode.

-cd=DIR

Change current directory to DIR.

-command=FILE

Execute gdb commands from a FILE.

-directory=DIR

Search for source files in the directory, DIR.

-epoch

Use output from the epoch emacs-GDB interface.

-exec=EXECFILE

Use the file, EXECFILE, as the executable file for debugging.

-fullname

Cause output information to go to the epoch emacs-GDB interface.

-help

List the version information and all options with brief explanations.

-m

Process all loaded DLKMs.

-nw

Do not use the Windows interface for debugging.

-nx

Do not execute commands from initialization files.

-objectdir=DIR

Search for object files in the directory, DIR.

-p

Enable PERL scripts to run in q4 programming mode.

-q4

Set kwdb to run in q4 mode.

-quiet

Do not print introductory and copyright messages.

-readnow

Read symbol files completely on its first access.

-se=FILE

Use the file, FILE, as both a symbol file and an executable file.

-symbols=FILE

Read symbols from the file, FILE.

-tui

Use a terminal user interface.

-type-clash

Generate table of type name clashes.

-write

Enable writing into kernel file and memory.

For remote debugging, kwdb has to be invoked with a local copy of the kernel file. Invoking kwdb with the -q4 option and a crash dump directory name as an argument starts kwdb for crash dump analysis in q4 mode.

Invoking kwdb with the -q4 option and kernel file name followed by a remote system:portnumber starts kwdb for analyzing crash dump on a remote system.

Invoking kwdb with /dev/mem or /dev/kmem as an argument starts kwdb for analyzing the local running system.

Commands

This manpage describes the most commonly used KWDB commands for kernel debugging.

Use the kwdb help command to see a complete list of commands, their explanations, and examples.

KWDB allows partial commands to be entered as long as the abbreviations are not ambiguous. For example, the following pairs of commands are equivalent:

(kwdb)kwdb -help (kwdb)kwdb -he (kwdb) break function_name (kwdb) b function_name (kwdb) info breakpoints (kwdb) i b

All address arguments are virtual addresses unless specified otherwise.

Getting Help

help

List the classes of commands.

help command

Describe the specified kwdb command.

Stopping KWDB

quit

Exit KWDB. Also typing q or EOF (CTRL- D) causes KWDB to quit.

CTRL-C

(INTERRUPT) Terminate the current command, or interrupt the target kernel.

detach

Release the target kernel from KWDB control and allow it to continue.

kill

Release the target kernel from KWDB control and reboot.

Attaching and Debugging Targets

Use the target command to debug a remote system. The target system must be booted with appropriate flags. The kernel debugger can be booted in either "boot-wait" mode or "boot-nowait" mode. In "boot-wait" mode, the kernel debugger will attach before the rest of the kernel boots. In "boot-nowait" mode, the debugger will attach after the kernel has fully booted.

After the target is specified, use the attach command to start a debugging session.

The target command has the following syntaxes:

target console lantron_name:20nn

Debug using the on-console debugger and kwdb via the remote console. lantron_name specifies the name of the terminal server such Lantronix hardware which is connected to the target system. nn is the port number for the remote console.

target ia64_kern comm_server[:47001]

Set up LAN-based debugging through the KWDB server on the communication server, comm_server, for Itanium-based architecture.

target serial devicefile

Set up RS-232-based debugging for the specified serial device file, devicefile.

target lantron_serial lantron_name :30nn

Set up Lantron serial debugging on the terminal server, lantron_name. nn is the serial port on the target system.

target nddb -h comm_server -t ethernet_mac_address

Debug an HP-UX 11.0 or earlier kernel using nddb compatibility mode. comm_server is the communication server. ethernet_mac_address is the Ethernet LAN MAC address of the LAN card used for debugger communications in the target system.

target pa_kern comm_server[:47001]

Set up LAN-based debugging on the kwdbd server on the comm_server for PA-RISC architecture.

target sub name_of_sub[:47001]

Set up debugging for a Superdome, Keystone, or ORCA system using SUB/SINC. name_of_sub is the console name of the system.

target udp ip-address

Set up UDP-based debugging. ip-address is the IP address of the target system.

target crash dir

Specify the target crash directory, dir, which is to be debugged. The target crash command is not required if kwdb is invoked with -q4 option. The attach command is not used with this target.

target devmem

kwdb runs on the target system and debugs live memory using /dev/mem or /dev/kmem. The target devmem command is not required if kwdb is invoked with the /dev/mem or /dev/kmem argument. The attach command is not used with this target system.

attach 0 [target_id]

Attach the remote target system. If target is connected through the kwdbd or nddbcs communication server, target_id is the Ethernet MAC address of target LAN. If communication is through SUB/SINC, target_id is the partition name.

Breakpoints

Breakpoints are used to stop execution at a particular location in a program. This section explains commands used for breakpoints.

break [file:]line

Set the breakpoint at the specified line number line in file.

break [file:]func

Set the breakpoint at the function func in file.

break *addr

Set the breakpoint at the specified address addr.

break

Set breakpoint at next instruction.

break [location] if expr

Break conditionally on a nonzero expr at the next instruction (or location specified as line or address or function).

clear

Delete breakpoints at next instruction.

clear [file:] func

Delete breakpoints at entry to the function at func.

clear [file:] line

Delete breakpoints on source line.

commands n [silent] command-list end

Execute command-list every time breakpoint n is reached.

cond n [expr]

Make a new conditional expression on breakpoint n. Make an unconditional expression if expr is omitted.

delete [n]

Delete breakpoints or the breakpoint n.

disable [n]

Disable breakpoints or the breakpoint n.

enable [n]

Enable breakpoints or the breakpoint n.

ignore n count

Ignore breakpoint at n, count number of times.

info break

Show breakpoints and watchpoints.

tbreak [args]

Specify a temporary breakpoint. Similar to the break command except that the breakpoint is temporary. When the breakpoint is reached, the breakpoint is disabled. args are accepted as in the break command.

watch *addr

Set the watchpoint at address specified by addr which is the default. Four bytes will be watched.

watch name

Set the watchpoint at a global symbol specified by name.

Kernel Stack

This section explains commands for examining the stack frames. The debugger assigns numbers to the stack frames starting from zero for the innermost (currently executing) frame.

backtrace [n]

bt[n]

Trace all frames in stack or n number of frames. If n is specified and is greater than zero (0), then start from the innermost frame. If n is specified and is less than zero, then start from the outermost frame.

down n

Select the frame that is n frames down.

frame [n]

Select frame n or the frame at address n. If n is not specified, then display the current frame.

info all-reg

Display all registers including floating point registers. This command is not supported in PA-RISC architecture.

info args

Display arguments of the selected frame.

info frame [addr]

Describe the selected frame, or the frame at addr.

info locals

Display locals of the selected frame.

info reg [rn]

Display register values for a selected frame. If rn is specified, then display register rn.

up n

Select a frame that is n frames up.

Execution Control

This section explains commands to control execution of instructions in a program.

call function(arg1, arg2,...arg8)

Call the specified function with up to eight 64-bit sized arguments.

continue [count]

Continue running. If count is specified, ignore this breakpoint count number of times.

finish

Continue executing until the current function returns.

jump line

jump *address

Resume execution at specified line number (line) or (address).

next [count]

This command is similar to the step command in that it executes the next command but it does not step into functions.

nexti [count]

ni [count]

This command is similar to the stepi command but does not step into functions.

return [expr]

Pop selected stack frame without executing. If an argument is given in expr, it is an expression for the value to return.

set var=expr

Evaluate expr without displaying it. Use this command for altering variables.

step [count]

Continue to execute until another source line is reached. If the repeat count is specified, execute count number of times.

stepi [count]

si [count]

Step by machine instructions rather than source lines.

until [location]

Execute or run until the next instruction. location is specified as a line, address, or function. If location is specified, run until the location is reached.

Display

This section explains commands for displaying values of different data structures of the program (kernel/dump) being debugged.

disassem [addr]

Display memory as machine instructions for the function at addr.

disassem [func]

Display memory as machine instructions for the function func.

print [/fmt] [expr]

Show the value of expr according to format fmt:

a

address, absolute and relative

c

character

d

signed decimal

f

floating point

o

octal

t

binary

u

unsigned decimal

x

hexadecimal

x [N|u|f] expr

Examine memory at the address specified by expr. The optional format specifications are specified by one of the following:

N

The count of how many units to display.

u

The unit size. One of

b individual bytes

g giant words (eight bytes)

h half words (four bytes)

w words (four bytes)

f

Printing format. Any format listed with print command, or

i machine instructions

s null-terminated string

display [/fmt] [expr]

Show the value of expr each time the kernel stops according to the format fmt listed with x command.

display

Display all enabled expressions on the list created with display command.

enable disp [n]

Enable display for all expression(s). Use the list number, n, to define a specific number of expressions to display.

info display

Display a numbered list of display expression(s).

undisplay [n]

Remove all expressions from the list of automatically-displayed expressions. Use the list number, n, to define a specific number of expressions to remove.

disable disp [n]

Disable display for all expression(s) Use the list number, n, to define a specific number of expressions to disable.

Symbol Table

This section explains commands for displaying different symbol related attributes in the program being debugged.

info var [regex]

Show all names types of global variables (all, or matching the regular expression specified by regex).

info address s

Show where the address of the symbol name s is stored.

info func[regex]

Show names, types of defined functions (all, or matching the regular expression specified by regex).

ptype [expr]

ptype type

Describe type, struct, union, or enum. If the expression, expr, is specified, it is described also.

whatis [expr]

Show data type of expr (or $) without evaluating.

Source Files

This section explains commands for source level kernel debugging. For example, commands for displaying and navigating the source while debugging.

dir names

Add directory names to the front of the source path.

dir

Clear the source path.

forw regex

Search the following source lines for the regular expression specified by regex.

info line num

Show the starting and ending addresses of code for the source line num.

info source

Show the name of the current source file.

info sources

List all source files in use.

list

Show the next ten lines of source list.

list -

Show the previous ten lines of source list.

list f,l

Show the source list from line f to line l.

list lines

Display the source surrounding lines, which is specified as one of the following:

*addr

Display the line containing addr.

[file:]num

Display the line number, num. If file is specified, then display the line number of file.

[file:]func

Display the beginning of the function, func. If file is specified, then display the beginning of func in file.

+off

Turn off lines after the last printed line.

-off

Turn off lines previous to last printed line.

rev regex

Search preceding source lines for the regular expression specified by regex.

show dir

Show current source path in dir.

DLKM Commands

This section explains commands for handling the Dynamically Loadable Kernel Modules while debugging. This debugging is similar to shared library debugging in application debugging.

catch load [modname]

Stop on loads of module modname. If modname is omitted, catch all loads.

catch unload [modname]

Stop on unloads of module modname. If modname is omitted, catch all unloads.

info sharedlibrary

Display information about loaded modules.

path directory

Add the directory to the search path for kernel modules.

tcatch load [modname]

Similar to the catch load command but a temporary catchpoint. The catchpoint which was set is deleted when hit. If modname is omitted, catch all loads.

tcatch unload [modname]

Similar to the catch unload command but temporary. Deleted when hit. If modname is omitted, catch all unloads.

uncatch load [modname]

Do not catch load for modname. If modname is omitted, do not catch any loads.

uncatch unload [modname]

Do not catch unload for modname. If modname is omitted, do not catch any unloads.

Special Debugging Commands

This section explains commands to modify kwdb parameters.

cpu select n

cs n

set cpu n

Select CPU n as the viewed CPU.

set kwdb cache [on|off]

Turn memory caching on or off.

set kwdb controlregs [on|off]

Enable (on) or disable (off) display of Itanium-based control registers.

set kwdb floatregs [on|off]

Enable (on) or disable (off) display of Itanium-based floating point registers.

set kwdb log [on|off]

If on, set logging of kwdb output to the file, kwdb-log. If off, then disable logging.

set kwdb logfile name

Change the name of log file from kwdb-log to name.

set kwdb memory_cache number

Set the number of pages for caching memory read from crash dump.

set kwdb ntimeout number

Set the number of retries for remote network I/O.

set kwdb performanceregs [on|off]

Enable or disable display of Itanium-based performance registers.

set kwdb remotelog [on|off]

Log data packet communications to and from the target to file kwdb-remote-log for support purposes. If off is specified, then disable logging.

set kwdb q4 [on|off]

Set kwdb to q4 mode (on) or turn q4 mode off.

set kwdb spaceid sid

Set the virtual space ID for memory access to sid.

set kwdb timeout number

Set number to define the timeout for remote network I/O in tenths of seconds.

set kwdb ttyoutput [on|off]

Set the terminal output on or off.

set print strings [on|off]

Control the printing of strings referenced by character pointers.

set thread addr

Set thread with the given address addr as the current context.

set crash event n

Set crash event n as the current context during crash dump analysis. n is the index of the crash event in the crash event table.

q4 Commands

Some q4 commands are prefixed with q4, because the same commands exist in KWDB with different behavior. If kwdb runs in q4 mode, this prefix is not required.

adddebug file

Add type information from an object file.

addmodule modname

Process the DLKM module modname for debugging.

catalog [-h] regex

Print cataloged types matching regex. Use the -h option to print the header even if output is redirected.

code [-o] [name|addr]

disassemble [-o] [name|addr]

Print the assembly code for function name or the function surrounding the address addr. You can use either the code or disassemble command.

-o

Read from the local copy of the kernel file, and not from the crash dump or remote target.

constant

Print enumerants in symbol table with values.

discard [cond_expr]

Discard structures satisfying a condition specified by cond_expr.

disassemble [name|addr]

Print the assembly code for function name or the function surrounding the address addr.

evaluate expr

Evaluate the expression expr, which may contain one or more of the following:

ltor (vaddr)

Get the physical address corresponding to the virtual address vaddr. vaddr can be an expression.

tooffset (long_addr)

Get the space of long_addr.

tospace (long_addr)

Move the offset of long_addr to space.

var_name =value

Create a variable var_name with the value of value.

examine

The format of the command is:

examine [-o|-r] [addr] [for no_of_lines] [using [n] fmt]

Print the contents of memory from address addr using the format specified.

-o

Set the flag to read the data from the kernel file and not from the crash dump or to read from the local copy while doing remote debugging.

-r

Set the flag to read the memory from given address without translation.

addr

Start reading memory from the value of addr. addr can be an expression. If omitted, use its value from the previous run.

for no_of_lines

Specify how many lines to read. no_of_lines can be an expression. If not given, use the value from the previous run. The default value is 1.

using [n] fmt

Print n number of items per line as per the format specified by fmt. fmt can be any of the following characters:

^

Decrement the address by the current increment (that is, back up over the previous value retrieved). Nothing is printed.

+

Increment the address by one. Nothing is printed.

-

Decrement the address by one. Nothing is printed.

a

Print the value of dot as a symbolic kernel address. The address is not incremented.

A

Print the value of dot as a decimal number. The address is not incremented.

b

Print the address in hexadecimal. Increment the address by one byte.

B

Print the address in octal. Increment the address by one byte.

c

Print a character. Increment address by one byte.

C

Print a character with backslash escapes to make it readable. Increment the address by one byte.

d

Print a half-word in decimal. Increment the address by two bytes.

D

Print a word in decimal. Increment the address by four bytes.

f

Print an IEEE float. Increment the address by four bytes.

F

Print an IEEE double. Increment the address by eight bytes.

i

Print an instruction. Increment the address by the size of instruction.

I

Print a bundle of instructions. The address is incremented by size of a bundle.

L

Print 64 bit in hexadecimal. The address is incremented by eight.

o

Print a half-word in octal. Increment the address by two.

O

Print a word in octal. Increment the address by four.

P

Print the word that dot points to as a symbolic kernel address. Increment the address by four.

s

Print a string. Increment the address by the length of the string (including the trailing null character).

S

Print a string with enough backslash escapes to make it readable. Increment the address by length of the string.

u

Print a half-word in unsigned decimal. Increment the address by two.

U

Print a word in unsigned decimal. Increment the address by four.

x

Print a half-word in hexadecimal. Increment the address by two.

X

Print a word in hexadecimal. Increment the address by four.

Y

Print a word as a date and time string. Increment the address by four bytes (see ctime(3C) for format information).

expr

Evaluate the expression expr (in kwdb q4 mode only).

fields [flags] [struct|union] type

listing fields of a specified type in the format defined by the following flags:

-c

print fields in C style.

-h

print header even if output is redirected.

-v

print fields with offset and size in C style.

-x

expand any embedded structures in C style.

forget [num|-num|name]

Delete the current pile or delete a specified pile as specified below. If a pile is not specified, then the current pile is deleted.

num

The pile number.

-num

The number of piles before the current pile.

name

The pile name.

help q4

Print a list of q4 commands

help q4 cmd

Print the help message for the specified q4 command, cmd.

history

Print the history of loaded data structures.

include file

Load the PERL script from the specified file.

info type-clash [regex]

Enable processing for type-clash and list the types of registers whose name match with the regular expression specified by regex. If the regex argument is omitted, list all types that have the name CLASH.

keep [cond_expr]

Select structures satisfying a condition, cond_expr.

load [-r] [type]from addr[max expr | skip expr] next next_field | until addr

Read a collection of structures:

-r

Read the structures without address translation.

type

The type of the data structure to read. If the type is not given, then use the type of addr if available.

from addr

Start reading structures from the value of addr. addr can be an expression.

max expr

Read at most expr number of structures.

skip expr

Skip expr number of structures before starting to read.

next next_field

The name of the field in the structure which points to the next structure in a linked list.

until addr

Read structures until addr is reached. addr can be an expression.

merge [num|-num|name]

Merge data from a pile specified by num, -num, or name to the current pile. See the forget command for information on num, -num, and name.

modules

Print details of currently loaded DLKM modules.

name it [num|-num|name]

Name the current pile or the pile specified with name.

pileon [type]from field

Read structures of type from values of field from the current pile.

pophistory

Pop the piles marked by last pushhistory.

pushhistory

Save the state of the current pile history for future popping.

q4 print

The format of the command is:

q4 print [options] field1 [%fmt], field2 [%fmt],...]

Print fields in the current pile. The options are:

%fmt

Print numerical value of the field using the %fmt format. Format characters for printf can be used in fmt.

-d

Print the integer fields in decimal format.

-h

Turn on the column heading even if the output is redirected.

-H

Turn off the column heading even if output is not redirected.

-o

Print integer fields in octal format.

-t

Print fields one per line instead of in multiple columns.

-x

Print integer fields in hexadecimal format.

q4 print

The format of the command is:

q4 print [options] [type] from addr

Print a structure from the value of addr. addr can be an expression.

options

All the options available for the first form of the q4 print command shown above are valid.

type

The type of the data structure to print. If the type is not given, use the type of addr if available.

from addr

Start printing structures from the value of addr. addr can be an expression.

q4 run func[args]

Run a PERL script function func with or without args.

q4 symbols regexp

Print kernel symbols matching regexp.

q4 trace [options] eventnum

Display the stack trace for the crash event number (num) for the crash target only. The options for all the q4 trace commands are as follows:

-f

Print input, local and output registers for each frame.

-u

Print registers for the first level and arguments for each frame.

-v

Verbose.

q4 trace [options] pc sp

Display stack trace with pc and sp (PA-RISC only).

q4 trace [options] pile

Display stack trace for structures from the current pile for process, processor, thread and crash event structures.

q4 trace [options] process at addr

Display stack trace for the process at addr.

q4 trace [options] processor num

Display stack trace for the processor number specified by num.

q4 trace [options] savestate at addr

Display stack trace for savestate at addr.

q4 trace [options] thread at addr

Display stack trace for thread at addr.

q4 unset var_name

Remove a user defined variable specified by var_name.

recall [num|-num|name]

Make a pile which is specified by num, -num, or name. See the forget command for information on num, -num, and name.

system cmd

Execute the shell command specified by cmd.

translate addr

Display the page table entry or translation registers used for translating addr.

variables

Display all user defined variables and values.

write

The format of the command is:

write [-o|-r] data at addr [using format]

Write the given data into memory or into a kernel file at the address specified by addr. Options -o and -r have the same meanings as explained in the examine command.

data

The data to be written.

addr

The address to write the data to. addr can be an expression including kernel symbols.

format

The format is the character b (for 1 byte), w (for 2 bytes), W (for 4 bytes), L (for 8 bytes), c (for 1 byte), or s (length of string). The default format for numeric data is W.

Miscellaneous Commands

This section explains commands for performing miscellaneous activities in the debugger while debugging the target.

cd dir

Set working directory to dir for the debugger and program being debugged.

define cmd

Define a new command, cmd. The definition appears on following lines, one command per line. End with a line that has only

document cmd

Document a user-defined command, cmd. Give documentation on the following lines. End with a line that has only

file [file]

Use file as the program to be debugged.

pwd

Print the working directory.

shell command_line

Execute the rest of the line with command_line as a shell command.

source script

Read and run commands from a file named script.

The gdb commands not supported by KWDB include:

core [file], exec [file], handle signal, run, set args, set env, signal, throw, exec, fork, vfork, and tty.

EXTERNAL INFLUENCES

The following environment variables influence the behavior of KWDB.

PXDB

The path of the pxdb file for kwdb to use for preprocessing the kernel file and dlkm module files. The default path is /usr/ccs/bin/pxdb.

Q4_PERL_PATH

The path of the PERL for KWDB to use while running in PERL programming mode. The default path is /opt/perl/bin/perl.

Q4_ROOT

The path which controls the location of PERL and startup scripts. The default path is /usr/contrib/Q4.

Q4_STARTUP_SCRIPT

The path of the start up PERL script file. The default path is $HOME/.q4rc.pl.

AUTHOR

kwdb was developed by the Free Software Foundation, Inc.

FILES

$HOME/.kwdbinit

The user's global initialization file which sets the initial debugger state no matter in which directory the debugger is started.

.kwdbinit

The user's local initialization file which sets the initial debugger state when the debugger is started in the directory containing this file. The commands in $HOME/.kwdbinit, if present, are executed first followed by the commands in ./.kwdbinit.

SEE ALSO

gdb(1), wdb(1), ctime(3C).

Debugging with GDB, Getting Started with HP WDB, HP KWDB Kernel Debugger Guide.

COPYRIGHT

Copyright (c) 1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.