System Profiler: user event formatting XML reference

QNX Tool SuiteIntegrated Development Environment User's GuideDeveloperSetup

This reference document defines attributes of the datakey specifier. For a detailed guide that walks through several examples, go to Formatting user events with the System Profiler.

eventdefinition

The high-level tag for the XML document.

To see the legacy format, go to eventclass (deprecated).

datakey

The datakey tags are subtags of the eventdefinitions tag, and events are subtags of a datakey; this allows keys and enums to be assigned to multiple events. The offset attribute allows you to specify where the datakey resides within the event data. There is also a wide_offset attribute for handling non-user events, when you want to differentiate between simple and wide data.

The datakey specifies a format that is applied to trace events specified by the required event subtags. All other subtags are optional, but are useful for controlling how the specified format is applied.

Attributes:

One or more required.

Attribute Description
format (string, required) Define the elements and labels. Same as sformat but arrays aren't supported. For more information about sformat, go to eventclass (deprecated).
offset (number, optional) Specify the region of data that the datakey should begin parsing the format at. Default value is 0.
wide_offset (number, optional) Specify the region of data that the datakey should begin parsing the format at for wide data. Not recommended. Default value is 0.
show_masked_value (true/false, optional) Displays hex values as well as enum strings. Only set this field to false if you haven't specified condition attributes for the field. Default value is true.

event (subtag)

One or more required.

Attributes:

Attribute Name Class ID Description
class (number, required) Required class ID of events this datakey applies to.
CONTROL 1 The _NTO_TRACE_CONTROL class includes events related to the control of tracing itself.
KER_CALL 2 The _NTO_TRACE_KERCALL is a pseudo-class that comprises all these classes.
INT 3 The _NTO_TRACE_INT class includes events related to interrupts.
PR_TH 4 The _NTO_TRACE_THREAD class includes events related to state changes for threads.
SYSTEM 5 The _NTO_TRACE_SYSTEM class includes events related to the system as a whole.
USER 6 The _NTO_TRACE_USER class includes custom events that your program creates.
COMM 7 The _NTO_TRACE_COMM class includes events related to communication.
QUIP 8 The _NTO_TRACE_QUIP class is the QNX Unified Instrumentation Platform class.
SEC 9 The _NTO_TRACE_SEC class includes events related to security.
QVM 10 The hypervisor event class includes events omitted by the hypervisor. To learn how to support these events, go to the information on updating hypervisor event trace descriptions in the hypervisor documentation.
id (number, required) Required event ID that this datakey applies to.

Example:

The event tag in the example datakey targets the user class events 65 and 15.

<eventdefinitions>
  <datakey format="%2u1x ipicmd %2u1x ipicmd2" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
    <event class="6" id="15" />
  </datakey>
</eventdefinitions>

bit mask (subtag)

You can perform bitmask ANDing to extract a subset of the bits from the field with a matching name attribute; this affects how this value is matched to enums. Bitmasks are intended to help isolate bitfields packed together into other data sizes. For example, you might pack together a 6-bit and 10-bit value into a 16-bit integer. A bitmask would help you split these values up into their own fields. If the mask ends with zeroes, like 0xff00, then the 0's on the bitmasked value are truncated. For example, if you had the field ipicmd (0x7cff), and bitmasked it with 0xff00, the resulting value would be 0x7c and not 0x7c00. This truncation allows you to more easily use enums to match against bitfields, as if you were accessing the bitfield in code.

Attributes:

Attribute Description
name (string, required) The label of the element to bitmask. Although typically required, this attribute is not necessary if the sformat attribute of the parent datakey only has one field (ie: <datakey sformat="%4u1x onlyfield" ... >).
key (string, deprecated - use name instead) Serves the same function as the name field which is now preferred. Can still be used for compatibility with older file formats.
value (number, required) Value to bitwise AND with the specified field.

Example:

In this example, the ipicmd field is masked with 0xff.

<eventdefinitions>
  <datakey format="%2u1x ipicmd %2u1x ipicmd2" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
    <bitmask name="ipicmd" value="0xff" />
  </datakey>
</eventdefinitions>

condition (subtag)

Display condition that controls whether the format specified in the parent datakey is applied to the event data, based on the mask, value, or both.
Note:
You should at minimum specify a mask or a value. You can also specify both a mask and a value.
CAUTION:

Conditions that match against fields specified by the format being conditionally applied are ignored. In the following example, the condition matching is ignored because the ipicmd field is specified in the format of the datakey with the condition. To work around this, only use condition subtags targeting fields defined in other datakeys.

<eventdefinitions>
  <datakey format="%1u1x ipicmd" offset="0" wide_offset="0" show_masked_value="false">
    <event class="6" id="65" />
    <condition key="ipicmd" mask="!0x0001" />
  </datakey>
</eventdefinitions>

Attributes:

Attribute Description
name (string, required) The label of the field that this condition matches against. Use field names contributed by other datakeys. Optional if only one label in format string. Otherwise, label of element to be applied to.
key (string, deprecated - use name instead) Serves the same function as the name field which is now preferred. Can still be used for compatibility with older file formats.
value (number, optional) Value to compare against. The condition evaluates to true if the element (or masked element, if mask is present) equals the value.
Note:
The value for this attribute can be prepended with ! to invert the match.
mask (number, optional) Number to bitwise AND with the specified element. If no value attribute is present, the condition will evaluate to true if the masked element equals the mask itself.

Example:

In the following example, The value in ipicmd would be bitwise AND with 0x0001, and depending on whether the resulting value is 0x0001, the contributed value would be formatted as dstring1 or dstring2.

<eventdefinitions>
  <datakey format="%2u1x ipicmd" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
  </datakey>
  <datakey format="%1s0 dstring1" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
    <condition key="ipicmd" mask="0x0001" />
  </datakey>
  <datakey format="%1s0 dstring2" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
    <condition name="ipicmd" mask="!0x0001" />
  </datakey>
</eventdefinitions>

enum (subtag)

Specify strings to display.
Note:
The enum matching is performed after the bitmask tag is applied to the target value.

Attributes:

Attributes support either mask or value, but not both.
Attribute Description
name (string, required) Optional if only one label in format string. Otherwise, label of element to be applied to.
value (number, optional) Value to compare against. Can be prepended with ! to invert the match.
mask (number, optional) Mask value to compare against. If you provide a mask, the following operation is used for matching: raw_value & mask == mask. Can be prepended with ! to invert the match.
string(string, required) String to display if mask or value match.
default(string, optional) String to display if no other enum matches.

Example:

<eventdefinitions>
  <datakey format="%2u1x ipicmd %2u1x ipicmd2" offset="0" wide_offset="0" show_masked_value="true">
    <event class="6" id="65" />
    <enum name="ipicmd" mask="0x100" string="1_bit_8" />
    <enum name="ipicmd" mask="0x200" string="1_bit_9" />
    <enum name="ipicmd" mask="0x400" string="1_bit_10" />
    <enum name="ipicmd" default="1_default" />
    <enum name="ipicmd2" value="0x1" string="2_val_1" />
    <enum name="ipicmd2" value="0x2" string="2_val_2" />
    <enum name="ipicmd2" value="0x4" string="2_val_3" />
    <enum name="ipicmd" default="2_default" />
  </datakey>
</eventdefinitions>

eventclass (deprecated)

The eventclass tag provides a simple way to format events, but has been deprecated in favor of the datakey tag which is more powerful. For more information, go to eventdefinition.

event (subtag)

One or more required.

Attribute Description Format
sformat Define the elements and labels. In general, an event is described as a serial series of event payload definitions. The label becomes the field name shown in the IDE. Where:
  • size — Size in bytes. Valid values are: 1, 2, 4, 8.
  • signed — Specifies whether the value is signed (s) or unsigned (u).
  • count — The number of items to read (ie., an array). If the <size> is 1 and there is no formatting, then the <count> can be 0; this accommodates NULL-terminated strings.
  • format — (optional) A hint as to how to format this value: d(decimal), x(hexadecimal), o(octal), c(character).
  • label — String label that can’t contain the % character.
 
%<size><signed><count><format> <label>
id Required event ID of events this datakey applies to. NA

Example:

The %2u1x ipicmd indicates that the field will be labeled ipicmd. It's an unsigned, single value; formatted in hexadecimal; and made up of 2 bytes of data.

<eventdefinitions>
  <eventclass id="6" name="User Events">
    <event id="65" sformat="%2u1x ipicmd %2u1x ipicmd2" />
    <event id="15" sformat="%2u1x ipicmd %2u1x ipicmd2" />
  </eventclass>
</eventdefinitions>
Page updated: