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

2.3.19. BREAKWRITE

The BREAKWRITE command sets a hardware breakpoint that triggers when a write operation is performed on any of the specified memory locations.

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

BREAKWRITE [,qualifier...] {address | address_range} [; macro_call]

where:

qualifier

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

address | address_range

Specifies a single address in target memory, or an address range. See Specifying address ranges for details on how to specify an address range.

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

BREAKWRITE is used to set or modify data write breakpoints. Data write breakpoints trigger when data that matches a condition is written to memory at a particular address or address range. If the command has no arguments, it behaves like DTBREAK on DTBREAK, listing the current breakpoints.

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

If you do not specify an address, the write breakpoint is set at the address defined by the current value of the PC. The breakpoint is triggered if the target program writes data to any part of the specified target memory area.

When a hardware data write breakpoint 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:


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

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:


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


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


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


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


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


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


BREAKWRITE,hw_and:next,hw_dvalue:1
    @copyfns\\COPYFNS\mycpy\append
BREAKWRITE,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:


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

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


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


BREAKWRITE,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 hardware 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.

register:expression

The breakpoint is triggered if a value is written to the specified memory-mapped register. The register is identified by expression. For example:


BREAKWRITE,register:PR1

or


BREAKWRITE,register:@PR1

Note

You can only specify registers that are defined in a Board/Chip Definition (.bcd) file, which you must have assigned to the connection.

sample

Not supported in this release.

size:n

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


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

BREAKWRITE 0x8000

Stop program execution if the program writes to location 0x8000.

BREAKW 0x1100..0x1200

Stop program execution if the program writes to the 257 bytes from 0x1100-0x1200 (inclusive).

BWRITE 0x1100..0x1200 ; CheckMem(0x100)

Stop program execution if the program writes to the 257 bytes from 0x1100-0x1200 (inclusive) and calls the macro CheckMem with the base address 0x100.

Alias

BWRITE is an alias of BREAKWRITE.

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 > BREAKWRITE