Debug

Features Supported

  • APIs to log strings to the selected console

  • APIs to assert if a expression evaluates to 0

    • Before asserting, it will log the file and line number to console

  • Ability to disable assert’s and logging via a pre-processor define

  • The following console options are supported

    • Log to CCS IDE console via JTAG

    • Log to UART terminal

  • SysCfg support for below,

    • SysCfg can be used to select the log console

    • When UART log is selected, SysCfg allows to select the UART instance and its properties (baud rate etc) to use.

    • SysCfg option to select UART for remote core trace when uart log is enabled. This enables the UART instance to be not closed as part of closing all drivers. Essentially used for Device Mangaer applications to enable Device Mangaer trace logs over UART.

    • SysCfg option to enable SysFw trace. When SysFw UART trace option is selected, SysCfg allows to select UART instance and its pinmuxing.

    • SysCfg option to enable shared memory reader task.

  • APIs to read line as string and/or format input in scanf style from UART console.

Features NOT Supported

  • Log APIs should not be called from ISR context. When called in ISR the APIs have no effect.

Important Usage Guidelines

Shared memory logging

  • The core on which the shared memory reader is enabled needs to run FreeRTOS since it needs task support.

  • The core on which the shared memory reader is enabled, the option to use shared memory writer is ignored.

  • When shared memory writer/reader is enabled, a shared memory section is used to write and read the strings for all the cores,

    • When SysCfg is used, the array representing this shared memory is generated in the file ti_dpl_config.c.

    • Place the section attributed to this array in the linker command file for each core such that all cores point to the same memory address for this section.

    • And this memory section should be marked as non-cache in the MPU/MMU entry for each core (see MpuP_arm_v7 and MmuP_arm_v8).

  • It is recommended to enable UART logging and shared memory reader on one “main” core and other core’s should enable the shared memory writer.

  • The memory used for logging is limited per core. If the writer is faster than reader, then the writer drops the characters to be printed.

  • To change the size of the log buffer, change the value of DebugP_SHM_LOG_SIZE in source/kernel/dpl/DebugP.h.

UART logging

  • Make sure the selected UART driver is opened for the logs to be output to UART.

    • When enabled via SysCfg, calling the function Drivers_open opens and initializes the UART for logging.

Other guidelines

  • Log and assert APIs should not be called from ISR context.

  • The assert and logging APIs are task or thread safe, i.e they can be called from multiple tasks without the output getting mixed.

  • The cores on which CCS or UART console logging is enabled can use either NORTOS or FreeRTOS.

  • If the UART console is used for remote core trace and needs to be opened forever in a FreeRtos application, then the “ Remote Core Trace (UART) “ option in the sysconfig can be enabled. So, the uart driver will not get closed when common Drivers_close function is called.

Example Usage

Include the below file to access the APIs,

Example usage for assert:

Example usage for logs:

Example usage for scanf,

API Reference

Debug log zones

DebugP_LOG_ZONE_ALWAYS_ON

Flag for always on zone, enabled by default and recommend to not switch off.

DebugP_LOG_ZONE_ERROR

Flag for error zone.

DebugP_LOG_ZONE_WARN

Flag for warning zone.

DebugP_LOG_ZONE_INFO

Flag for info zone.

Compile time log and assert enable, disable

DebugP_ASSERT_ENABLED

Pre-processor define to enable or disable DebugP assert’s.

Set to 0 to disable assert checks and recompile all code where this file is included.

DebugP_LOG_ENABLED

Pre-processor define to enable or disable DebugP log’s.

Set to 0 to disable logging and recompile all code where this file is included.

Debug assert APIs

DebugP_assert(expression)

Function to call for assert check.

If expresion evaluates to 0 then the function disable’s interrupt and loops forever. It logs the file name and line number before looping forever. User should fix their code and run again.

This API should not be called within ISR context.

Parameters:

  • expression – [in] expression to check for.

DebugP_assertNoLog(expression)

Function to call for assert check, no logs are printed.

Same as DebugP_assert except no logs are printed. This can be used in very early initialization code and in ISRs.

During very early initialization and inside ISRs asserts with log will not work.

Parameters:

  • expression – [in] expression to check for.

Debug log APIs

DebugP_log(format, ...)

Function to log a string to the enabled console.

This API should not be called within ISR context.

Parameters:

  • format – [in] String to log

DebugP_logError(format, ...)

Function to log a string to the enabled console, for error zone.

This API should not be called within ISR context.

Parameters:

  • format – [in] String to log

DebugP_logWarn(format, ...)

Function to log a string to the enabled console, for warning zone.

This API should not be called within ISR context.

Parameters:

  • format – [in] String to log

DebugP_logInfo(format, ...)

Function to log a string to the enabled console, for info zone.

This API should not be called within ISR context.

Parameters:

  • format – [in] String to log

Defines

DebugP_SHM_LOG_SIZE

size of shared memory log for a CPU

DebugP_MEM_LOG_SIZE

size of memory log for a CPU

DebugP_SHM_LOG_IS_VALID

Flag to indicate shared memory buffer is valid.

Written by the writer after it has initialized and cleared by the reader after reader has initialized

UNSIGNED_INTEGERVAL_TWO

Macro defines the value of two

UNSIGNED_INTEGERVAL_THREE

Macro defines the value of three

CARRIAGE_RETURN_ASCII

Macro defines the ascii value of carriage return

Functions

void _DebugP_assert(int32_t expression, const char *file, const char *function, int32_t line, const char *expressionString)

Actual function that is called for assert’s by DebugP_assert.

void _DebugP_assertNoLog(int32_t expression)

Actual function that is called for assert’s by DebugP_assertNoLog.

void _DebugP_logZone(uint32_t logZone, char *format, ...)

Function to log a string to the enabled console for a given zone.

This API should not be used directly, instead DebugP_log, DebugP_logError, DebugP_logWarn, DebugP_logInfo should be used.

Parameters:

  • logZone – [in] Value from DebugP_LOG_ZONE

  • format – [in] String ot log

uint32_t DebugP_logZoneEnable(uint32_t logZoneMask)

Enable log zones.

Parameters:

logZoneMask – [in] Mask of values from DebugP_LOG_ZONE

Returns:

old value of zone mask, can be used to restore original state using DebugP_logZoneRestore

uint32_t DebugP_logZoneDisable(uint32_t logZoneMask)

Disable log zones.

Parameters:

logZoneMask – [in] Mask of values from DebugP_LOG_ZONE

Returns:

old value of zone mask, can be used to restore original state using DebugP_logZoneRestore

void DebugP_logZoneRestore(uint32_t logZoneMask)

Restire zone mask returned from DebugP_logZoneDisable or DebugP_logZoneEnable.

Parameters:

logZoneMask – [in] Mask of values from DebugP_LOG_ZONE

void DebugP_shmLogWriterInit(DebugP_ShmLog *shmLog, uint16_t selfCoreId)

Initialize shared memory log writer for this core.

Parameters:

  • shmLog – [in] Address of shared memory where the writer should write logs to

  • selfCoreId – [in] ID of core on which this API is called, this is used to add a core name prefix string to each log line, see CSL_CoreID

void DebugP_shmLogWriterPause(void)

Pauses shared memory log writer for this core.

void DebugP_shmLogWriterResume(void)

Resumes shared memory log writer for this core.

void DebugP_shmLogWriterPutChar(char character)

Write a character to shared memory log.

If shared memory log buffer is full, nothing is written and character gets “dropped”

Internally, the charaxter is stored in a local line buffer and line buffer is flushed to shared memory only when a ‘\n’ character is put.

Parameters:

character – [in] character to write

void DebugP_uartLogWriterPutChar(char character)

Write a character to UART terminal. 

   Make sure the UART to use is set via DebugP_uartSetDrvIndex().
   When using SysConfig this is done when UART debug log is enabled.
Parameters:

character – [in] character to write

void DebugP_shmLogReaderInit(DebugP_ShmLog *shmLog, uint16_t numCores)

Initialize log reader to read from shared memory and log to console via DebugP_log.

The parameter shmLog is a array and is indexed using core ID as defined by CSL_CoreID

Parameters:

  • shmLog – [in] Array of addresses of shared memory where the reader should read from.

  • numCores – [in] Number of entries in the shmLog array. Typically CSL_CORE_ID_MAX

void DebugP_shmLogRead(void)

Reads logs from shared memory.

User needs to invoke this API periodically to get continous logs from Shared memory. Used when Shared Memory log Reader is enabled for nortos application.

void DebugP_memLogWriterInit(uint16_t selfCoreId)

Initialize log write to write to memory trace buffer.

Used when IPC with Linux is enabled OR ROV based logging is enabled

Parameters:

selfCoreId – [in] ID of core on which this API is called, this is used to add a core name prefix string to each log line, see CSL_CoreID

void DebugP_memLogWriterPause(void)

Pauses memory trace log for this core.

void DebugP_memLogWriterResume(void)

Resumes memory trace log for this core.

void DebugP_memLogWriterPutChar(char character)

Write a character to trace buffer.

Used when IPC with Linux is enabled OR ROV based logging is enabled

Internally, the charaxter is stored in a local line buffer and line buffer is flushed to UART only when a ‘\n’ character is put.

Parameters:

character – [in] character to write

void DebugP_uartSetDrvIndex(uint32_t uartDrvIndex)

Set UART driver index to use for character read and write form UART. 

   Make sure the UART to use is set via DebugP_uartSetDrvIndex().
   When using SysConfig this is done when UART debug log is enabled.
Parameters:

uartDrvIndex – [in] UART driver instance index to use

int32_t DebugP_scanf(char *format, ...)

Read a formatted string from the selected UART driver. 

   This function returns when a "new line" or "enter" is input on the console.

   Make sure the UART to use is set via DebugP_uartSetDrvIndex().
   When using SysConfig this is done when UART debug log is enabled.
Returns:

SystemP_SUCCESS on sucessful read

Returns:

SystemP_FAILURE on failure

int32_t DebugP_readLine(char *lineBuf, uint32_t bufSize)

Read a string from the selected UART driver. 

   This function returns when a "new line" or "enter" is input on the console.

   Make sure the UART to use for reading is set via DebugP_uartSetDrvIndex.
   When using SysConfig this is done when UART debug log is enabled.

   A '\0' is always put at the end.
Parameters:

  • lineBuf – [in] Buffer into which the string is read

  • bufSize – [in] Size of the buffer in which to read, if buffer is not enough, input is truncated.

Returns:

SystemP_SUCCESS on sucessful read

Returns:

SystemP_FAILURE on failure

struct DebugP_ShmLog
#include <DebugP.h>

Data structure describing log in shared memory.

Public Members

uint32_t isValid
uint32_t rdIndex
uint32_t wrIndex
uint32_t rsv
uint8_t buffer[DebugP_SHM_LOG_SIZE]