AM263Px MCU+ SDK: APIs for Debug log's and assert's

| AM263Px MCU+ SDK 26.00.00 |

Data Structures | Functions | Macros
APIs for Debug log's and assert's
APIs for Driver Porting Layer

## Introduction

For more details and example usage, see Debug

## Data Structures
struct | DebugP_ShmLog
| Data structure describing log in shared memory. More...

## 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. More...
void | _DebugP_assertNoLog (int32_t expression)
| Actual function that is called for assert's by DebugP_assertNoLog. More...
void | _DebugP_logZone (uint32_t logZone, char *format,...)
| Function to log a string to the enabled console for a given zone. More...
uint32_t | DebugP_logZoneEnable (uint32_t logZoneMask)
| Enable log zones. More...
uint32_t | DebugP_logZoneDisable (uint32_t logZoneMask)
| Disable log zones. More...
void | DebugP_logZoneRestore (uint32_t logZoneMask)
| Restire zone mask returned from DebugP_logZoneDisable or DebugP_logZoneEnable. More...
void | DebugP_shmLogWriterInit (DebugP_ShmLog *shmLog, uint16_t selfCoreId)
| Initialize shared memory log writer for this core. More...
void | DebugP_shmLogWriterPreludeEnable ()
| Enable auto prelude for shared memory log writer. More...
void | DebugP_shmLogWriterPreludeDisable ()
| Disable auto prelude for shared memory log writer. More...
void | DebugP_shmLogWriterPutChar (char character)
| Write a character to shared memory log. More...
void | DebugP_uartLogWriterPutChar (char character)
| Write a character to UART terminal. More...
void | DebugP_shmLogReaderInit (DebugP_ShmLog *shmLog, uint16_t numCores)
| Initialize log reader to read from shared memory and log to console via DebugP_log. More...
void | DebugP_shmLogReaderSetChunkSize (uint16_t readChunkSize)
| Set the read chunk size for the shared memory reader. More...
uint16_t | DebugP_shmLogReaderGetChunkSize (void)
| Get the read chunk size for the shared memory reader. More...
void | DebugP_shmLogRead (void)
| Reads logs from shared memory. More...
void | DebugP_memLogWriterInit (uint16_t selfCoreId)
| Initialize log write to write to memory trace buffer. More...
void | DebugP_memLogWriterPutChar (char character)
| Write a character to trace buffer. More...
void | DebugP_uartSetDrvIndex (uint32_t uartDrvIndex)
| Set UART driver index to use for character read and write form UART. More...
int32_t | DebugP_scanf (char *format,...)
| Read a formatted string from the selected UART driver. More...
int32_t | DebugP_readLine (char *lineBuf, uint32_t bufSize)
| Read a string from the selected UART driver. More...

## Macros
#define | DebugP_SHM_LOG_SIZE ((2U*1024U) - 16U)
| size of shared memory log for a CPU More...
#define | DebugP_MEM_LOG_SIZE ( 4*1024U )
| size of memory log for a CPU More...
#define | DebugP_SHM_LOG_IS_VALID (0x12345678U)
| Flag to indicate shared memory buffer is valid. More...
#define | DebugP_SHM_LOG_READER_CHUNK_SIZE_INF UINT16_MAX
| Infinite read chunk size for the shared memory reader. More...
#define | UNSIGNED_INTEGERVAL_TWO (2U)
#define | UNSIGNED_INTEGERVAL_THREE (3U)
#define | CARRIAGE_RETURN_ASCII (13U)

## Debug log zones
#define | DebugP_LOG_ZONE_ALWAYS_ON (0x0001U)
| Flag for always on zone, enabled by default and recommend to not switch off. More...
#define | DebugP_LOG_ZONE_ERROR (0x0002U)
| Flag for error zone. More...
#define | DebugP_LOG_ZONE_WARN (0x0004U)
| Flag for warning zone. More...
#define | DebugP_LOG_ZONE_INFO (0x0008U)
| Flag for info zone. More...

## Compile time log and assert enable, disable
#define | DebugP_ASSERT_ENABLED 1
| Pre-processor define to enable or disable DebugP assert's. More...
#define | DebugP_LOG_ENABLED 1
| Pre-processor define to enable or disable DebugP log's. More...

## Debug assert APIs
#define | DebugP_assert(expression) _DebugP_assert(expression, __FILE__, __FUNCTION__, __LINE__, #expression)
| Function to call for assert check. More...
#define | DebugP_assertNoLog(expression) (_DebugP_assertNoLog(expression))
| Function to call for assert check, no logs are printed. More...

## Debug log APIs
#define | DebugP_log(format, ...) _DebugP_logZone(DebugP_LOG_ZONE_ALWAYS_ON, (char *)format, ##__VA_ARGS__)
| Function to log a string to the enabled console. More...
#define | DebugP_logError(format, ...) _DebugP_logZone(DebugP_LOG_ZONE_ERROR, "ERROR: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)
| Function to log a string to the enabled console, for error zone. More...
#define | DebugP_logWarn(format, ...) _DebugP_logZone(DebugP_LOG_ZONE_WARN, "WARNING: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)
| Function to log a string to the enabled console, for warning zone. More...
#define | DebugP_logInfo(format, ...) _DebugP_logZone(DebugP_LOG_ZONE_INFO, "INFO: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)
| Function to log a string to the enabled console, for info zone. More...

## Macro Definition Documentation

## ◆ DebugP_LOG_ZONE_ALWAYS_ON

#define DebugP_LOG_ZONE_ALWAYS_ON (0x0001U)

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

## ◆ DebugP_LOG_ZONE_ERROR

#define DebugP_LOG_ZONE_ERROR (0x0002U)

Flag for error zone.

## ◆ DebugP_LOG_ZONE_WARN

#define DebugP_LOG_ZONE_WARN (0x0004U)

Flag for warning zone.

## ◆ DebugP_LOG_ZONE_INFO

#define DebugP_LOG_ZONE_INFO (0x0008U)

Flag for info zone.

## ◆ DebugP_SHM_LOG_SIZE

#define DebugP_SHM_LOG_SIZE ((2U*1024U) - 16U)

size of shared memory log for a CPU

## ◆ DebugP_MEM_LOG_SIZE

#define DebugP_MEM_LOG_SIZE ( 4*1024U )

size of memory log for a CPU

## ◆ DebugP_SHM_LOG_IS_VALID

#define DebugP_SHM_LOG_IS_VALID (0x12345678U)

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

## ◆ DebugP_SHM_LOG_READER_CHUNK_SIZE_INF

#define DebugP_SHM_LOG_READER_CHUNK_SIZE_INF UINT16_MAX

Infinite read chunk size for the shared memory reader.

DebugP_shmLogReaderSetChunkSize(DebugP_SHM_LOG_READER_CHUNK_SIZE_INF) will make DebugP_shmLogRead() process the entire shared memory log in one go or until the end of the shared memory log is reached.

## ◆ UNSIGNED_INTEGERVAL_TWO

#define UNSIGNED_INTEGERVAL_TWO (2U)

Macro defines the value of two

## ◆ UNSIGNED_INTEGERVAL_THREE

#define UNSIGNED_INTEGERVAL_THREE (3U)

Macro defines the value of three

## ◆ CARRIAGE_RETURN_ASCII

#define CARRIAGE_RETURN_ASCII (13U)

Macro defines the ascii value of carriage return

## ◆ DebugP_ASSERT_ENABLED

#define DebugP_ASSERT_ENABLED 1

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

#define DebugP_LOG_ENABLED 1

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.

## ◆ DebugP_assert

#define DebugP_assert | ( |  | expression | ) | _DebugP_assert(expression, __FILE__, __FUNCTION__, __LINE__, #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

#define DebugP_assertNoLog | ( |  | expression | ) | (_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.

## ◆ DebugP_log

#define DebugP_log | ( |  | format,
|  |  | ...
| ) |  | _DebugP_logZone(DebugP_LOG_ZONE_ALWAYS_ON, (char *)format, ##__VA_ARGS__)

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

#define DebugP_logError | ( |  | format,
|  |  | ...
| ) |  | _DebugP_logZone(DebugP_LOG_ZONE_ERROR, "ERROR: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)

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

#define DebugP_logWarn | ( |  | format,
|  |  | ...
| ) |  | _DebugP_logZone(DebugP_LOG_ZONE_WARN, "WARNING: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)

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

#define DebugP_logInfo | ( |  | format,
|  |  | ...
| ) |  | _DebugP_logZone(DebugP_LOG_ZONE_INFO, "INFO: %s:%d: " format, __FUNCTION__, __LINE__, ##__VA_ARGS__)

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

## Function Documentation

## ◆ _DebugP_assert()

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.

## ◆ _DebugP_assertNoLog()

void _DebugP_assertNoLog | ( | int32_t | expression | ) |

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

## ◆ _DebugP_logZone()

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

## ◆ DebugP_logZoneEnable()

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

## ◆ DebugP_logZoneDisable()

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

## ◆ 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

## ◆ DebugP_shmLogWriterInit()

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

## ◆ DebugP_shmLogWriterPreludeEnable()

void DebugP_shmLogWriterPreludeEnable | ( |  | ) |

Enable auto prelude for shared memory log writer.

## ◆ DebugP_shmLogWriterPreludeDisable()

void DebugP_shmLogWriterPreludeDisable | ( |  | ) |

Disable auto prelude for shared memory log writer.

This is useful for creating structured logs

## ◆ DebugP_shmLogWriterPutChar()

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

## ◆ DebugP_uartLogWriterPutChar()

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

## ◆ DebugP_shmLogReaderInit()

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

A single invocation processes up to DebugP_shmLogReaderGetChunkSize() log lines

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

## ◆ DebugP_shmLogReaderSetChunkSize()

void DebugP_shmLogReaderSetChunkSize | ( | uint16_t | readChunkSize | ) |

Set the read chunk size for the shared memory reader.

Parameters

  readChunkSize | [in] The read chunk size in bytes.

## ◆ DebugP_shmLogReaderGetChunkSize()

uint16_t DebugP_shmLogReaderGetChunkSize | ( | void |  | ) |

Get the read chunk size for the shared memory reader.

Returns
  The read chunk size in bytes.

## ◆ DebugP_shmLogRead()

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.

## ◆ DebugP_memLogWriterInit()

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

## ◆ DebugP_memLogWriterPutChar()

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

## ◆ DebugP_uartSetDrvIndex()

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

## ◆ DebugP_scanf()

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
  SystemP_FAILURE on failure

## ◆ DebugP_readLine()

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
  SystemP_FAILURE on failure