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_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
	)

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

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_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");

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

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_CODE_SUCCESS STERNUM_CODE_NOT_INITIALIZED STERNUM_CODE_INVALID_POINTER STERNUM_CODE_OUT_OF_MEMORY STERNUM_CODE_MUTEX_OPERATION_FAILURE