bs (SDM)

Sets new software or hardware breakpoints, or displays the current breakpoints. You can set breakpoints in conventional memory or at an I/O address. To display current breakpoints, issue the bs command without any parameters.

bs [address]
bs address e
bs address m b|h|w
bs address w b|h|w
bs address i b|h

Parameters

address

An address for the breakpoint. If you do not follow the address with any other parameters, bs sets a software execution breakpoint.

When you set a breakpoint in conventional memory (either a software breakpoint or a hardware breakpoint using an e, m, or w parameter), you should typically specify a segmented address such as cs:offset. You cannot specify a physical address for conventional memory. You can specify a linear address by entering a hexadecimal value followed by the character l. However, be aware that in a flat-model application using virtual memory, a linear address is not the same as a physical address. In that case, SDM interprets the linear address using the page table mechanism to set the breakpoint at the correct location.

When you set an I/O breakpoint with the i parameter, specify a hexadecimal physical address in the range 0 - 0FFFFH. Do not follow the address with the letter h or l.

e

Execution breakpoint: sets a hardware breakpoint to occur when the instruction at the specified address is ready to be executed. The address must be on an instruction boundary.

m

Modify breakpoint: sets a hardware breakpoint to occur following a read or write at the specified address.

w

Write breakpoint: sets a hardware breakpoint to occur following a write at the specified address.

i

I/O breakpoint: sets a hardware breakpoint to occur following a read or write at the specified port address.

b

Specifies that the breakpoint applies to one byte.

h

Specifies that the breakpoint applies to a halfword (16 bits). The address must be aligned on the appropriate halfword boundary.

w

Specifies that the breakpoint applies to a word (32 bits). The address must be aligned on the appropriate word boundary.

Remarks

A breakpoint is a condition that you set to return control to SDM. When you issue the g command, SDM returns execution to the program you are debugging. If you have breakpoints set in the program, execution continues until the first breakpoint is encountered, then control returns to SDM. At that point you can use SDM commands to examine or change the state of the program (processor registers, memory, etc.).

A software breakpoint is one that SDM manages itself by inserting an Interrupt 3 at a specified address. When you execute code at that address, the interrupt returns control to SDM, which then removes the interrupt and reinserts the original code. You can set up to 32 software breakpoints with the bs command.

A hardware breakpoint is managed by one of the debug registers in the processor. You can set a total of 4 hardware breakpoints, using a combination of the g and bs commands:

Any breakpoints that you enter on the g command line are automatically hardware execution breakpoints. The breakpoints must be set in code to be effective. When the g command executes to the point where the first breakpoint is reached, control returns to SDM. At that point, SDM removes all breakpoints you specified on the g command line, freeing them for further use.
Hardware breakpoints that you set with the bs command can be in code (execution breakpoints), data (modify or write breakpoints), or I/O space (modify breakpoints at a port address). The only way you can clear breakpoints set with the bs command is to use the bc command. This applies to both software and hardware breakpoints.

You can set multiple hardware breakpoints at the same address, or set a software breakpoint at the same address as a hardware breakpoint. However, you cannot set multiple software breakpoints at the same address.

CAUTION: If you intend to set breakpoints in the g command, you must limit the hardware breakpoints set with bs to fewer than four. For example, if you intend to set two breakpoints on the g command line, you can only set two hardware breakpoints with bs. Then when you issue the g command with two breakpoints, the total of four hardware breakpoints is used. The n command with the p option also uses a hardware breakpoint, so you can set a maximum of three hardware breakpoints with bs before issuing an np or npr command.

The breakpoints set with bs remain set until you specifically clear them with bc. Breakpoints set on the g command line are cleared the next time you enter SDM, regardless of how you enter. For example, assume that you set one breakpoint with bs and two others in a g command. It doesn't matter which breakpoint causes the break to SDM; at the next SDM prompt the breakpoint set with bs will still be set, but the two set in the g command will be cleared.

Reason Codes

SDM assigns a number to each breakpoint when the breakpoint is set. This number is called a reason code. Software breakpoints are assigned reason codes 1000H - 101FH. Hardware breakpoints are numbered 200h through 203h. When you set a breakpoint or display breakpoints, the bs command displays the reason code, which is a 32-bit number in hexadecimal format. The bc command displays the same reason code when you clear an individual breakpoint.

No Breaks Available

If all the available breakpoints of one type (hardware or software) are set and you attempt to set another breakpoint of that type, SDM displays the message "No Breaks Available." You must clear a previous breakpoint with the bc command to be able to set a new breakpoint.

Software Breakpoints

You can set as many as 32 software breakpoints. Software breakpoints are execution breakpoints: a break occurs when the code executes to the specified address. The instruction at the address is not executed.

CAUTION: When setting a software breakpoint, make sure the address is the first byte of an instruction, including prefixes. Software breakpoints temporarily replace the byte at the specified address with an interrupt instruction. If the address does not point to an instruction boundary, the substituted instruction never causes a break. Instead, your program contains a byte which is interpreted as an unintended command or data. The result is unpredictable and the program could crash.

Hardware Breakpoints

When you set a hardware breakpoint, the monitor changes the contents of the debug registers in the processor. The registers affected are DR0, DR1, DR2, DR3, and DR7. Register DR6 is set to 0 each time the monitor relinquishes control to your program.

Execution Breakpoints

A break caused by an execution-type breakpoint (parameter e) occurs only when the address on the command line is an instruction to be executed. The break occurs before the instruction is executed.

It is important that you set the address correctly for an execution-type breakpoint. To cause a break on an instruction, the specified address must point to the first byte of the instruction, including any prefixes. If the address does not point to an instruction boundary, the break never occurs.

Data Breakpoints and I/O Access Breakpoints

Breakpoint types modify, write, and I/O (parameters m, w, and i) cause breaks when a location is accessed. These breaks occur immediately after the instruction causing the access. A modify breakpoint causes a break whenever memory at the specified address is written or read, but not when an instruction is fetched from memory. A write breakpoint causes a break only when there is a write at the address. An I/O breakpoint causes a break when an I/O port is read or written.

The modify, write, and I/O breakpoints require that you specify a length parameter following the m, w, or i on the command line. The choices of length parameter are byte, halfword, and word. If you try to set these breakpoints without a length parameter, SDM displays a syntax error message.

The length parameter determines the length of the breakpoint field, which begins at the specified address. A break occurs when a memory access in your program overlaps any part of the breakpoint field. For example, assume that you set a word breakpoint of type m (modify) at address B000H, which defines a four-byte breakpoint field beginning at B000H. A byte read or write of any address B000H through B003H causes a break. Likewise, a word read or write at address B002H causes a break, even though only two of the four bytes overlap the field you defined.

Note: The address on the command line should be a multiple of the specified length parameter (byte, halfword, or word). If you specify a byte, use any address. If you specify a halfword, use an address that is a multiple of two. If you specify a word, use an address that is a multiple of four. If the address is not a multiple of the length parameter, the program may break in unexpected places.

Breakpoint Display

When you issue the bs command without parameters, SDM displays the breakpoints currently set. For each breakpoint the output is:

reason code: The reason code assigned to the breakpoint.
s or h: Indicates a software or hardware breakpoint.
address: The breakpoint address, returned as a linear address.
e, m, w, or i: Execution, modify, write, or I/O (only for hardware breakpoints).
b, h, or w: Byte, halfword, word (only for modify, write, or I/O breakpoints).

Displayed software breakpoints look like this:

00001000 s 00020af0

Displayed hardware breakpoints have two forms, either as below:

00000200 h 0000fffe e

or with a b, h, or w parameter:

00000201 h 000d1240 m h

Examples

Assume that you want your program to break when it reads or writes any memory location from 1FF3h through 1FF7h. Set two hardware breakpoints:

..bs 1ff3 l m b
00000200
..bs 1ff4 l m w
00000201
..

The first breakpoint is a modify breakpoint covering one byte in memory. SDM assigns it reason code 200h. The second breakpoint is a modify breakpoint covering four bytes in memory. SDM assigns it reason code 201h. To display the breakpoints, issue the bs command with no parameters:

..bs
00000200 h 00001ff3 m b
00000201 h 00001ff4 m w
..