BD(1)

NAME
bp, bpa, bph, bpha, bd, bc, be, bl - breakpoint commands

SYNOPSIS
bp address-expression

bpa address-expression

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

bpha address-expression [DATAR|DATAW|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. 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. 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.

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.

The be command will re-enable a disabled breakpoint.

The bc command will clear a breakpoint from the breakpoint table.

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.
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