Using the API

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

Include Files

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

#include "sternum_sdk.h"

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

Detailed API Usage

Initialize the API

The SDK environment (i.e. settings) shall be defined before calling the SDK initialization function. The environment is defined by the struct sternum_sdk_settings_t structure. It defines for example the trace flush behavior, the device id to use, and other parameters:
You can also use the predefined function init_sternum_sdk_settings(sternum_sdk_settings_t * settings) to initialize your settings struct object.

typedef struct sternum_sdk_settings_t {
    uint32_t        inter_transmission_delay_ms;    //!< Time to wait in milliseconds between each transmission
    const char *    firmware_version;               //!< Firmware version string
    bool            flush_automatically;            //!< Enable to transmit traces immediately if possible
    unsigned char * trace_buffer;                   //!< Pointer to buffer holding single trace
    size_t          trace_buffer_size;              //!< Size of buffer holding single trace
    unsigned char * communication_buffer;           //!< Pointer to buffer holding all pending traces
    size_t          communication_buffer_size;      //!< Size of buffer holding all pending traces
    uint64_t        access_token;                   //!< Device type ID taken from ADS
    uint64_t        device_id;                      //!< Device ID unique for each device (eg. device serial number or unique random number)
} sternum_sdk_settings_t;

This table provides more information on each parameter:

Parameter	Default Value	Description
inter_transmission_delay_ms	100	Time to wait in milliseconds between each transmission.
firmware_version	none	Device firmware version string. Used in system trace generated by the sdk_init().
flush_automatically	false	Automatically call sdk_flush() for each trace.
trace_buffer	none	Pointer to buffer holding single trace. You are responsible to allocate the buffer and assign this field with its address.
trace_buffer_size	none	Size of buffer holding single trace. You are responsible to set this field with the size of the allocated trace_buffer.
communication_buffer	none	Pointer to buffer holding all pending traces. You are responsible to allocate the buffer and assign this field with its address.
communication_buffer_size	none	Size of buffer holding all pending traces. You are responsible to set this field with the size of the allocated communication_buffer.
access_token	none	The access token (aka. Device Profile ID) obtained from ADS for your device/firmware type. Refer to ADS Device Profiles.
device_id	none	The ID of the device (uint64_t value).

A simple way to define the settings is to use the predefined settings and completes its non-initialized parameters, a shown in the next example.

The function sternum_sdk_initialize() shall be invoked right after the system was completely initialized and before any use of other API functions. This function uses the provided settings to initialize the API and the tracing capabilities. For example, it triggers the creation of underlying resources (e.g. mutexes or communication channels, depending on the operating system/integration).

An example of initialization is:

sternum_sdk_settings_t sdk_settings;
 
unsigned char SDK_SINGLE_TRACE_BUFFER[128];
unsigned char SDK_PENDING_TRACE_BUFFER[2048];
 
 
int main(int argc, char *argv[]) {
 
    init_sternum_sdk_settings(&sdk_settings);
 
   /* Define SDK behavior */
 
    sdk_settings.firmware_version = "1.1";
 
    /*
      Use default values for:
        sdk_settings.inter_transmission_delay_ms
        sdk_settings.flush_automatically
    */
 
    sdk_settings.trace_buffer = SDK_SINGLE_TRACE_BUFFER;
 
    sdk_settings.trace_buffer_size = sizeof(SDK_SINGLE_TRACE_BUFFER);
 
    sdk_settings.communication_buffer = SDK_PENDING_TRACE_BUFFER;
 
    sdk_settings.communication_buffer_size = sizeof(SDK_PENDING_TRACE_BUFFER);
 
    sdk_settings.access_token = 1234567890;
    sdk_settings.device_id = 125478;
 
 
    sternum_code_t status = sternum_sdk_initialize(&sdk_settings);
    if (status != STERNUM_CODE_SUCCESS) {
        return -1;
    }

Generate Traces

The SDK provides the following functions to generate traces in your application code:

• STERNUM_ADS_TRACE()
• STERNUM_ADS_TRACEF()
• and a set of trace type-specific functions.

Examples of use of these functions are described below.

Trace with no argument

To generate a 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.

STERNUM_ADS_TRACE(TRACE_BOOT);

Trace with one trace argument

To generate a trace with one trace 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

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

STERNUM_ADS_TRACE(
  TRACE_TASK_STARTED,
  ARGUMENT_STRING(ARG_ROLE_NAME, 256, "task12"))

3- Generating a 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

To generate a trace with multiple trace 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.

STERNUM_ADS_TRACE(
  TRACE_VIDEO_SESSION_REPORT,
  ARGUMENT_UINTEGER(ARG_ROLE_SESSION_ID, sessionId),
  ARGUMENT_UINTEGER(ARG_ROLE_VS_DURATION, sessionDurationSecs),
  ARGUMENT_STRING(ARG_ROLE_USER_ID, 256, userId),
  ARGUMENT_BLOB(ARG_ROLE_USER_KEY, 16, userKey));

Generate Formatted String Traces

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

STERNUM_ADS_TRACEF(TraceType, ArgumentRoleType, MaxLength, 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.

STERNUM_ADS_TRACEF(
  TRACE_TASK_STARTED,
  ARG_ROLE_MESSAGE,
  256,
  "Task %s was started at %d", name, time);

Use Predefined Trace Functions

To enhance user convenience, we have included a collection of predefined logs that are commonly used. The complete set of predefined log functions is detailed in the sternum_trace_api.h file.

To employ a predefined log, you can easily call it as a function with the required argument.

trace_reboot_reason("User request");

Refer to sternum_trace_api.h for a comprehensive list of available predefined log functions.

Flush Traces

The sternum_sdk_flush() function will trigger and wait for the completion of the transmission of pending traces that have not been yet sent to the Sternum Platform.

If the transmission cannot be completed, the function will return an error.

sternum_sdk_flush();

Auto flush mechanism

The SDK can manage the flushing of traces automatically.
To enable auto-flush, set the flush_automatically flag to true in the sdk_settings set during the SDK initialization.

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

Activity Diagram

The activity diagram detailing the sequence of events when a user initiates the STERNUM_ADS_TRACE() or sternum_sdk_flush() operation provides a comprehensive overview of the system's behavior during these specific actions.