Skip to main content

Using the EIV SDK API

This section documents how to use the EIV SDK API to generate traces and provide associated data (trace arguments) in C/C++ applications .

Audience: This section only applies to firmware developers.

Include Files​

The following include files shall be loaded in order to use the SDK API functions:

EIV SDK Include Files

#include "sternum_ads_api.h"

note

The trace_protocol_user_definition.h file is generated automatically by Studio and contains the definitions of the traces and trace arguments associated to your device profile in the Sternum Platform. You can also download this file directly from the device profile menu Download Traces Definition -> Header File in the Sternum Platform.

Detailed API Usage​

The detailed API reference documentation can be found in the API Reference section and inline in the sternum_ads_api.h file.

Initialize the API​

The function STERNUM_ADS_INITIALIZE() shall be invoked right after the system was completely initialized and before any use of other SDK API functions. This function initializes the API and the tracing capabilities.

Refer to the API reference information for the status return value.

Generate Traces​

The SDK function to generate a trace in your application code is STERNUM_ADS_TRACE(), which is non-blocking.

Trace with no argument​

The function to generate a trace with no argument is:

Trace with no argument
STERNUM_ADS_TRACE(TraceType);

with:

  • TraceType: The trace type generated by Studio and defined in the trace_protocol_user_definition.h file.
    It references a system trace or a trace you defined using Studio.

Refer to the API reference information for the status return value.

Example of BOOT trace with no argument
STERNUM_ADS_TRACE(TRACE_BOOT);

Trace with one trace argument​

The function to generate a trace with one trace argument is:

Format of a trace with one argument
STERNUM_ADS_TRACE(
  TraceType,
  Argument_Arg_Type(ArgumentRoleType, [ Size, ] Value) );

with:

  • TraceType: The trace type generated by Studio, defined in the trace_protocol_user_definition.h file.
  • Argument_Arg_Type: the argument to add to the trace, composed of:
    • ArgType: The type of argument. The following types are supported:
      • Simple types - where the Size parameter is not required:
        • Integer: ARGUMENT_INTEGER
          • Unsigned integer: ARGUMENT_UINTEGER
          • Float: ARGUMENT_FLOAT
          • Pointer: ARGUMENT_POINTER
        • Complex types - where the Size parameter is required:
          • String: ARGUMENT_STRING (see also next section). The Size parameter specifies the size of the string.
          • Blob: ARGUMENT_BLOB, i.e. a byte buffer. The Size parameter specifies the size of the byte buffer.
      • ArgumentRoleType: The trace argument role type generated by Studio and defined in the trace_protocol_user_definition.h file. It references the Trace Argument you defined using Studio.
      • Value: the value of the argument.

Refer to the API reference information for the status return value.

1- Example: Generating a trace with an unsigned integer argument

Example of trace with an unsigned integer argument
    STERNUM_ADS_TRACE(  
      TRACE_CPU_USAGE,  
      ARGUMENT_UINTEGER(ARG_ROLE_PERCENT, cpuUsagePercent));

    STERNUM_ADS_TRACE(  
      TRACE_CLIENT_DISCONNECTED,  
      ARGUMENT_UINTEGER(ARG_ROLE_ID, 123));

2- Example: Generating a trace with a string argument

Example of trace with a string argument
    STERNUM_ADS_TRACE(  
      TRACE_TASK_STARTED,  
      ARGUMENT_STRING(ARG_ROLE_NAME, 256, "task12"))

3- Generating a trace with a blob argument

Example of trace with a blob argument
    STERNUM_ADS_TRACE(  
      TRACE_IMPLANTABLE_IDENTIFICATION,  
      ARGUMENT_BLOB(ARG_ROLE_ID, myByteBufferLen, myByteBuffer));

myByteBufferLen is the amount of bytes to be collected. myByteBuffer is the blob itself and can be a literal or a pointer variable.


Trace with multiple trace arguments​

The function to generate a trace with multiple trace arguments is:

Format of a trace with multiple arguments
STERNUM_ADS_TRACE(
  TraceType,
  ARGUMENT_<ArgType>(ArgumentRoleType, [ Size, ] Value)
  [, ARGUMENT_<ArgType>(ArgumentRoleType>, [ Size,] Value]* ));

with the same parameters as above.

Refer to the API reference information for the status return value.

Example of trace with multiple arguments
STERNUM_ADS_TRACE(
  TRACE_VIDEO_SESSION_REPORT,  
  ARGUMENT_UINTEGER(ARG_ROLE_SID, 16, sessionId),  
  ARGUMENT_UINTEGER(ARG_ROLE_VS_DURATION, sessionDurationSecs),  
  ARGUMENT_STRING(ARG_ROLE_USERID, 256, userId),
  ARGUMENT_BLOB(ARG_ROLE_USERKEY, 16, userKey));

Generate Formatted String Traces​

The STERNUM_ADS_TRACEF() function allows to generate a trace with a formatted string argument:

Formatted string trace
STERNUM_ADS_TRACEF(TraceType, ArgumentRoleType, Format, ...);

Where Format is a string that contains the text argument value. It can optionally contain format tags that are replaced by the values specified in subsequent additional arguments (represented as …) and formatted as requested.

See https://linux.die.net/man/3/printf to learn more on the format structure.

Traces with malformed arguments will be sent if possible. An indicative error will be returned.

Refer to the API reference information for the status return value.

Example of formatted string trace
STERNUM_ADS_TRACEF(
  TRACE_TASK_STARTED,
  ARG_ROLE_MESSAGE,
  "Task %s was started at %d", name, time);

Flush Traces​

This function will trigger and wait for the completion of the transmission of traces that have not been sent yet to the Sternum Platform.

If the transmission cannot be completed after a reasonable timeout, the API will abort.

Flush all traces
STERNUM_ADS_FLUSH();

Refer to the API reference information for the status return value.