RealView® Debugger Command Line Reference GuideVersion 1.8
Home > RealView Debugger Commands > Alphabetical command reference > BREAKEXECUTION

2.3.16. BREAKEXECUTION

The BREAKEXECUTION command sets an execution breakpoint that enables ROM-based breakpoints by using the hardware breakpoint facilities of the target.

See the chapter that describes working with breakpoints RealView Debugger v1.8 User Guide for full details on the use of breakpoints in RealView Debugger.

Syntax

BREAKEXECUTION [,qualifier...] expression [;macro-call]

where:

qualifier

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

expression

Specifies the address at which the breakpoint is placed. For an unqualified breakpoint, this is the address at which program execution is stopped.

macro-call

Specifies a macro and any parameters it requires. The macro runs when the breakpoint is triggered 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 a zero value, 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.

Description

This command is used to set or modify instruction address breakpoints. 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.

Hardware address breakpoints can use other hardware tests in association with the address test, such as trigger inputs and outputs, hardware pass counters, and and-then, or chained, tests.

All breakpoints can add on-host qualifiers, for example expressions, macros, C++ object tests, and pass counters. All address breakpoints can include on-host actions including counters, timing (with hardware assist), update of specified windows, enabling or disabling other breakpoints, and starting and stopping other processors or threads (see List of qualifiers).

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

  1. The debugger or the hardware associates the event with a specific debugger breakpoint ID.

  2. If the breakpoint has a software 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. 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.

  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 triggers. For full details, see the chapter that describes working with multiple targets in the RealView Debugger v1.8 Extensions User Guide.

List of qualifiers

The list of qualifiers is dependent on the processor and vehicle 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 vehicle, but this is determined when you issue the command.

To set up a conditional breakpoint, use the following condition qualifiers:

  • macro (or ;macro-call)

  • obj

  • passcount

  • when

  • when_not.

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

  • continue

  • message

  • sample (not supported in this release)

  • timed

  • update.

The possible qualifiers are:

append:(n)

Instead of creating a new breakpoint, append the qualifiers specified with this command to an existing breakpoint with breakpoint ID number n.

Note

You cannot use append to change the breakpoint address or to create chained breakpoints.

continue

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

context:{context}

Sets the context for other expressions in this breakpoint command to the value of context. This provides an alternative to specifying the complete context for every symbol. For example:


BREAKEXECUTION,context:{DHRY_1},when:{Int_1_Loc>0} #152

This causes a breakpoint to be set at line 15 of dhry_1.c that is triggered only when the variable status defined in dhry_1.c is greater than zero. The alternative form is:


BREAKEXECUTION,when:{Int_1_Loc>0} \DHRY_1\#152

Note

When using this alternative form of the command, the filename DHRY_1 must be uppercase.

data_only

The breakpoint is triggered if a data value, specified using hw_dvalue, is detected by the debug hardware on the processor data bus.

gui

If an error occurs when executing the command or when the breakpoint is triggered, the GUI is used to report it. Otherwise, the error is reported to the command pane.

Note

This qualifier has no effect in the headless debugger.

hw_ahigh:(n)

Specifies the high address for an address-range breakpoint. The low address is specified by the standard breakpoint address.

This facility is not supported by ARM EmbeddedICE macrocells. For example, this command sets a breakpoint that triggers for any address between 0x1000-0x1200:


BREAKEXECUTION,hw_ahigh:0x1200 0x1000

hw_amask:(n)

Specifies the address mask value for an address-range breakpoint. Addresses that match the standard breakpoint address when masked with this value cause the breakpoint to trigger.

This facility is supported by ARM EmbeddedICE macrocells. For example, this command sets a breakpoint that triggers for any address between 0x1FA00-0x1FA0F:


BREAKEXECUTION,hw_amask:0xFFFF0 0x1FA00

hw_dvalue:(n)

Specifies a data value to be compared to values transmitted on the processor data bus.

This facility is supported by ARM EmbeddedICE macrocells. For example, this command sets a breakpoint that triggers for the data value 0x400:


BREAKEXECUTION,hw_dvalue:0x400 0x1FA00

hw_dhigh:(n)

Specifies the high data value for a data-range breakpoint. The low data value is specified by the hw_dvalue qualifier.

This facility is not supported by ARM EmbeddedICE macrocells. For example, this command sets a breakpoint that triggers for any data value between 0x00-0x18:


BREAKEXECUTION,hw_dvalue:0x0,hw_dhigh:0x18 0x1000

hw_dmask:(n)

Specifies the data value mask value for a data-range breakpoint. Data values that match the value specified by the hw_dvalue qualifier when masked with this value cause the breakpoint to trigger.

This facility is supported by ARM EmbeddedICE macrocells. For example, this command sets a breakpoint that triggers for any data value between 0x400-0x4FF:


BREAKEXECUTION,hw_dvalue:0x400,hw_dmask:0xF00 0x1FA00

hw_passcount:(n)

Specifies the number of times that the break condition is ignored before it is triggered. The default value is 0. This qualifier differs from passcount only in that it is implemented in hardware. n is limited to a 32-bit value by the debugger, but might be much more limited by the target hardware, for example to 8 or 16 bits.

You can combine hardware and software pass counts to achieve higher count values. If you define both hardware and software pass counts:

  1. when the hardware count reaches zero, the software count is decremented

  2. when the software count reaches zero, the breakpoint triggers.

hw_and:{[then-]id}

Perform an and or an and-then conjunction with an existing breakpoint. For example, hw_and:{2}, or hw_and:{then-2}, where 2 is the breakpoint id of another breakpoint.

In the and form, the conditions associated with both breakpoints are chained together, so that the action associated with the second breakpoint are performed only when both conditions simultaneously match.

In the and-then form, when the condition for the first breakpoint is met, the second breakpoint is enabled but the program is not yet stopped. When the second breakpoint condition is matched, the actions associated are performed. At this point, unless the continue qualifier is specified in the second breakpoint, the program stops.

The id is one of:

  • the breakpoint list index of an existing breakpoint

  • next for the next breakpoint specified for this connection

  • prev for the last breakpoint specified for this connection.

When a breakpoint is set with hw_and:next, and another is set with hw_and:prev, these two breakpoints are chained. For example:


BREAKEXECUTION,hw_and:next,hw_dvalue:1
    @copyfns\\COPYFNS\mycpy\append
BREAKEXECUTION,hw_and:prev @copyfns\\COPYFNS\mycpy\

If you clear the breakpoint that has the ID next, then both breakpoints are cleared.

If you clear the breakpoint that has the ID prev, then only that breakpoint is cleared.

Debugger internal handle numbers are not available to users to identify breakpoints.

hw_in:{}

In trigger tests. The string that follows matches hardware-supported input tests, per vehicle and processor, as a list of names or a value.

hw_out:{s}

Not supported in this release.

hw_not:{s}

Use this qualifier to invert the sense of an address, data, or hw_and term specified in the same command. The argument s can be set to:

addr

Invert the breakpoint address value.

data

Invert the breakpoint value.

then

Invert an associated hw_and:{then} condition.

For example, to break when a data value does not match a mask, you can write:


BREAKEXECUTION,hw_not:data,hw_dmask:0x00FF ...

The break commands require an address value, and the addr variant of hw_not uses this address.


BREAKEXECUTION,hw_not:addr 0x10040

This means to break at any address other than 0x10040. This example is probably not useful.

The hw_not:then variant of the command is used in conjunction with hw_and to form nand and nand-then conditions.

This facility is not supported by ARM EmbeddedICE macrocells.

macro:{MacroCall(arg1,arg2)}

The triggering of the breakpoint results in the specified macro being 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. You must include the braces { and }.

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

Triggering 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. See Window and file numbers for details. For example:


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

modify:(n)

Instead of creating a new breakpoint, modify the breakpoint with breakpoint ID number n by replacing the address expression and the qualifiers of the existing breakpoint to those specified in this command.

Note

You cannot use this qualifier with the hw_and qualifier to change a non-chained breakpoint to a chained breakpoint. However, you can modify a chained breakpoint with any other qualifier and also change the address expression.

obj:(n)

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

passcount:(n)

Specifies the number of times that the break condition is ignored before it is triggered. 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.

There is a hardware passcount qualifier available, hw_passcount, for debug hardware that supports it.

Note

If a breakpoint uses a passcount, the counting is performed on the host, and so program execution stops briefly every time the breakpoint is hit, even when the count has not been reached.

sample

Not supported in this release.

size:n

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


BREAKEXECUTION,size:32 0x10040

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

timed

Triggering records the time, in whatever units the debug hardware chooses, from the last reset of time. The time can be in nano- seconds, micro-seconds, processor cycles, instructions, or units. See the documentation for the hardware interface for more information.

The recorded times are displayed in the Resource Viewer window and in the breakpoint information for this breakpoint.

The timed qualifier can be used for simple profiling, or for a measure of specific response times. If you use timed and continue, the debugger keeps a log of times for each break.

update:{"name"}

Update the named windows, or all windows, by reading the memory and processor state when the breakpoint triggers. 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.

when:{condition}

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

Note

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

when_not:{condition}

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

Examples

The following examples show how to use BREAKEXECUTION:

BREAKEXECUTION \MATH_1\#449:22

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

BREAKE,append:(1),continue,update:{all}

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

BE,hw_pass:(5) \MAIN_1\#49

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

BE \MAIN_1\MAIN_C\#33 ;CheckStruct()

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

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

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

Alias

BEXECUTION is an alias of BREAKEXECUTION.

See also

The following commands provide similar or related functionality:

Copyright © 2002-2005 ARM Limited. All rights reserved.ARM DUI 0175G
Non-Confidential
PDF file icon  PDF version
Home > RealView Debugger Commands > Alphabetical command reference > BREAKEXECUTION