man bph (1): breakpoint commands

Other Alias

bp, bpa, bpha, bd, bc, be, bl

SYNOPSIS

bp address-expression

bpa address-expression

bph address-expression [DATAR|DATAW|DATAA|IO [length]]

bpha address-expression [DATAR|DATAW|DATAA|IO [length]]

bd breakpoint-number

bc breakpoint-number

be breakpoint-number

DESCRIPTION

The bp family of commands are used to establish a breakpoint. The address-expression may be a numeric value (decimal or hexidecimal), a symbol name, a register name preceeded by a percent symbol '%', or a simple expression consisting of a symbol name, an addition or subtraction character and a numeric value (decimal or hexidecimal).

bph and bpha will force the use of a hardware register, provided the processor architecture supports them.

The address-expression may also consist of a single asterisk '*' symbol which indicates that the command should operate on all existing breakpoints (valid only for bc, bd and be).

Four different types of breakpoints may be set:

Instruction: Causes the kernel debugger to be invoked from the debug exception path when an instruction is fetched from the specified address. This is the default if no other type of breakpoint is requested or when the bp command is used.
DATAR: Causes the kernel debugger to be entered when data of length length is read from or written to the specified address. This type of breakpoint must use a processor debug register which places an architecture dependent limit on the number of data and I/O breakpoints that may be established. On arm mode XScale platform (thumb mode is not supported yet), debugger is triggered by reading from the specified address. The bph or bpha commands must be used.
DATAW: Enters the kernel debugger when data of length length is written to the specified address. length defaults to four bytes if it is not explicitly specified. Note that the processor may have already overwritten the prior data at the breakpoint location before the kernel debugger is invoked. The prior data should be saved before establishing the breakpoint, if required. On arm mode XScale platform, the debugger is triggered after having overwritten the specified address. The bph or bpha commands must be used.
IO: Enters the kernel debugger when an in or out instruction targets the specified I/O address. The bph or bpha commands must be used. This type of breakpoint is not valid in arm mode XScale platform. This option is not valid in arm mode XScale platform.
DATAA: Enters the kernel debugger after the data in specified address has been accessed (read or write), this option is only used in arm mode XScale platform.

The bpha command will establish a breakpoint on all processors in an SMP system. This command is not available in an uniprocessor kernel.

The bd command will disable a breakpoint without removing it from the kernel debugger's breakpoint table. This can be used to keep breakpoints in the table without exceeding the architecture limit on breakpoint registers. A breakpoint-number of * will disable all break points.

The be command will re-enable a disabled breakpoint. A breakpoint-number of * will enable all break points.

The bc command will clear a breakpoint from the breakpoint table. A breakpoint-number of * will clear all break points.

The bl command will list the existing set of breakpoints.

LIMITATIONS

There is a compile time limit of sixteen entries in the breakpoint table at any one time.

There are architecture dependent limits on the number of hardware breakpoints that can be set.

ix86: Four.
xscale: Two for insruction breakpoints and another two for data breakpoint.
ia64: ?
sparc64: None. When issuing the "go" command after entering the debugger due to a breakpoint, kdb will silently perform a single step in order to reapply the breakpoint. The sparc64 port has some limitations on single stepping, which may limit where a breakpoint may be safely set. Please read the man page for ss for more information.

ENVIRONMENT

The breakpoint subsystem does not currently use any environment variables.

SMP CONSIDERATIONS

Using bc is risky on SMP systems. If you clear a breakpoint when another cpu has hit that breakpoint but has not been processed then it may not be recognised as a kdb breakpoint, usually resulting in incorrect program counters and kernel panics. It is safer to disable the breakpoint with bd, then go to let any other processors that are waiting on the breakpoint to clear. After all processors are clear of the disabled breakpoint then it is safe to clear it using bc.

Breakpoints which use the processor breakpoint registers are only established on the processor which is currently active. If you wish breakpoints to be universal use the bpa or bpha commands.

EXAMPLES