RealView® Developer Kit Debugger Command Line Reference GuideVersion 1.0
Home > RealView Debugger Commands > Alphabetical command reference > BREAKEXECUTION

2.2.13. BREAKEXECUTION

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

Syntax

BREAKEXECUTION [{,qualifier...}] expression [={threads,...}] [;macro-call]

where:

qualifier

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

expression

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

threads

Not supported in this release.

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 TRUE (nonzero) value, or you specified continue in the qualifiers, execution continues. If the macro returns a FALSE (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, and enabling or disabling other breakpoints, and starting and stopping other threads.

If supported by an RTOS kernel, these breakpoints can be thread-specific, although usually not for hardware-assisted breaks.

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 fails, target execution resumes with the instruction at the breakpointed location.

  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. Macros specified with macro: are run in this phase.

  5. If there is a macro specified after a semicolon on the command line, this is run.

  6. If the qualifiers included 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.

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 not allowed for a specific processor or vehicle, but this is determined when you issue the command. 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. You cannot change the breakpoint address.

continue

Any triggering of the breakpoint is recorded (for example, as a journal entry, or by the action of a macro) but execution then continues.

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:

be,context:{\HELLO_1\HELLO_C},when:{status>0} #15

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

be,when:{\HELLO_1\HELLO_C\status>0} \HELLO_1\HELLO_C\#15
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.

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:

BE,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:

BE,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:

BE,hw_dvalue:0x440 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:

BE,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-0x4F0:

BE,hw_dvalue:0x440,hw_dmask:0xF0F 0x1FA00
hw_passcount:(n)

Specifies the number of times that the specified condition has to occur to trigger the breakpoint. The default value is 1. 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 supplement the hardware one for higher count values. When both hardware and software pass counts are defined:

  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 tied, 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

  • prev for the last breakpoint specified for this connection.

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.

BE,hw_not:addr 0x10040

This means to break at any address other than 0x10040. This 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.

message:{message}

Triggering of the breakpoint results in message being output. Prefixing message with $n$ enables you to write the message text to custom window n, where n is between 50-1024.

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.

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 specified condition has to occur to trigger the breakpoint. The default value is 1. 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.

timed

Triggering records the time, in whatever units the debug hardware chooses, from the last reset of time. The time can be in nanoseconds, microseconds, 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.

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

Set a hardware breakpoint at line 449, statement 3 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 TRUE, 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 FALSE, the debugger continues application execution.

Alias

BEXECUTION is an alias of BREAKEXECUTION.

See also

The following commands provide similar or related functionality:

Copyright © 2003, 2004 ARM Limited. All rights reserved.ARM DUI 0235B
Non-Confidential
PDF file icon  PDF version
Home > RealView Debugger Commands > Alphabetical command reference > BREAKEXECUTION