kdb_bt(3)

NAME

bt - Stack Traceback command

SYNOPSIS

bt [ <stack-frame-address> ]

btp <pid>

bta

DESCRIPTION

The bt command is used to print a stack traceback. It uses the current registers (see rd command) to determine the starting context and attempts to provide a complete stack traceback for the active thread. If stack-frame-address is supplied, it is assumed to point to the start of a valid stack frame and the stack will be traced back from that point (e.g. on i386 architecture, stack-frame-address should be the stack address of a saved %eip value from a call instruction. on sparc64 architecture, it should be a pointer to a saved register window, as is found in the %fp register).

If present, a kernel configuration option CONFIG_FRAME_POINTER should be enabled so that the compiler will utilize the frame pointer register properly to maintain a stack which can be correctly analyzed. Some architectures (e.g. sparc64) always use CONFIG_FRAME_POINTER, and so the option is not present.

The bt command will attempt to analyze the stack without frame pointers if the CONFIG_FRAME_POINTER option is not enabled, but the analysis is difficult and may not produce accurate nor complete results.

The btp command will analyze the stack for the given process identification (see the ps command).

The bta command lists the stack for all processes.

For each function, the stack trace prints at least two lines. The first line contains four or five fields :-

*

The pointer to the previous stack frame, blank if there is no valid frame pointer.

*

The current address within this frame.

*

The address converted to a function name (actually the first non-local label which is <= the address).

*

The offset of the address within the function.

*

Any parameters to the function.

On the next line there are five fields which are designed to make it easier to match the trace against the kernel code :-

*

The module name that contains the address, "kernel" if it is in the base kernel.

*

The section name that contains the address.

*

The start address of the section.

*

The start address of the function.

*

The end address of the function (the first non-local label which is > the address).

If arguments are being converted to symbols, any argument which converts to a kernel or module address is printed as :-

*

Argument address.

*

The module name that contains the address, "kernel" if it is in the base kernel.

*

The symbol name the argument maps to.

*

The offset of the argument from the symbol, suppressed if 0.

MATCHING TRACE TO KERNEL CODE

The command "objdump -S" will disassemble an object and, if the code was compiled with debugging (gcc flag -g), objdump will interleave the C source lines with the generated object.

A complete objdump of the kernel or a module is too big, normally you only want specific functions. By default objdump will only print the .text section but Linux uses other section names for executable code. When objdump prints relocatable objects (modules) it uses an offset of 0 which is awkward to relate to the stack trace. The five fields which are printed for each function are designed to make it easier to match the stack trace against the kernel code using "objdump -S".

If the function is in the kernel then you need the section name, the start and end address of the function. The command is

  objdump -S -j <section_name> \
          --start-address=<start-address> \
          --stop-address=<end-address> \
          /usr/src/linux/vmlinux

If the function is in a module then you need the section name, the start address of the section, the start and end address of the function, the module name. The command is

  objdump -S -j <section_name> \
          --adjust-vma=<section-start> \
          --start-address=<start-address> \
          --stop-address=<end-address> \
          /path/to/module/<module-name>.o

All addresses to objdump must be preceded by '0x' if they are in hex, objdump does not assume hex. The stack trace values are printed with leading '0x' to make it easy to run objdump.

LIMITATIONS

If the kernel is compiled without frame pointers, stack tracebacks may be incomplete. The mds %esp (i386) or mds %fp (sparc64) command may be useful in attemping to determine the actual stack traceback manually.

A stack trace can be misleading if any code in a function exit has been executed, the stack is partially unwound at that stage.

The bt command may print more arguments for a function than that function accepts; For sparc64, this will always happen as the debugger cannot determine the correct number. For i386, this happens when the C compiler doesn't immediately pop the arguments off the stack upon return from a called function. When this is this case, these extra stack words will be considered additional arguments by the bt command.

ENVIRONMENT

The BTARGS environment variable governs the maximum number of arguments that are printed for any single function.

If the BTSYMARG environment variable is non-zero then any arguments that fall within the kernel are converted to symbols.

If the NOSECT environment variable is non-zero then the section information is suppressed.

The BTAPROMPT environment variable controls the prompt after each process is listed by the bta command. If BTAPROMPT is not set or is non-zero then bta issues a prompt after each process is listed. If BTAPROMPT is set to zero then no prompt is issued and all processes are listed without human intervention.

SMP CONSIDERATIONS

None.

EXAMPLES

Entering kdb (0xc3cb4000) due to Breakpoint @ 0xc011725d
Instruction(i) breakpoint #0 at 0xc011725c
qm_modules+0xd1:   movl   %ebp,%esp
kdb> bt
    EBP       EIP         Function(args)
0xc3cb5f98 0xc011725d  qm_modules+0xd1 (0x80721c0, 0x100, 0xbfff5000)
                       kernel .text 0xc0100000 0xc011718c 0xc0117264
0xc3cb5fbc 0xc0117875  sys_query_module+0x1b1 (0x0, 0x1, 0x80721c0, 0x100, 0xbfff5000)
                       kernel .text 0xc0100000 0xc01176c4 0xc01178e8
           0xc01095f8  system_call+0x34
                       kernel .text 0xc0100000 0xc01095c4 0xc01095fc