Sets a software instruction breakpoint at the specified memory location. Software breakpoints are implemented by writing a special instruction at the break address, and so cannot be set in ROM.


BREAKINSTRUCTION [,qualifier...] expression [=threads,...] [;macro-call]



Is an ordered list of zero or more qualifiers. The possible qualifiers are described in List of qualifiers for the BREAKINSTRUCTION command.


Specifies the address at which the breakpoint is placed. By default, this is the address where program execution stops.


The list of threads that make up the break trigger group.

Only available for OS-aware RSD connections.


Specifies a macro and any parameters it requires. The macro runs when the breakpoint activates and before the instruction at the breakpoint is executed. The macro is treated as being specified last in the qualifier list.

If the macro returns a nonzero value, or you specified continue in the qualifiers, execution continues. If the macro returns zero, or if you do not specify a macro, target execution stops and the debugger waits in command mode.

The macro argument symbols are interpreted when the breakpoint is specified and so they must be in scope at that point, or you must explicitly qualify them.


BREAKINSTRUCTION is used to set or modify software address breakpoints. Software address breakpoints include breakpoints set by patching special instructions into the program and hardware that tests the address and data values. If the command has no arguments, it behaves like DTBREAK on DTBREAK, listing the current breakpoints.

If you try to set a software breakpoint at a location in ROM or Flash, the attempt fails by default. However, if you use the failover qualifier, RealView Debugger attempts to set a hardware breakpoint instead. The attempt fails if insufficient hardware facilities are available.

You can use qualifiers evaluated in the debugger, such as expressions, macros, C++ object tests, and software pass counters. You can also define actions to occur when the breakpoint is triggered (hit), including updating counters or windows, and the enabling or disabling of other breakpoints (see List of qualifiers for the BREAKINSTRUCTION command).

When a software breakpoint instruction is hit on the target, the following sequence of events occurs:

  1. The debugger associates the address with a specific breakpoint ID. A memory address can only be associated with one user breakpoint at a time.

  2. If the breakpoint has a pass count associated with it, the count is updated.

  3. The conditions for this breakpoint, if any, are tested in the order specified on the command line (see Qualifiers that define conditional breakpoints). If any condition is False, target execution resumes with the instruction at the breakpointed location. Macros specified with the macro: qualifier or the ;macro-call argument are run in this phase.

  4. If the breakpoint has actions associated with it (for example, using timed to note the time the breakpoint occurred) these actions are run, in the order specified on the command line (see Qualifiers that define breakpoint actions).

  5. If the qualifiers include continue, target execution resumes with the instruction at the breakpointed location. If not, the debugger updates the state of the GUI and waits for a command, leaving the application halted.

If you are debugging multiprocessor applications, and you have set up synchronization and cross-triggering, then you can specify how each processor is affected when a breakpoint activates.

The breakpoint list index number

RealView Debugger assigns a breakpoint list index number to each breakpoint. This number is assigned consecutively. However, if you delete a breakpoint, then the numbering might no longer be consecutive.

To determine the breakpoint list index of an existing breakpoint:

  1. Start RealView Debugger in GUI mode.

  2. Select View → Break/Tracepoints from the Code window main menu to open the Break/Tracepoint view.

  3. Select the checkbox for the chosen breakpoint to disable it.

  4. Click the Cmd tab in the Output view.

    The breakpoint list index (number) for the breakpoint is shown in the command:

    disable,h number

  5. Select the checkbox for the chosen breakpoint to enable it.

Qualifiers that define conditional breakpoints

To set up a conditional breakpoint, use one or more of the following condition qualifiers:

  • macro (or ;macro-call)

  • obj

  • passcount

  • when

  • when_not.

Qualifiers that define breakpoint actions

To specify actions to be performed when a breakpoint activates, use the following action qualifiers:

  • continue

  • message

  • update.

List of qualifiers for the BREAKINSTRUCTION command

The list of qualifiers is dependent on the processor and Debug Interface, and so the GUI does not present things that do not make sense. The command handler generates an error if a specific combination is invalid for a specific processor or Debug Interface, but this is determined when you issue the command.

The possible qualifiers are:


Instead of creating a new breakpoint, append the qualifiers specified with this command to an existing breakpoint with breakpoint list index number n (see The breakpoint list index number). You cannot change the breakpoint address.


Execution continues when the breakpoint activates and no breakpoint details are displayed. Any specified action qualifiers are still performed, depending on the results of any condition qualifiers.


When you attempt to set a software breakpoint in read-only memory, the default behavior causes the operation to fail. The error message displayed depends on whether or not memory mapping is enabled:

  • Memory mapping enabled:

    Error V004E (Vehicle): Memory map forbids software breakpoint at this address
  • Memory mapping disabled:

    Error V2801C (Vehicle): 0x050b0001: Unable to write sw breakpoint to memory.

However, in some circumstances it might be useful to convert the software breakpoint to a hardware breakpoint. To do this, use the failover qualifier.


When the breakpoint is hit, the specified macro is executed. Any program variables or functions must be in scope at the time the breakpoint request is entered, or the names must be fully qualified. A macro call specified here is treated in the same way as a macro specified after a ;. You must include the braces { and }.

message:{"$windowid | fileid$message"}

Activation of the breakpoint results in message being output. Prefixing message with $windowid | fileid$ enables you to write the message text to a user-defined window or file. For example:

BREAKINSTRUCTION,message:{"$100$this is a message"}

Instead of creating a new breakpoint, modify the breakpoint with breakpoint list index number n (see The breakpoint list index number). The address expression and the qualifiers of the existing breakpoint are replaced by those specified in this command.


This condition is True if the argument n matches the C++ object pointer, normally called this.


Specifies the number of times that the break condition is ignored before the breakpoint activates. The default value is 0. If you specify this in the middle of a sequence of break conditions, those specified before the passcount are processed whether or not the count reaches zero. The conditions specified afterwards are run only when the count reaches zero.


Sets a breakpoint for OS-aware connections, where type is one of:


Sets a Halted System Debug (HSD) breakpoint for debugging your OS-aware image.


Not supported in this release.


Sets a system breakpoint for debugging images running in Running System Debug (RSD) mode.


Sets a thread breakpoint for debugging images running in RSD mode.


Set the size of the breakpoint to either 16 or 32 bits. For example:

BREAKINSTRUCTION,size:32 0x10040

Use this qualifier if no debug information is available for your image. By default, RealView Debugger sets a 32-bit breakpoint.


Update the named windows, or all windows, by reading the memory and processor state when the breakpoint activates. You can use the name all to refresh all windows, or a name specified in the title bar of the window.

This qualifier enables you to get an overview of the process state at a particular point, without having to manually restart the process at each break. The update still takes a significant period of time, and so this method is unsuitable as a non-intrusive debugging tool.


The breakpoint activatesactivates whenever condition, a debugger expression, evaluates to True.


Using a macro as an argument to when, reverses the sense of the return value from the macro.


The breakpoint activates whenever condition, a debugger expression, evaluates to False.

Rules for the BREAKINSTRUCTION command

The following rules apply to the use of the BREAKINSTRUCTION command:

  • Breakpoints are specific to the board, process, or task active in the window at the time they are set.

  • If synchronous breakpoints are set on two or more threads on the same board, the debugger stops the threads as close to the same time as the architecture of the board permits.


The following examples show how to use BREAKINSTRUCTION:


Set a breakpoint at address 0x8000.


Set a breakpoint at line 449, column 22 in the file math.c.


Given an already set breakpoint at position 1 in the breakpoint list, add a request to update all windows in the code window for this connection and continue execution each time the breakpoint activates.


Set a breakpoint using a hardware counter to stop at the fifth time that execution reaches line 49 of main.c.


Set a breakpoint that calls a debugger macro CheckStruct each time it reaches line 33 of main.c. If CheckStruct returns a nonzero value, the debugger continues application execution.

BREAKINSTRUCTION,when:{count<4 || err==5} \MAIN_1\SUBFN_C\#33

Set a breakpoint that activates when the expression count<4 || err==5 is True when execution reaches line 33 of subfn.c.

BREAKINSTRUCTION,when:{check_struct()} \MAIN_1\MAIN_C\#33

Set a breakpoint that calls a target program function check_struct() each time it reaches line 33 of main.c. If this function returns zero, the debugger continues application execution.


Set a HSD breakpoint at line 201 in demo.c.


Set a system breakpoint at line 154 in demo.c.

BREAKINSTRUCTION,rtos:thread \DEMO\#154 = 0x39d8, 0x3a68

Set a thread breakpoint using a break trigger group consisting of two threads, defined by the addresses of the thread control blocks.

BREAKINSTRUCTION,rtos:thread \DEMO\#180 = thread_2, thread_6, thread_8

Set a thread breakpoint using a break trigger group consisting of three threads, defined by the thread names.


Modify breakpoint number 2, a thread breakpoint, to be a system breakpoint.

BREAKINSTRUCTION,modify:3,rtos:thread = 0x1395c, 0x13bac

Modify breakpoint number 3, a thread breakpoint, to specify a different break trigger group, shown in Figure 2.1.

Figure 2.1. Changing the break trigger group

Changing the break trigger group



See also

Copyright © 2002-2011 ARM. All rights reserved.ARM DUI 0175N