Sternum trace API. More...

#include <stdbool.h>
#include <stdint.h>
#include "sternum_sdk/api/sternum_error_codes.h"
#include "sternum_sdk/private/trace_dynamic.h"
#include "sternum_sdk/user/trace_protocol_user_definition.h"

Functions
void	trace_battery_health (unsigned int capacity_percent, unsigned int voltage_mV)
	Trace battery health. More...

void	trace_coredump (const char *message)
	Trace coredump after crash was detected. 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 ()
	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_db)
	Trace signal strength. More...

Macros
#define	STERNUM_ADS_TRACE(TRACE, ...) sternum_trace_dynamic(TRACE, ##__VA_ARGS__, END_OF_ARGUMENTS)
	A general API to transmit Sternum Platform traces. More...

#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 Sternum Platform traces that are string based only. More...

#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

Sternum trace API.

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_coredump()

void trace_coredump ( const char * message )

Trace coredump after crash was detected.

Note: Zephyr SDK package provides the functionality of automatically collecting and sending coredump. This trace should not be used manually when using the Zephyr SDK package.

Parameters

message - contains coredump.

◆ 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 ( )

Trace firmware update finished.

◆ 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_version	The version of the firmware being updated.
firmware_hash	The hash of the firmware being updated.
hash_algorithm	The 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_db
	)

Trace signal strength.

Parameters

communication_type	- code describing communication type [unsigned int]
signal_strength	- signal strength in decibels (dB)

Macro Definition Documentation

◆ ARGUMENT_BLOB

#define ARGUMENT_BLOB	(	ARG_ROLE,
		SIZE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)BLOB_TYPE, (unsigned int)SIZE, (uint8_t*)(ARG_VALUE)

◆ ARGUMENT_FLOAT

#define ARGUMENT_FLOAT	(	ARG_ROLE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)FLOAT_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)

◆ ARGUMENT_INTEGER

#define ARGUMENT_INTEGER	(	ARG_ROLE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)SIGNED_INTEGER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)

◆ ARGUMENT_POINTER

#define ARGUMENT_POINTER	(	ARG_ROLE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)POINTER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)

◆ ARGUMENT_STRING

#define ARGUMENT_STRING	(	ARG_ROLE,
		MAX_SIZE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)STRING_TYPE, (unsigned int)MAX_SIZE, (char*)(ARG_VALUE)

◆ ARGUMENT_UINTEGER

#define ARGUMENT_UINTEGER	(	ARG_ROLE,
		ARG_VALUE
	)	(unsigned int)ARG_ROLE, (unsigned int)UNSIGNED_INTEGER_TYPE, (unsigned int)sizeof(ARG_VALUE), (ARG_VALUE)

◆ BLOB_TYPE

#define BLOB_TYPE (4 | POINTER_DEREFERENCE_INDICATOR)

◆ END_OF_ARGUMENTS

#define END_OF_ARGUMENTS 0

◆ FLOAT_TYPE

#define FLOAT_TYPE 2

◆ POINTER_DEREFERENCE_INDICATOR

#define POINTER_DEREFERENCE_INDICATOR 0x8000

◆ POINTER_TYPE

#define POINTER_TYPE 3

◆ SIGNED_INTEGER_TYPE

#define SIGNED_INTEGER_TYPE 1

◆ STERNUM_ADS_TRACE

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

A general API to transmit Sternum Platform traces.

Please note that some development environments will require enabling GNU C extensions.

In order to initialize Sternum Platform tracing, please invoke sternum_sdk_initialize 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 Sternum 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.

Here are some examples for using the tracing API

Performing a trace with an integer argument. STERNUM_ADS_TRACE(TRACE_CLIENT_DISCONNECTED, ARGUMENT_UINTEGER(ARG_ROLE_COUNT, count));
Performing a trace with a string argument. STERNUM_ADS_TRACE(TRACE_TASK_STARTED, ARGUMENT_STRING(ARG_ROLE_NAME, 256, taskName));
Performing a trace with a blob argument. STERNUM_ADS_TRACE(TRACE_IMPLANTABLE_IDENTIFICATION, ARGUMENT_BLOB(ARG_ROLE_ID, 16, implantableIDBuffer));
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

TRACE	A 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_SDK_SUCCESS STERNUM_SDK_NOT_INITIALIZED STERNUM_SDK_INVALID_POINTER STERNUM_SDK_UNSUPPORTED_ARGUMENT_SIZE STERNUM_SDK_OUT_OF_MEMORY STERNUM_SDK_UNSUPPORTED_ARGUMENT_TYPE STERNUM_SDK_UNSUPPORTED_ARGUMENT_ROLE_TYPE STERNUM_SDK_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:

TRACE_ERROR(500, "Memory fault");

◆ 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 Sternum Platform 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, ARG_ROLE_MESSAGE, 256, "Task %s was started at %d", name, time);

Parameters

TRACE	A trace event type defining the purpose of the trace.
ARG_ROLE	A argument role type defining the purpose of the argument.
FORMAT	The 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_SDK_SUCCESS STERNUM_SDK_NOT_INITIALIZED STERNUM_SDK_INVALID_POINTER STERNUM_SDK_OUT_OF_MEMORY STERNUM_SDK_MUTEX_OPERATION_FAILURE

◆ STRING_TYPE

#define STRING_TYPE (5 | POINTER_DEREFERENCE_INDICATOR)

◆ UNSIGNED_INTEGER_TYPE

#define UNSIGNED_INTEGER_TYPE 0

Functions

Macros

Detailed Description

Function Documentation

◆ trace_battery_health()

◆ trace_coredump()

◆ trace_error()

◆ trace_firmware_update_finish()

◆ trace_firmware_update_start()

◆ trace_reboot_reason()

◆ trace_signal_strength_report()

Macro Definition Documentation

◆ ARGUMENT_BLOB

◆ ARGUMENT_FLOAT

◆ ARGUMENT_INTEGER

◆ ARGUMENT_POINTER

◆ ARGUMENT_STRING

◆ ARGUMENT_UINTEGER

◆ BLOB_TYPE

◆ END_OF_ARGUMENTS

◆ FLOAT_TYPE

◆ POINTER_DEREFERENCE_INDICATOR

◆ POINTER_TYPE

◆ SIGNED_INTEGER_TYPE

◆ STERNUM_ADS_TRACE

◆ STERNUM_ADS_TRACE_ERROR

◆ STERNUM_ADS_TRACEF

◆ STRING_TYPE

◆ UNSIGNED_INTEGER_TYPE