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

2.3.18. BREAKWRITE

Sets a hardware breakpoint that activates when a write operation is performed on any of the specified memory locations.

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 for the BREAKWRITE command.

address | address-range

Specifies a single address or an address range in target memory. The address can also be a memory mapped register (see Memory mapped registers).

macro-call

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

Description

BREAKWRITE is used to set or modify data write breakpoints. Data write breakpoints activate 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, 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 (see Qualifiers that define hardware tests).

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 activates, including updating counters or windows, and the enabling or disabling of other breakpoints (see List of qualifiers for the BREAKWRITE command).

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 hit 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 (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.

Memory mapped registers

You can set a breakpoint that activates on a write to a memory-mapped register. To specify a memory mapped register, enter the following expression for the address:

register:expression

The register is identified by expression. For example:

BREAKWRITE register:PR1

or

BREAKWRITE register:@PR1

Note

You can only specify memory mapped registers that are defined in Board/Chip Definition (.bcd) files that you have assigned to a Debug Configuration. You cannot set breakpoints on core registers.

Combining hardware and software pass counts

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 pass count reaches zero, the software pass count is decremented. What happens next depends on your hardware:

    • For RVISS, the hardware count remains at zero, so that

      total count = hw_passcount + passcount

    • Other processors might exhibit the RVISS behavior, or might reset the hardware pass count to the initial value, so that:

      total count = (hw_passcount +1) * passcount + hw_passcount

  2. When the software pass count reaches zero, the breakpoint activates and the activation count is incremented. The following example shows the counts for the breakpoint bexec,hw_pass:3,pass:50 \DHRY_1\#70:0 on an RVISS target:

    • Initial state:

      > dtbreak
S ID    Type            Address         Count   Miscellaneous
- --    ----            -------         -----   -------------
  1     Exec            0x00008480      0       Pass=50

    • State after activation:

      > dtbreak
S ID    Type            Address         Count   Miscellaneous
- --    ----            -------         -----   -------------
  1     Exec            0x00008480      1       Pass=0

    If the breakpoint is in a loop, then activation occurs on hit 53.

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 Break/Tracepoints from the View menu to display 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.

Qualifiers that define hardware tests

To specify hardware tests for data write breakpoints, use the following qualifiers:

  • data_only

  • hw_ahigh

  • hw_amask

  • hw_and

  • hw_dhigh

  • hw_dmask

  • hw_dvalue

  • hw_in

  • hw_not

  • hw_passcount.

List of qualifiers for the BREAKWRITE command

The list of qualifiers depends 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:

append:(n)

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

Note

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

continue

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.

data_only

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

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 activates for any address between 0x1000-0x1200:

BREAKWRITE,hw_ahigh:0x1200 0x1000

This is equivalent to the command:

BREAKWRITE 0x1000..0x1200
hw_amask:(n)

Specifies the address mask value for an address-range breakpoint. The address range is determined by masking lower order bits out of the specified address.

This facility is supported by ARM EmbeddedICE macrocells.

For example, to set a breakpoint that activates when any address in the range 0x1FA00-0x1FA0F is accessed, enter the command:

BREAKWRITE,hw_amask:0xFFFF0 0x1FA00

This is equivalent to the command:

BREAKWRITE 0x1FA00..0x1FA0F
hw_and:{id | "then-id"}

Perform an and or an and-then conjunction with another breakpoint, to create a chain of breakpoints. The parentheses are optional. Each breakpoint in the chain is called a breakpoint unit.You specify the breakpoint units in the reverse order that RealView Debugger processes them. The position of the breakpoint unit in the chain is identified by id, which is one of the following:

next

Indicates that this breakpoint unit is to be linked to another breakpoint unit specified for this connection. You must set a breakpoint unit with the ID next before you set any other breakpoint units for the chain. When used with then-, this breakpoint unit is the last one processed in the chain.

prev

Indicates that this breakpoint unit is to be linked to an existing breakpoint unit specified for this connection. Make sure the existing breakpoint has been set with a next, prev, or index_number ID, and is a hardware breakpoint.

Note

When using the prev ID, you must finish defining the complete breakpoint chain before you create any non-chained breakpoints.

index_number

The breakpoint list index number of an existing breakpoint unit (see The breakpoint list index number). Make sure the existing breakpoint has been set with a next, prev, or index_number ID, and is a hardware breakpoint.

How RealView Debugger processes the breakpoint units depends on the conjunction you have used:

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

    For example:

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

  • In the and-then form, RealView Debugger examines the breakpoint units starting with the last one you specified. When the condition for the last breakpoint unit (breakpoint unit N) is met, the associated actions are performed and the previous breakpoint is enabled (breakpoint unit N-1). RealView Debugger continues processing all remaining breakpoints in the chain, until the condition in the first one you specified is met (breakpoint unit 1). At this point, unless the continue qualifier is specified in that breakpoint, execution stops.

    Note

    You must include the quotes when using the and-then form.

    For example, you might have three breakpoint units in a chain, which you specify in the following order:

    BREAKWRITE,hw_and:"then-next",continue 0x10014 (BPU1)

    BREAKWRITE,hw_and:"then-prev" 0x10018 (BPU2)

    BREAKWRITE,hw_and:"then-prev" 0x1001B (BPU3)

    In this case, RealView Debugger first checks for a data write at address 0x1001B (BPU3), then at address 0x10018 (BPU2), and finally at adress 0x10014 (BPU1). When all conditions are met, processing continues as instructed by the first breakpoint in the chain.

If you clear BPU1, then all breakpoints in the chain are cleared.

If you clear any other breakpoint unit, then that breakpoint unit and the following ones are cleared. The previous breakpoint units remain set. For example, clearing BPU2, clears both BPU2 and BPU3, but not BPU1.

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 activates for any data value between 0x00-0x18:

BREAKWRITE,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)

Specifies the data value mask for a data-range breakpoint. The data value to which the mask is applied is specified by the hw_dvalue qualifier. The data value range is determined by masking lower order bits out of the specified data value.

This facility is supported by ARM EmbeddedICE macrocells.

For example, to set a breakpoint that activates when a data value in the range 0x400-0x4FF is accessed at address 0x1FA00, enter the command:

BREAKWRITE,hw_dvalue:0x400,hw_dmask:0xF00 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 activates for the data value 0x400:

BREAKWRITE,hw_dvalue:0x400 0x1FA00
hw_in:{s}

Input trigger tests. The string that follows matches hardware-supported input tests as a list of names or a value. The available tests depends on the Debug Interface and the target processor.

Table 2.20 shows the possible strings for an ARM940T processor.

Table 2.20. Example hw_in test strings for an ARM940T

Input test stringMeaning
No "Ext=level" stringIgnore external trigger level
Ext=0x00000001Low
Ext=0x00000002High
No "Mode=mode" stringAny mode
Mode=0x00000004Privileged
Mode=0x00000008User
No "AccessSize=size" stringDefault access size
AccessSize=0x000001008-bit
AccessSize=0x0000020016-bit
AccessSize=0x0000030032-bit
AccessSize=0x000004008/16-bit
AccessSize=0x000005008/32-bit

For example, you might have a connection to an ARM940T processor through the RealView ICE Debug Interface. For this processor, to test for a low external trigger level and a 32-bit data write in User mode to address 0x10014, enter:

BREAKWRITE,hw_in:"Ext=0x00000002",hw_in:"Mode=0x00000008",hw_in:"AccessSize=0x00000300" 0x10014

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.

hw_out:{s}

Not supported in this release.

hw_passcount:(n)

Specifies the number of times that the break condition is ignored before the breakpoint activates. 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 the hardware and software pass counts to achieve higher count values. However, the behavior depends on your processor (see Combining hardware and software pass counts).

macro:{MacroCall(arg1,arg2)}

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

BREAKWRITE,message:{"$100$this is a message"}
modify:(n)

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.

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 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 pass count 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 pass count qualifier available, hw_passcount, for debug hardware that supports it. You can combine the hardware and software pass counts to achieve higher count values. However, the behavior depends on your processor (see Combining hardware and software pass counts).

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.

update:{"name"}

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.

when:{condition}

The breakpoint activates 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 activates 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.

BREAKWRITE 0x1100..0x1200

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

BREAKWRITE 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

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