BGAPI Trace#

sli_bgapi_trace_message_type_t#

sli_bgapi_trace_message_type_t

Specifies the full type of a BGAPI message.

sli_bgapi_trace_init#

void sli_bgapi_trace_init (void )

Initialize BGAPI tracing.

sli_bgapi_trace_output_message#

void sli_bgapi_trace_output_message (sli_bgapi_trace_message_type_t type, uint32_t header, const void * data)

Output a BGAPI message to the trace channel.

sli_bgapi_trace_log_custom_message#

size_t sli_bgapi_trace_log_custom_message (const void * buffer, size_t buffer_length)

Output a custom log message to the trace channel.

This function is intended as a debugging helper for components that implement BGAPI classes/devices or otherwise contribute to the processing of BGAPI commands or events. Such components can use this function to log arbitrary messages so that they can be decoded and displayed in the right sequence with respect to the BGAPI commands, responses, and events.

No special formatting of the log message is required by this function, as the bytes of the custom message are written as-is to the RTT stream in the sl_bgapi_debug_evt_trace_custom_message event of the BGAPI Debug Device. The BGAPI Trace decoder tool bgapi_trace treats the message as a bytearray and prints it out. Typically the message is a human-readable string intended for a developer to read, but callers are free to output some binary data as well. This may be useful if the RTT stream is read with a custom tool, as outputting binary is more efficient than formatting data to a string on the device.

The maximum length of the custom message is limited by the 255-byte limit of the bytearray and the maximum total BGAPI payload size defined by SL_BGAPI_MAX_PAYLOAD_SIZE. The practical limit is typically 250 bytes. Messages longer than this are truncated to fit the BGAPI message payload size. The function returns the number of bytes that were successfully output so that the caller can detect truncation.

Returns

• The number of bytes that were successfully output. If BGAPI Trace is currently stopped (see sli_bgapi_trace_start() and sli_bgapi_trace_stop()), the function returns 0.

sli_bgapi_trace_start#

void sli_bgapi_trace_start (void )

Start the BGAPI Trace.

This function is not used by normal applications. In the default configuration the BGAPI Trace will start automatically at application initialization time so that all BGAPI messages get traced. To avoid the RTT writes from blocking the application execution, something on the host computer side needs to read the RTT buffer. This may be inconvenient in situations where the user would like to use one application image for both a normal run where RTT is not read, and for taking debug traces using BGAPI Trace.

To facilitate using one image for both normal runs and for tracing, special applications (typically for example a test application used in automated testing) may define SLI_BGAPI_TRACE_DISABLE_AUTO_START as a global #define macro when building the application. When that macro is defined, the BGAPI Trace is not started automatically and the application can run normally even without anything reading RTT. When the application wants to start tracing in this configuration, it can do so by calling this function sli_bgapi_trace_start().

Use sli_bgapi_trace_stop() to stop the BGAPI Trace if needed.

sli_bgapi_trace_stop#

void sli_bgapi_trace_stop (void )

Stop the BGAPI Trace.

This function is not used by normal applications. See sli_bgapi_trace_start() for a description of special situations where this function might be useful.

sli_bgapi_trace_sync#

void sli_bgapi_trace_sync (void )

Synchronize BGAPI Trace with the host.

This function sends a sync event to the host and blocks until the host connects, i.e. until the RTT buffer becomes empty. The BGAPI Trace uses the RTT buffer in blocking mode. As a consequence, if the host doesn't read the RTT buffer, it becomes full at some point depending on the buffer size and the application will be blocked until the host starts reading. This unpredictable behavior can be prevented by calling this function at a planned spot, e.g. at init.