AM64x MCU+ SDK  10.00.00
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
    • Log to shared memory, can be viewed via the CPU on which log reader is enabled
    • Log to CPU local memory, can be viewed via ROV in CCS or when Linux is enabled via Linux kernel debugfs
  • Ability to read logs from shared memory and output to selected console.
  • 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 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, 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.
  • 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.
    Note
    When shared memory reader is enabled for a nortos application user needs to invoke DebugP_shmLogRead API to read logs from shared memory. DebugP_shmLogRead will read the log once and exit thus application needs to call this API periodically in-order to gather continous logs.

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.

Memory 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 or shared memory writer is enabled can use either NORTOS or FreeRTOS.

Example Usage

Include the below file to access the APIs,

#include <stdio.h>

Example usage for assert,

void *addr = NULL;
/* This will assert when addr is NULL */

Example usage for logs,

uint32_t value = 10;
char *str = "Hello, world !!!";
/* use snprintf to format the string and then call the logging function */
DebugP_log("This is %s and value = %d",
str,

Example usage for scanf,

uint32_t value32;
DebugP_log("Enter a 32b number\r\n");
value32 = 0;
DebugP_scanf("%d", &value32);
DebugP_log("32b value = %d\r\n", value32);

Example snippet to show linker command file placement of the shared memory log section generated via SysCfg,

SECTIONS
{
/* this is used when Debug log's to shared memory are enabled, else this is not used */
.bss.log_shared_mem (NOLOAD) : {} > LOG_SHM_MEM
}
MEMORY
{
/* shared memories that are used by all cores */
/* On M4F,
* - By default MSMC RAM is not accessible to M4F, a RAT entry is needed to make it
* accessible on M4F
* - So make sure there is a RAT entry which has a 1:1 mapping from 0x70000000 to 0x70200000
*/
/* On R5F,
* - make sure there is a MPU entry which maps below regions as non-cache
*/
LOG_SHM_MEM : ORIGIN = 0x701D4000, LENGTH = 0x00004000
}

API

APIs for Debug log's and assert's

addr
uint64_t addr
Definition: csl_udmap_tr.h:3
str
char str[32]
Definition: tisci_core.h:1
DebugP_log
#define DebugP_log(format,...)
Function to log a string to the enabled console.
Definition: DebugP.h:225
DebugP_scanf
int32_t DebugP_scanf(char *format,...)
Read a formatted string from the selected UART driver.
value
uint32_t value
Definition: tisci_otp_revision.h:2
DebugP.h
DebugP_assert
#define DebugP_assert(expression)
Function to call for assert check.
Definition: DebugP.h:177