Trace Hub Metadata

The Trace Hub metadata is one or more XML files used by SourcePoint to format and display Trace Hub trace data.  It includes information about the masters and channels in a system.  This includes names, display formats, and system-wide settings.  

The metadata is used for display purposes only.  It is not required to decompress the Trace Hub trace stream.  If metadata is not present, hex values will be displayed for master and channel names, and ASCII will be the default display format.

Following is a description of the different sections contained in the metadata file(s):

Files Section

The Trace Hub metadata can be contained in a single XML file, or multiple XML files.  The files section is used to specify additional metadata files to process.  File paths can be absolute or relative to the location of the top level file.  There is no limit to the levels of file nesting.

Following is an example of nested metadata files.  The top level file (specified in the Trace Hub Configuration tab) includes two additional files:

 

Settings section

The Settings element contains system-wide settings.  These settings apply to all masters and channels in the system.

 

Messages are made up of multiple Trace Hub data packets.  Data packets can be “marked” to indicate message boundaries.  Whether a marked packet contains the first byte(s) of a message, or the last byte(s) of a message, depends on the software generating the messages.  

The “mark terminates message” attribute is used to inform SourcePoint how marks are to be interpreted.  If the "mark terminates message" setting is set to true, marks terminate a message.  If the "mark terminates message" attribute is set to false, marks begin a message.

Newlines can be implied to terminate ASCII messages.  If the "newline terminates message" attribute is true then newlines end a message.  If messages contained multiple lines, then this setting should be set to false.

The “payload nibbles swapped” attribute needs to be set on certain early Trace Hub implementations.

The “master/channel display base” attribute controls the display base of master and channel numbers.  The default is “hex”.

Masters Section

The masters element defines the masters and channels in a system.  These include master names, channel names, and display formats.  Following are two simple master definitions:

 

The first master corresponds to master number 0x74 (master numbers are dependent on the target hardware).  The metadata file associates the name “P1” with master number 0x74.  When data from this master is displayed in the Trace view, “P1” will be displayed instead of 0x74.

There are 3 channels defined for master P1 (usually there would be many more).  Channel numbers are dependent on the software generating the Trace Hub trace data.  The metadata associates the name “Blue” with channel number 0x45.  Without the metadata file, the Trace view will display the master and channel as 74:45.  With the metadata file, the Trace view will display the master and channel as P1:Blue.

Each individual channel can have its own display format (more on display formats later).  If all channels in a master use the same display format, then the format can be specified at the master level.  This is the case for master P1 which specifies a display format of “ASCII” for all channels.

If most channels in a master are one display format, and a few channels are a different display format, then the display format can be overridden at the channel level.  This is the case for channel 0x22 in master P2.  Instead of displaying ASCII data, hex data will be displayed.

Display Formats

The following display format are supported:

ASCII.  Data packets are collected and displayed as a single ASCII string.  Strings are delimited by data markers, flag packets, null characters or optionally newline characters.

Example: format="ASCII"

Hex.  Each Trace Hub data packet is displayed as a single hex value.  The Size attribute specifies the display size.

Example: format="hex" size="32"

Tabular Hex.  Data packets are collected and displayed as tabular hex data.  The Columns and Size fields are used for formatting.  Tabular data is delimited by either data markers or flag packets.

Example: format="tabular hex" columns="16"

Hosted Printf.  Similar to ASCII string display, but SourcePoint performs the printf. See Hosted_Printf for more information.

Example: format="hosted printf"

Table Printf.  Similar to ASCII string display, but SourcePoint performs the printf. See Table_Printf for more information.

Example: format="table printf"

Bitfields. Displays a value as a series of bit fields rather than as a single hex value.  See Bit_Fields for more information.

Example: format="bit field"  template="myBitData"

Display Format Usage

Display formats can be specified at two different levels: per master, or per channel.  This design is meant to minimize the size of the metadata.  

Example  - Most channels of a master display ASCII data, but a few display hex data. Set the master display format to ASCII, and override the default at the channel level.

Note:  This design does not allow a single channel to use a mix of display formats.  If this is desired, then a pair of channels should be allocated.

Bit Fields

Bit fields display an 8, 16, 32 or 64-bit value as a series of bit fields rather than as a single hex value.  There are two ways to specify a bit field definition.  It can be entered in the channel definition, or if there are multiple channels that share the same bit field format, it can be entered as a bit field template, and referenced by name.

Example 1 – Bit field definition in channel definition

The following defines 3 bit fields in a 32-bit value.  The start attribute indicates the starting bit position for the field.  The size attribute specifies the size in bits of the field.

 

The bit field display format is defined by a user-specified printf format string (format above). The arguments to printf are the bit fields in the order they appear in the metadata.  Assuming a 32-bit hex value of 0x12345678, the output will look like this:

 

a=1234, b=78, c=56

Example 2 – Bit field definition from a bit field template

The following example generates the same output as Example 1, but uses a bit field template.  The bit fields are defined once (in the bit field templates section), and a name is assigned to the template (in this case myBitData).  The channel definition then references the bit field template by name.

 

Enumerations

Enumerations are used to show strings instead of values in bit fields.  In the following example there are two enumerations defined: “animals” and “people”.  In the bit field definition, the second field specifies that the value is to be displayed using the “animals” enumeration.

 

Assuming a 32-bit hex value of 0x12345678, the display will look like this ("cat" displayed instead of "78"):

a=1234, b=cat, c=56

Hosted Printf - Normal

The Hosted Printf display format specifies that SourcePoint should perform the printf rather than target software.  This is accomplished by emitting the address of the printf format string, and the printf arguments as data packets.  This greatly reduces the number of bytes traced.  

For example, the following printf call generates 28 bytes of trace data if the printf is performed by target software.  Using Hosted Printf results in only 12 bytes of trace data.

printf("index = %2d, value = %08X", _nIndex, _nValue)

An additional advantage of Hosted Printf is the decreased processing time for target software to generate the message.  Rather than executing potentially millions of printfs (which may be thrown away if the trace buffer wraps), the printfs are performed just-in-time by SourcePoint as they are displayed.

Note: Hosted printf requires changes to target software generating the Trace Hub data.  Contact ASSET InterTech for more information.

 

Note: Hosted printf can only be used on systems where the program traced is either still in memory, or loaded into the SourcePoint (SourcePoint needs access to the original printf format string).

Hosted Printf – Table-based

Table-based Hosted Printf is identical to normal Hosted Printf except the format strings come from tables in the metadata.  Rather than the address of the format string being emitted with the trace data, a key value is generated instead.  The key can be 8, 16, 32 or 64 bits.

Following is an example of a format string table and how to use it:

 

Trace View Coloring

Masters and Channels can be displayed in different colors in the Trace view (background colors only).  To display all channels in a particular master with the same color, a color attribute is specified at the master level.  To display an individual channel with a different color, specify the color at the channel level.

 

Up to eight different colors can be used.  These colors are shared with the eight different colors used in processor trace display.  Press Colors in the Trace Display Settings dialog to access these color settings.  The colors are labelled Processor 0 – Processor 7.  If a color is not specified, then the default color (labelled TraceHub) will be used.  

 

Following is an example of specifying colors.  All channels within the master use color 2, except for channel 22, which uses color 3.