Customizing the USER output mode

Trace Probes for C

The USER output mode for Trace Probes requires that you rewrite user-defined probecst.c and probecst.h based on the files provided with the product.

Only use the USER mode if the DEFAULT, FIFO or FILE modes are not practical for your application.

To rewrite your own routines, make a copy of the probecst.c and probecst.h that are provided with the product and use them as a template. These files are located in the following directory located in the installation directory of the product:

/lib/probe/probecst/fifo

Note These are the files that are used for the FIFO output mode, therefore ensure that any changes that you make are performed on copies of these files.

The implementation delivered in the FIFO mechanism is based on a circular buffer. The instrumented application sends traces to the intermediate storage buffer, by using the atl_write_probe function. The traces can then be read by the atl_read_probe function.

You can modify this file to adapt the probe mechanism to your application and platform.

For example, when using USER mode, the main probed application may store messages in binary format in a shared memory or pipe, whereas a dedicated "dump application" can be written to read the shared memory or pipe and to generate the .rio result file.

By using this method, the probed application can still run with minimal overhead while another process generates the .rio result file either on the fly or after the execution of the probed application.

Whichever storage mechanism you use, it is important that the dump application runs within the same hardware architecture as the main application to avoid misalignment or little-big endian problems.

When using the USER mode, you must specify the location of the user-defined probecst.c and probecst.h files in the USER custom files directory setting. See Probe control settings for details.

The probecst.c file contains definitions for the Trace Probe macro functions. These are detailed below. For the usage and syntax of the Trace Probe macros, please refer to the Reference section. For each function, the probecst.c file contains comments that should help you to rewrite each of these functions.

The following functions must be executed during the execution of the probed application:

atl_create_probe
atl_end_probe
atl_write_key
atl_write_probe

The following functions can be executed when the probed application ends or after the application has finished in a dedicated dump application:

atl_open_probe
atl_close_probe
atl_read_probe

atl_start_trace

The atl_start_trace function executes atl_create_probe. It must be called before any other macros, once for each instance. Its role is to open, create and initialize the intermediate storage media used to keep messages in the intermediate binary format.

atl_end_trace

The atl_start_trace function executes atl_end_probe. It must be called at the end of the application, once for each instance. Its role is to close the intermediate storage media used to keep messages in the intermediate binary format.

atl_send_trace and atl_recv_trace

The atl_send_trace and atl_recv_trace functions execute atl_write_probe in order to dump the message to the intermediate storage media.

It is important that the .rio result file retains the message sequence. Therefore, ensure that data is recorded in the execution order.

atl_write_probe

The role of the atl_write_probe function is to record the following data:

The complete message, the length of the message is provided to help.
The date of the event.
An internal code.
The key format.

If your USER mechanism required the use of intermediate storage, the atl_dump_trace must be called after the atl_end_trace macro.

atl_dump_trace()

This macro can be either part of the probed application or part of a dedicated dump program that would be executed after the main application, depending on what is practical in your application.

The atl_dump_trace() macro executes, for each instance,

atl_open_probe,
atl_read_probe for each recorded message, and
atl_close_probe.

atl_open_probe

The role of the atl_open_probe function is to reopen the intermediate storage and point to the first recorded message.

atl_close_probe

The role of the atl_close_probe function is to close, destroy or free the memory of the intermediate storage.

atl_read_probe

The role of the atl_read_probe function is to retrieve the following data from the intermediate storage:

The message as it was recorded during the execution.
A timestamp of the message.
An internal code.
The key format of the message.

atl_select_trace

The role of the atl_select_trace function is to execute atl_write_key in the API. The code of this function must not be customized. It must be copied from the original probecst.c without any change.