Sternum iOS SDK
sternum_trace_api.h File Reference

Defines the SDK's API for transmitting traces. More...

#include <stdint.h>
#include <stdbool.h>
#include "trace_protocol_user_definition.h"
#include "error_codes.h"
#include "device_type.h"

Go to the source code of this file.

Functions

sternum_code_t sternum_trace_dynamic (int trace_event_type,...)
 
sternum_code_t sternum_trace_string_format (uint16_t trace_event_type, uint16_t argument_role_type, uint16_t max_length, const char *format,...)
 
void trace_battery_health (unsigned int capacity_percent, unsigned int voltage_mV)
 Trace battery health. More...
 
void trace_error (unsigned int error_code, const char *message, const char *file_name, unsigned int line)
 Trace error. More...
 
void trace_firmware_update_start (const char *firmware_version, const char *firmware_hash, const char *hash_algorithm)
 Trace firmware update start. More...
 
void trace_firmware_update_finish (void)
 Trace firmware update finished. More...
 
void trace_reboot_reason (const char *reboot_reason)
 Trace reboot reason. More...
 
void trace_signal_strength_report (unsigned int communication_type, int signal_strength)
 Trace signal strength. More...
 

Macros

#define STERNUM_ADS_TRACE(TRACE, ...)   sternum_trace_dynamic(TRACE, ## __VA_ARGS__, END_OF_ARGUMENTS)
 
#define STERNUM_ADS_TRACEF(TRACE, ARG_ROLE, MAX_LENGTH, FORMAT, ...)   sternum_trace_string_format(TRACE, ARG_ROLE, MAX_LENGTH, FORMAT, ## __VA_ARGS__)
 
#define END_OF_ARGUMENTS   0
 
#define POINTER_DEREFERENCE_INDICATOR   0x8000
 
#define UNSIGNED_INTEGER_TYPE   0
 
#define SIGNED_INTEGER_TYPE   1
 
#define FLOAT_TYPE   2
 
#define POINTER_TYPE   3
 
#define BLOB_TYPE   (4 | POINTER_DEREFERENCE_INDICATOR)
 
#define STRING_TYPE   (5 | POINTER_DEREFERENCE_INDICATOR)
 
#define ARGUMENT_STRING(ARG_ROLE, MAX_SIZE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)STRING_TYPE, (unsigned int)MAX_SIZE, (char*)(ARG_VALUE)
 
#define ARGUMENT_BLOB(ARG_ROLE, SIZE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)BLOB_TYPE, (unsigned int)SIZE, (uint8_t*)(ARG_VALUE)
 
#define ARGUMENT_INTEGER(ARG_ROLE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)SIGNED_INTEGER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)
 
#define ARGUMENT_UINTEGER(ARG_ROLE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)UNSIGNED_INTEGER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)
 
#define ARGUMENT_POINTER(ARG_ROLE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)POINTER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)
 
#define ARGUMENT_FLOAT(ARG_ROLE, ARG_VALUE)   (unsigned int)ARG_ROLE, (unsigned int)FLOAT_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)
 
#define STERNUM_ADS_TRACE_ERROR(error_code, message)   trace_error(error_code, message, __FILE__, __LINE__)
 Macro for convenient error tracing with file and line information. More...
 

Detailed Description

Defines the SDK's API for transmitting traces.

Function Documentation

◆ trace_battery_health()

void trace_battery_health ( unsigned int  capacity_percent,
unsigned int  voltage_mV 
)

Trace battery health.

Parameters
capacity_percent- Percentage of battery capacity remaining.
voltage_mV- Battery voltage in millivolts.

◆ trace_error()

void trace_error ( unsigned int  error_code,
const char *  message,
const char *  file_name,
unsigned int  line 
)

Trace error.

Parameters
error_code- The error code to be associated with the error.
message- A descriptive message providing additional information about the error.
file_name- Name of the file where the error originated.
line- The line number in the file where the error originated.

◆ trace_firmware_update_finish()

void trace_firmware_update_finish ( void  )

Trace firmware update finished.

This function is used to log the finish of a firmware update process.

◆ trace_firmware_update_start()

void trace_firmware_update_start ( const char *  firmware_version,
const char *  firmware_hash,
const char *  hash_algorithm 
)

Trace firmware update start.

This function is used to log the start of a firmware update process.

Parameters
firmware_versionThe version of the firmware being updated.
firmware_hashThe hash of the firmware being updated.
hash_algorithmThe algorithm used to generate the firmware hash.

◆ trace_reboot_reason()

void trace_reboot_reason ( const char *  reboot_reason)

Trace reboot reason.

Parameters
reboot_reason- reboot reason description

◆ trace_signal_strength_report()

void trace_signal_strength_report ( unsigned int  communication_type,
int  signal_strength 
)

Trace signal strength.

Parameters
communication_type- code describing communication type [unsigned int]
signal_strength- signal strength (unit can be defined in cloud)

Macro Definition Documentation

◆ STERNUM_ADS_TRACE

#define STERNUM_ADS_TRACE (   TRACE,
  ... 
)    sternum_trace_dynamic(TRACE, ## __VA_ARGS__, END_OF_ARGUMENTS)

A general API to transmit ADS traces. Please note that some development environments will require enabling GNU C extensions.

In order to initialize ADS tracing, please invoke initialize_communication_relay before using this API. Using this API, you will able to create traces with infinite number of arguments.

Trace format: STERNUM_ADS_TRACE(TRACE_*, [ARGUMENT_*(ARG_ROLE_* [,SIZE], ARG_VALUE), ARGUMENT_*(ARG_ROLE_* [,SIZE], ARG_VALUE), …]) Each trace call is constructed with a trace event type, defining the purpose of the trace. For example, TRACE_TASK_STARTED. Every trace event type has the "TRACE_" prefix.

A trace can posses multiple arguments. Each argument is constructed from an argument role type that defines the purpose of the argument. For example, ARG_ROLE_NAME. Every argument role type has the "ARG_ROLE_" prefix. And an argument type that defines the type of the argument - string/integer/float.

Traces and arguments roles are defined in the trace_protocol_user_definition.h file. You can download it at any time from the ADS cloud platform.

To perform a simple trace without any arguments just write STERNUM_ADS_TRACE(TRACE_CLIENT_DISCONNECTED). To add arguments to the traces please use one of the following argument decelerations.

To declare a string type argument. the first argument is the argument role type, the second argument is the maximum length of the string to be collected (without a null terminator byte) and the last argument is the string itself which can be a literal or a pointer variable.

  • ARGUMENT_STRING(ARG_ROLE_*, MAX_SIZE, ARG_VALUE)

To declare a blob type argument. the first argument is the argument role type, the second argument is the amount of bytes to be collected and the last argument is the blob itself which can be a literal or a pointer variable.

  • ARGUMENT_BLOB(ARG_ROLE_*, SIZE, ARG_VALUE)

The following declares an integer/float/pointer type arguments. the first argument is the argument role type, the second argument is the argument value itself which can be a literal or a variable.

  • ARGUMENT_INTEGER(ARG_ROLE_*, ARG_VALUE)
  • ARGUMENT_UINTEGER(ARG_ROLE_*, ARG_VALUE)
  • ARGUMENT_POINTER(ARG_ROLE_*, ARG_VALUE)
  • ARGUMENT_FLOAT(ARG_ROLE_*, ARG_VALUE)

Here are some examples for using the tracing API

  1. Performing a trace with an integer argument. STERNUM_ADS_TRACE(TRACE_CLIENT_DISCONNECTED, ARGUMENT_UINTEGER(ARG_ROLE_COUNT, count));
  2. Performing a trace with a string argument. STERNUM_ADS_TRACE(TRACE_TASK_STARTED, ARGUMENT_STRING(ARG_ROLE_NAME, 256, taskName));
  3. Performing a trace with a blob argument. STERNUM_ADS_TRACE(TRACE_IMPLANTABLE_IDENTIFICATION, ARGUMENT_BLOB(ARG_ROLE_ID, 16, implantableIDBuffer));
  4. Performing a trace with a multiple arguments. STERNUM_ADS_TRACE(TRACE_IMPLANTABLE_IDENTIFICATION, ARGUMENT_BLOB(ARG_ROLE_ID, 16, implantableIDBuffer), ARGUMENT_UINTEGER(ARG_ROLE_COUNT, count), ARGUMENT_STRING(ARG_ROLE_NAME, 256, taskName));
Parameters
TRACEA trace event type defining the purpose of the trace.
...A variable argument list as described above.
Note
Each argument role type(ARG_ROLE_*) must be used once under the same trace.
Traces with malformed arguments will be sent if possible with all of the valid arguments up to the malformed one. An indicative error will be returned.
The maximum trace size is 64KB.
Thread-safe
Returns
Possible return values: STERNUM_CODE_SUCCESS STERNUM_CODE_NOT_INITIALIZED STERNUM_CODE_INVALID_POINTER STERNUM_CODE_UNSUPPORTED_ARGUMENT_SIZE STERNUM_CODE_OUT_OF_MEMORY STERNUM_CODE_UNSUPPORTED_ARGUMENT_TYPE STERNUM_CODE_UNSUPPORTED_ARGUMENT_ROLE_TYPE STERNUM_CODE_MUTEX_OPERATION_FAILURE

◆ STERNUM_ADS_TRACE_ERROR

#define STERNUM_ADS_TRACE_ERROR (   error_code,
  message 
)    trace_error(error_code, message, __FILE__, __LINE__)

Macro for convenient error tracing with file and line information.

Note
To use this macro, ensure that your operating system supports the FILE and LINE macros.

Example usage:

STERNUM_ADS_TRACE_ERROR(500, "Memory fault");
#define STERNUM_ADS_TRACE_ERROR(error_code, message)
Macro for convenient error tracing with file and line information.
Definition: sternum_trace_api.h:175

◆ STERNUM_ADS_TRACEF

#define STERNUM_ADS_TRACEF (   TRACE,
  ARG_ROLE,
  MAX_LENGTH,
  FORMAT,
  ... 
)    sternum_trace_string_format(TRACE, ARG_ROLE, MAX_LENGTH, FORMAT, ## __VA_ARGS__)

An API to perform ADS traces that are string based only. Please read STERNUM_ADS_TRACE documentation first to learn the trace API basics.

Here is an example for such usage: STERNUM_ADS_TRACEF(TRACE_TASK_STARTED, MESSAGE, 256, "Task %s was started at %d", name, time);

Parameters
TRACEA trace event type defining the purpose of the trace.
ARG_ROLEA argument role type defining the purpose of the argument.
FORMATThe format to follow by the when constructing the output. Please go to https://linux.die.net/man/3/printf to learn more on the format structure.
...A variable argument list containing the variables to be formatted.
Note
Only one argument is allowed in this function.
Traces with malformed arguments will be sent if possible. An indicative error will be returned.
Thread-safe
Returns
Possible return values: STERNUM_CODE_SUCCESS STERNUM_CODE_NOT_INITIALIZED STERNUM_CODE_INVALID_POINTER STERNUM_CODE_OUT_OF_MEMORY STERNUM_CODE_MUTEX_OPERATION_FAILURE