http://www.percepio.com/

User Events

Overview

User Events are custom events that you generate from your application code. They can be used for logging any kind of event and/or data, including variables in control algorithms, software states, hardware state, inputs and outputs.

In ThreadX, User Events are created by calling tx_trace_user_event_insert, with an event code and up to four data arguments. By default, Tracealyzer displays such User Events as e.g. "Event 4096", followed by the four data arguments provided.

User Events are stored quickly and can typically be used without noticeable overhead. Note the time scale in the above screenshot - the gray area is 10 µs, so the User Events are less than 1 µs apart.

Custom Formatting

To simplify comprehension, Tracealyzer allows you to customize the display of User Events by adding your own names and format strings to each Event ID. This formatting does not affect the logged data in the target system, but only the host-side display in Tracealyzer.

For example, the same trace as above, with the "User Event Definitions" provided below:

Custom formatting of User Events is specified in "File" -> "Settings" -> "User Event Definitions".

A User Event Definition is an entry with three fields:

  • Event ID: The numerical code, as specified in tx_trace_user_event_insert (e.g., 4096, 4097, ...).
  • Channel Name: What to call these events in Tracealyzer (e.g. "Sensor1").
  • Format String: How to present each individual event, including data arguments. See syntax below.

In the Settings window, the "User Event Definitions" dialog is divided into two parts. The lower part, labeled "User Event Definitions", shows the definitions you have created so far. They are saved to the Tracealyzer settings file when you click OK. To edit an existing entry, you can also double-click on the entry instead of using the Edit button.

The upper part, labeled "Add or Update..." is an editor that allows for creating a new entry, and for editing an existing entry. When you have finished editing a definition, click "Add/Update" to save the definition to the lower list. The settings file is however not updated until you click OK, so you can undo your changes by selecting Cancel or simply closing the window.

Format Strings
The format string has very similar syntax as the classic printf function, with the general syntax as follows:

%[flags][width][subtype]type

The type specifier provides the data type (signed or unsigned integer) and radix (decimal or hex)::

  • d: signed integer
  • u: unsigned integer
  • x: hexadecimal integer (lowercase)
  • X: hexadecimal integer (uppercase)
  • p: pointer (same as %08X)

The values are assumed to be 32 bits wide, unless an optional subtype specifier is included:

  • b: 8-bit value (e.g., %bd means 8-bit signed integer)
  • h: 16-bit value (e.g., %hu means 16-bit unsigned integer)

The optional width specifier is the minimum number of characters that will be displayed. If the value has fewer digits, the output is padded with spaces or zeros. For instance, the value 42 printed with %08d results in 00000042.

Finally, the flags allow for additional formatting. The following flags are supported:

  • -: Causes left alignment if padding (width) is specified (e.g. %-8d). Default is right alignment.
  • 0: The value is padded with zeros instead of spaces (e.g. %08u).
  • #: For hexadecimal output (x or X), this appends "0x" before the value (e.g. %#04X)

User Event Signal Plot

The User Event Signal Plot view displays a plot over time, for the first data arguments in each User Event, grouped into channels.

Like other views, this is connected to the main Trace View, which allows for correlating the signal values with the task scheduling and other recorded events. For instance, if you spot an anomaly in a monitored output signal of a control loop, you can double-click on the data point to show the specific user event in the trace view. This allows you to analyze what was going on at this time - perhaps the scheduling caused an extra delay of the control loop task which affected the signal.

As mentioned, double-clicking a data point navigates the Trace View to that User Event. You may also right-click on a data point you get another option, "Show in Log", that opens the User Event Log. User Events are also displayed in the more flexible Event Log.

To select what channels to display, click in the "Legend" on the right. If you right-click on an entry in the legend, you may select "Show Only [channel name]" or "Show All".

You can combine this view with other horizontal views by choosing Views -> Add -> (graph type).

User Event Log

The User Event Log view displays all user events of the recording in a list view. This view can be opened by double-clicking on a user event in the main trace view, from the View menu, or by right-clicking on a data point in the User Event Signal Plot. Clicking on a user event in this view highlights the corresponding label in the Trace View. User Events can be searched for and filtered using the textbox in the panel on the right.

You may also filter the user event list using Perl compatible Regular Expressions. Enable this by checking the Regex checkbox.

User Events are also displayed in the more flexible Event Log.


Copyright Percepio AB 2017, all rights reserved.