RealView® Debugger Command Line Reference GuideVersion 3.0
Home > RealView Debugger Commands > Alphabetical command reference > TRACEBUFFER

2.3.133. TRACEBUFFER

The TRACEBUFFER command manipulates the contents and display of the program execution trace buffer.

Syntax

TRACEBUFFER ,subcommand [,qualifier] ="text"

TRACEBUFFER ,subcommand =value

TRACEBUFFER ,subcommand

where:

subcommand

The possible commands are described in Description.

qualifier

The possible qualifiers are described in Description.

text

The name of a file or program symbol.

value

A numeric value or range, for example 4 or 5..8.

Description

The TRACEBUFFER command manipulates the program execution and data trace buffer associated with a trace analyzer, enabling you to save, load, find, and filter the data. The actions are differentiated using the subcommand, and are described in the section Subcommands.

Trace operation is described in detail in the RealView Debugger v3.0 Trace User Guide.

Subcommands

The possible subcommands listed in the syntax are described in the following sections:

Loadfile

TRACEBUFFER ,loadfile ="filename"

Load a file into the trace buffer for extra analysis. filename is the name of the file to load, and must be quoted.

You can include one of more environment variables in the filename. For example, if MYPATH defines the location C:\Myfiles, you can specify:


TRACEBUFFER,loadfile '$MYPATH\mytrace.dat'

Note

The file must have been saved using the savefile subcommand with the qualifier full, minimal, or profile, or the GUI equivalent.

Savefile

TRACEBUFFER ,savefile [ ,ascii | ,full | ,minimal | ,profile] [,append] [,filtered] ="filename"

Save the trace buffer to a file, where:

ascii

Save lines of text as displayed in the current tab of the Analysis window. This format cannot be loaded into the RealView Debugger analysis window.

full

Save the whole trace buffer as a binary file in an RealView Debugger internal format.

minimal

Save only timing, address, and access type data from the trace buffer as a binary file in a RealView Debugger internal format. The files created are much smaller than the full format, but some information is lost.

profile

Save only execution profile data from the trace buffer as a binary file in a RealView Debugger internal format. The files created are smaller than the minimal format, but only include enough information to display execution profiles.

append

Append the new trace data to an existing file. Do not append data in one format to files in a different format.

filtered

Apply the selected display filters when saving trace data. If not specified, the entire trace buffer is saved, regardless of selected display filters.

filename

The name of the file to write the data to. If the full argument is specified, the filename extension is ignored. If the full argument is not specified, then the filename must use a known extension (.trc, .trm, .trp, or .txt).

You can include one of more environment variables in the filename. For example, if MYPATH defines the location C:\Myfiles, you can specify:


TRACEBUFFER,savefile '$MYPATH\mytrace.dat'

Closefile

TRACEBUFFER ,closefile

Unload the data from the last file loaded with loadfile and clear the Analysis window.

Amount

TRACEBUFFER ,amount =size

This subcommand is deprecated. Specify the number of captured trace records to read from the trace buffer. There is a default value that normally corresponds to the entire trace buffer. Set this if you do not require analysis of all of the captured trace buffer.

The value of size is one of:

0

The default buffer size. Normally this is the whole buffer, but see your analyzer documentation for full details.

n

The maximum number of records to read.

n..m

The range of records to read, with 0 being the trigger record, if any, and the start of the buffer point if not triggered. If you have a trigger record, you can use negative values to reference records before the trigger.

For example, if a trigger is specified then 10..200 means read 190 records starting 10 records after the analyzer triggered.

If no trigger is specified, the same string, 10..200, means to read the 190 records starting 10 records into the buffer.

To read the records around the trigger position in the buffer, you can specify -20..20.

Scaletime

TRACEBUFFER ,scaletime =scale

Set the units for time values displayed in the Analysis window, where scale is:

0

The default units

1

Picoseconds (10-12 seconds)

2

Nanoseconds (10-9 seconds)

3

Microseconds (10-6 seconds)

4

Milliseconds (10-3 seconds)

5

Seconds

6

Cycles.

For ARM ETM, the default units are nanoseconds, and you cannot use scale 6, cycles.

Speed

TRACEBUFFER ,speed =mhz

Set the speed of the target processor clock for use in cycle-to-time conversions, where mhz is the clock frequency in MHz. The default value is 20MHz. For example:


TRACEBUFFER,speed=40

sets the speed to 40MHz, so that a period of 400 cycles is considered to take 400/40E6 seconds, or 10 microseconds.

Find_trigger

TRACEBUFFER ,find_trigger

Searches for the trigger position in the trace buffer. If found, the item is selected and the Analysis window display is centered on it. There are no arguments.

Find_position

TRACEBUFFER ,find_position =position

Searches for the indicated position or set of positions in the trace buffer, where position is an integer or range:

n

The position to find.

n..m

Find the first in a range of positions from n to m inclusive.

n..+o

Find the first in a range of positions from n to n+o inclusive.

The values n and m can be negative if a trigger is defined. If any of the positions is found, the first is selected and the Analysis window display is centered on it.

Find_time

TRACEBUFFER ,find_time =time

Searches for the indicated time or range of times in the trace buffer, where time is an integer or range:

n

The time to find.

n..m

Find the first in a range of times from n to m inclusive.

n..+o

Find the first in a range of times from n to n+o inclusive.

The values n and m can be negative if a trigger is defined. If any of the times are found, the first is selected and the Analysis window display is centered on it.

Find_address

TRACEBUFFER ,find_address =address

Searches for the indicated address or set of positions in the trace buffer, where address is an integer or range:

n

The address to find.

n..m

Find the first in a range of addresses from n to m inclusive.

n..+o

Find the first in a range of addresses from n to n+o inclusive.

If any of the addresses are found, the first is selected and the Analysis window display is centered on it.

Find_data

TRACEBUFFER ,find_data =dbval

Searches for the indicated data bus value or set of values in the trace buffer, where dbval is an integer or range:

n

The data bus value to find.

n..m

Find the first in a range of data bus values from n to m inclusive.

n..+o

Find the first in a range of data bus values from n to n+o inclusive.

The values n and m can be negative. If any of the values are found, the first is selected and the Analysis window display is centered on it.

Find_name

TRACEBUFFER ,find_name ="text"

Searches for the supplied text. The search is based on a textual search of the information in the Symbolic column of the analysis window. If found, the record is selected and the Analysis window display is centered on it.

Posfilter

TRACEBUFFER ,posfilter =position

Restricts the trace buffer information displayed in the Analysis window based on a positions or set of positions, where position is an integer or range:

n

The position to display.

n..m

Display the range of positions from n to m inclusive. n can be negative.

n..+o

Display the range of positions from n to n+o inclusive.

The values n and m can be negative if a trigger is defined. Positions are displayed in the Elem column of the Analysis window.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Timefilter

TRACEBUFFER ,timefilter =time

Restricts the trace buffer information displayed in the Analysis window based on a time or range of times in the current time scale units, where time is an integer or range:

n

The time to display.

n..m

Display the range of times from n to m inclusive.

n..+o

Display the range of times from n to n+o inclusive.

The values n and m can be negative if a trigger is defined. You can use cycle numbers instead of time values. Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Addressfilter

TRACEBUFFER ,addrfilter =address

TRACEBUFFER ,addressfilter =address

Restricts the trace buffer information displayed in the Analysis window based on an address or range of addresses, where address is an integer or range:

n

The address to display.

n..m

Display the range of addresses from n to m inclusive.

n..+o

Display the range of addresses from n to n+o inclusive.

You cannot specify addresses symbolically with addressfilter. Use namefilter instead.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Namefilter

TRACEBUFFER ,namefilter ="name"

Restricts the trace buffer information displayed in the Analysis window based on a symbolic name, where name is a single string. The symbol names used by this filter are displayed in the Symbolic column of the Analysis window.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Percentfilter

TRACEBUFFER ,percentfilter =percent

Restricts the trace buffer information displayed in the Analysis window based on an percentage of the buffer, where percent is an integer or range:

n

The percentage to display.

n..m

Display the range of percentages from n to m inclusive.

n..+o

Display the range of percentages from n to n+o inclusive.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Datavaluefilter

TRACEBUFFER ,dvalfilter =value

TRACEBUFFER ,datavaluefilter =value

Restricts the trace buffer information displayed in the Analysis window based on an data value or range of values, where value is an integer or range:

n

The value to display.

n..m

Display the range of value from n to m inclusive.

n..+o

Display the range of value from n to n+o inclusive.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Accesstypefilter

TRACEBUFFER ,typefilter =mask

TRACEBUFFER ,accesstypefilter =mask

Restricts the trace buffer information displayed in the Analysis window based on an access type, where mask is a bitwise-OR of the following values:

0x001

Code access.

0x002

Data access.

0x004

Instruction prefetch.

0x008

DMA.

0x010

Interrupt.

0x020

Bus transaction.

0x040

Probe collection.

0x080

Pin or signal change.

0x100

Non-trace error.

Applying a filter to the trace buffer does not lose information unless you save the trace with the filtered qualifier. See Savefile for more information.

Clearfilter

TRACEBUFFER ,clearfilter

Remove any and all of the filters applied to the trace buffer, so that the Analysis window displays all the collected trace information.

Or_filter

TRACEBUFFER ,or_filter

Specifies that, if multiple filter conditions are applied to the trace buffer, the trace data is displayed if any of the filters display it. That is, the display is the union of all the filters. This is the initial state and you can change it using and_filter. Specifying or_filter overrides a previously active and_filter setting, and the change is applied to the Analysis window immediately.

And_filter

TRACEBUFFER ,and_filter

Specifies that, if multiple filter conditions are applied to the trace buffer, the trace data is displayed only if all of the filters display it. That is, the display is the intersection of all the filters. Specifying and_filter overrides a previously active or_filter setting and the change is applied to the Analysis window immediately.

Invert_filter

TRACEBUFFER ,invert_filter

Invert the sense of the specified filter conditions.

For example, if you specify posfilter and Datavaluefilter, then:

  • with and_filter specified, the filtering process returns trace information for the areas of execution except where both the position and data value match criteria you have entered are satisfied

  • for or_filter specified, the filtering process returns trace information for the areas of execution except where either the position or data value match criterion you have entered is satisfied.

Normal_filter

TRACEBUFFER ,normal_filter

Revert back to non-inverted filtering (the default).

Pos_relative

TRACEBUFFER ,pos_relative

Specifies that the element (position) numbering used in the Elem column of the Analysis window is relative to the trigger position, so that the trigger record is numbered 0, the record before (in time) the trigger is -1, and the record after is 1.

Pos_absolute

TRACEBUFFER ,pos_absolute

Specifies that the element (position) numbering used in the Elem column of the Analysis window is absolute, so that the record captured first is numbered 0, and records captured later are numbered in increasing sequence.

You cannot use this mode with the ARM ETM because records are always relative to a trigger.

Refresh

TRACEBUFFER ,refresh

This option refreshes the trace display.

Gui

TRACEBUFFER ,gui

This option modifies the action of the other commands. It specifies that the TRACEBUFFER command was initiated from the GUI, and that messages must be displayed using dialogs rather than text in the command window.

Note

This option has no effect when running in command line mode.

Examples

The following examples show how to use TRACEBUFFER:

TRACEBUFFER,timefilter 49.9..50.1

Set a filter that displays in the Analysis window only trace records captured 0.1 time unit before and after 50 time units. You set time units with scaletime.

TRACEBUFFER,savefile,full ="tracerun.trc"

Save the whole of the current trace buffer, because no filtering is applied, to a file in the current directory called tracerun.trc.

TRACEBUFFER,find_name ="main"

Search through the Analysis window for the first occurrence of the text main, and display it.

See also

The following commands provide similar or related functionality:

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