cobctf_trace

Outputs an event to one or more output destinations.

Syntax:
cobrtncode_t cobctf_trace(cobuns32_t      flags,
                          const cobuns8_t *component_id,
                          TRACE_EVENT     *trace_event)
Parameters:
flags Control flags:
Bit Value Meaning
0-11 Reserved for future use. Must be 0.
12 0 Output event data only if the component is enabled for tracing, and if the event level specified by level in the trace_event structure is greater or equal to the tracing level configured for the component.
1

Force the output of the event if the component is enabled for tracing. level in the trace_event structure and the tracing level configured for the component are ignored.
13 0 event_data is an array of pointers to trace data of varying size and type. The corresponding elements of the event_len and event_type arrays need to be defined.
1 event_data is an array of pointers to trace data of the same size and type. Only the first element of event_len and event_type need to be defined.
14-29 Reserved for future use. Must be 0.
30 0 component_id is space-terminated.
1 component_id is null-terminated. This is ignored if bit 31 is unset.
31 0 component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component_id Component identifier. This is either a 32-bit unsigned integer tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a text identifier if bit 31 of flags is set.
trace_event Trace event structure:
version Structure version. Must be 0.
flags Control flags. Must be 0.
event_id Component-specific event identifier used to identify the type of event being output.
level Tracing level of the event being output.
data_count Number of trace data items, indicating the number of elements in the event_len, event_type, and event_data arrays. This can be 0.
event_len Pointer to an array of 32-bit unsigned integers. Each array element indicates the length of the corresponding trace data item in the event_data array. This can be NULL if data_count is 0.
event_type Pointer to an array of 32-bit unsigned integers. Each array element indicates the type of the corresponding trace data item in the event_data array. This can be NULL if data_count is 0.
Value Type
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
Any value other than the ones specified above is treated as type 0 (binary).
event_data Pointer to array of pointer items. Each array element addresses a trace data item of the type and length indicated by the corresponding element in the event_type and event_len arrays respectively. This can be NULL if data_count is 0.

For address type items, the array element is the address value; not a pointer to the address value.
cobrtncode_t One of:
  • CTF_RET_INVALID_COMPONENT_NAME
  • CTF_RET_INVALID_TRACE_HANDLE
  • CTF_RET_INVALID_TRACE_LEVEL
  • CTF_RET_NOT_ENOUGH_MEMORY
  • CTF_RET_NOT_TRACE_ENABLED
  • CTF_RET_NOT_TRACING_LEVEL
  • CTF_RET_OUTPUT_ERROR
  • CTF_RET_SUCCESS
Comments:

cobctf_trace outputs the event specified by event_id to one or more output destinations provided that the event level specified in level is greater or equal to that configured for the component.

Example:
#include "mfctf.h"

#define EVENT_TYPE_A    1

some_func()
{
    const cobuns8_t *component_id  = "mycomp";
    cobuns32_t      event_len[1];
    cobuns32_t      event_type[1];
    void            *event_data[1];
    cobuns32_t      flags;
    TRACE_EVENT     trace_event;
    cobuns32_t      tracer_handle;
    cobuns32_t      trace_info = 999;

    ...
    /*
    ** Acquire tracer handle
    */
    CBL_CTF_TRACER_GET(CTF_FLAG_COMP_NAME_NULL_TERM,
                       component_id, 
                       (cbl_x4_comp5_t *)&tracer_handle); 

    /*
    ** Set up trace event
    */
    memset(&trace_event, 0, sizeof(trace_event);

    trace_event.event_id = EVENT_TYPE_A;
    trace_event.level = CTF_FLAG_LEVEL_INFO;
    trace_event.event_len = (cobuns32_t *)&event_len;
    trace_event.event_type = (cobuns32_t *)&event_type;
    trace_event.event_data = &event_data;

    event_len[0] = sizeof(trace_info);
    event_type[0] = TRACE_EVENT_TYPE_COMP5;
    event_data[0] = &trace_info;

    /*
    ** Output trace event
    */
    cobctf_trace(0,
                 (const cobuns8_t *)&tracer_handle,
                 &trace_event);
    ...
}

Related Topics: