BP - Set or Alter a Breakpoint

Set or re-specify a software sticky breakpoint. by inserting an INT 3 instruction.

Syntax:

───┬─ BP  ─┬─ addr ──┬───────────────┬─┬───────────────────┬──
     └─ BPn ─┘         └── passcount ──┘ ├─────── cmd ───────┤
                                         └─ " ─── cmd ─┬─ " ─┘
                                                      │
                                               └── ; ──┘

Parameters:

n

Explicitly specifies a breakpoint number to be assigned to this breakpoint. A value from 0 to 9 may be specified. If specified there must be no space between the number and the BP command.

The default is to assign the lowest available number. If all 10 breakpoint numbers have been assigned then the following message appears:

Too many breakpoints

addr
The address of the breakpoint.

The Kernel Debugger saves the byte of storage at the location specified by addr and inserts an INT 3 instruction in its place.

Notes

Whenever the Kernel Debugger is entered the storage overlayed by any breakpoints is temporarily restored. When the Kernel Debugger gives control back to the system, enabled breakpoints are re-instated.

If addr specifies the address of an existing breakpoint then the existing breakpoint is updated with the new parameters.

Each break-point address is recorded with its associated process context. For shared data this is of no consequence. However for private addresses, especially those in the private arena the addr may be qualified by slot number by using the | operator. This acts as a shorthand to save changing contexts using the .S command in order to set the breakpoint correctly. For example, suppose the current slot is 8, then:

      BP 31 | %10032

is equivalent to:

      .S 31
      BP 31 | %10032
      .S 8

passcount
Specifies the number of times the breakpoint may be passed before the Kernel Debugger is entered. Each time the breakpoint is passed the count is decremented by 1 until 1 is reached. When the breakpoint is encountered with a count of 1 then it will fire and the Kernel Debugger will be entered. Thus if passcount is 5 then the breakpoint will fire on the 5th encounter.

The default passcount is 1, that is, the breakpoint will fire on first encounter.

cmd
Specifies a command to be executed when the breakpoint fires. More than one command may be specified by using a semi-colon separator and enclosing the entire command list in single or double quotes.

If no command string is specified then the default command string, as specified by the Z command will be executed.

Results & Notes:

If the specified address is valid then the breakpoint definition is accepted otherwise one of the following messages is generated:

Invalid linear address: %nnnnnnnnInvalid selector: selector:offset
Past end of segment selector:offset

If the break-point is successfully defined then the in-built mnemonic BRn, where n corresponds to the break-point number, takes the value of the break-point address. This may be used in any address expression or any command.

Note:

Since BP break-points are implemented by the insertion of INT 3 instructions, it is possible for such break-points to become discarded if the page of code is discarded and subsequently paged back into memory.

If the .I command is used to swap in a page of code, then the break-points are automatically restored. (In earlier versions of OS/2 it was necessary to specify the B option of .I).

This complexity may be avoided by setting register break-points with the BR command.

---

[Back: BL - List Breakpoints]
[Next: BR - Set or Alter a Debug Register Breakpoint]