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

bl

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

bp schedule
Sets an instruction breakpoint at the begining of the function schedule.

bp schedule+0x12e
Sets an instruction breakpoint at the instruction located at schedule+0x12e.

bph ttybuffer+0x24 dataw
Sets a data write breakpoint at the location referenced by ttybuffer+0x24 for a length of four bytes.

bph 0xc0254010 datar 1
Establishes a data reference breakpoint at address 0xc0254010 for a length of one byte.

bp
List current breakpoint table.

bd 0
Disable breakpoint #0.

bc *
Clear all breakpoints