Introduction

This section describes the various tools used in conjunction with System Controller Firmware (SYSFW)

Tool requirements on host PC

The tools mentioned are implemented using python and needs python version 3.x
Refer to the page, Python3 , to install python and the required python packages on your PC.

Important files and folders

Folder/Files	Description
${SDK_INSTALL_PATH}/tools/bin2c/
bin2c.py	Tool to convert a binary file to a C array of hexadecimals
${SDK_INSTALL_PATH}/tools/sysfw/boardcfg/
sysfw_boardcfg_validator.py	Python script which validates the boardcfg. Used internally in the boardcfg makefile
${SDK_INSTALL_PATH}/tools/sysfw/trace_parser/
sysfw_trace_parser.py	Python script which decodes SYSFW log file
${SDK_INSTALL_PATH}/tools/sysfw/secure_debug/
debug_unlock_x509_cert_gen.py	Python script to generate X509 certificate for runtime JTAG debug unlock in HS devices

SYSFW Board Config Generation

SYSFW Board Config is a SOC specific configuration data regarding the various system attributes controlled by the SYSFW. These include resources, power and clock, security etc. This configuration is sent to SYSFW during boot time. The default configuration is stored in source/drivers/sciclient/sciclient_default_boardcfg/{SOC}/

Resource Management BoardCfg - sciclient_defaultBoardcfg_rm.c
Power Management BoardCfg - sciclient_defaultBoardcfg_pm.c
Security BoardCfg - sciclient_defaultBoardcfg_security.c
Default Boardcfg - sciclient_defaultBoardcfg.c

For sending it to SYSFW, these files are converted to hex arrays. We use the bin2c.py python script to do this. This is done internally in the boardcfg makefile. If we change the boardcfg in the above mentioned files, run the following command to generate the hex array header files

cd ${SDK_INSTALL_PATH}

make -s -C tools/sysfw/boardcfg SOC=am62dx

Once these header files are generated, rebuild the libraries by doing

cd ${SDK_INSTALL_PATH}

make -s libs

After this, make sure to rebuild the secondary bootloader (SBL) applications. You can do this by

cd ${SDK_INSTALL_PATH}

make -s sbl

TIFS and DM Trace Enable

The TIFS and DM logging system uses board configuration to control where logs are sent (trace destinations) and what components generate logs (trace sources).

Default Configuration:

trace_dst_enables = TISCI_BOARDCFG_TRACE_DST_UART0 | TISCI_BOARDCFG_TRACE_DST_ITM | TISCI_BOARDCFG_TRACE_DST_MEM (UART, CCS Console, and Memory destinations enabled)
trace_src_enables = TISCI_BOARDCFG_TRACE_SRC_USER (USER source enabled)
With these defaults, DM R5 application logs (from Sciserver, Sciclient Direct, and IPC) will appear on all destinations, i.e WKUP UART, CCS Console, and memory buffer
TIFS logs and DM PM/RM logs remain disabled by default

To enable all TIFS and DM traces, change the #undef SYSFW_TRACE_ENABLE to #define SYSFW_TRACE_ENABLE in source/drivers/device_manager/sciclient.h. Then rebuild the boardcfg as explained in the SYSFW Board Config Generation section. This enables all the following trace sources and destinations -

Trace Destinations (trace_dst_enables): Controls where logs are output. (All enabled by default)
- TISCI_BOARDCFG_TRACE_DST_UART0 - WKUP UART output
- TISCI_BOARDCFG_TRACE_DST_MEM - Memory buffer
- TISCI_BOARDCFG_TRACE_DST_ITM - CCS Console
Trace Sources (trace_src_enables): Controls which components generate logs
- TISCI_BOARDCFG_TRACE_SRC_PM - Power Management traces
- TISCI_BOARDCFG_TRACE_SRC_RM - Resource Management traces
- TISCI_BOARDCFG_TRACE_SRC_SEC - Security traces
- TISCI_BOARDCFG_TRACE_SRC_BASE - Baseport traces
- TISCI_BOARDCFG_TRACE_SRC_USER - User-level traces (DM R5 application)
- TISCI_BOARDCFG_TRACE_SRC_SUPR - Supervisor-level traces

To selectively enable specific traces instead of all, follow these steps:

Locate board configuration file:
- Path: source/drivers/sciclient/sciclient_default_boardcfg/{SOC}/sciclient_defaultBoardcfg.c
- Edit the .debug_cfg section in the tisci_boardcfg structure
Configure trace settings based on your needs:

In the #else block (when SYSFW_TRACE_ENABLE is not defined), replace the default values with your desired configuration:

Example 1: Enable DM PM/RM logs and DM application logs to both UART and memory
.trace_dst_enables = TISCI_BOARDCFG_TRACE_DST_UART0 |

TISCI_BOARDCFG_TRACE_DST_MEM,

.trace_src_enables = TISCI_BOARDCFG_TRACE_SRC_PM |

TISCI_BOARDCFG_TRACE_SRC_RM |

TISCI_BOARDCFG_TRACE_SRC_USER,

Example 2: Enable TIFS security logs to UART
.trace_dst_enables = TISCI_BOARDCFG_TRACE_DST_UART0,

.trace_src_enables = TISCI_BOARDCFG_TRACE_SRC_SEC |

TISCI_BOARDCFG_TRACE_SRC_BASE,

Example 3: Disable all logs
.trace_dst_enables = 0,

.trace_src_enables = 0,
Rebuild and reflash board configuration:
- Follow the instructions in SYSFW Board Config Generation section to regenerate boardcfg
- Reflash the SBL with the updated board configuration
- The DM firmware will automatically load the new configuration at runtime (no DM firmware rebuild needed - only SBL reflash required)

Viewing Trace Output

Depending on the destination flags enabled, logs can be viewed from different locations:

UART Destination (TISCI_BOARDCFG_TRACE_DST_UART0):

DM logs: Available at WKUP UART (/dev/ttyUSB2 on Linux)
TIFS logs: Available at UART1 (/dev/ttyUSB1 on Linux)
Terminal settings: 115200 baud, 8N1 (8 data bits, no parity, 1 stop bit)
Recommended tool: minicom, putty, or any serial terminal

Memory Destination (TISCI_BOARDCFG_TRACE_DST_MEM):

Logs stored in a memory buffer
Memory buffer location: See TIFS memory buffer documentation

ITM Destination (TISCI_BOARDCFG_TRACE_DST_ITM):

Logs appear in CCS Console when debugging with Code Composer Studio

SYSFW Trace Parser

After taking the TIFS logs as in above section, it can be parsed using the sysfw_trace_parser.py script. This will decode the hex trace values and gives readable text file as output. Using this, the user can interpret the log and debug.

Run the python script on the Windows command prompt (cmd.exe) or Linux bash shell with the required arguments to parse the TIFS logs.

cd ${SDK_INSTALL_PATH}/tools/sysfw/trace_parser

python sysfw_trace_parser.py --log_file ${SYSFW_LOG_FILE} --output_file ${TRACE_OUTPUT_TEXT_FILE}

To know about the arguments, run the script with help option.

python sysfw_trace_parser.py --help

For more details, refer system firmware trace layer documentation

SYSFW Secure Debug Certificate Generation

On HS-SE devices, the JTAG port is closed by default. If required, the user can open the JTAG port and debug the cores. This can be done by sending a TISCI message with a signed X509 certificate authorizing the debug.

The debug_unlock_x509_cert_gen.py script generate the debug certificate with required debug extensions and save it as a hex header file. The user can include this hex header in their application and send the certificate from a valid host to the TIFS core via the TISCI message.

Run the python script on the Windows command prompt (cmd.exe) or Linux bash shell with the required arguments to generate the debug certificate.

C:> cd ${SDK_INSTALL_PATH}/tools/sysfw/secure_debug
 
C:> python debug_unlock_x509_cert_gen.py --help
 
    usage: debug_unlock_x509_cert_gen.py [-h] -s SOC [--key KEY] [--swrv SWRV] [--socUID SOCUID] [--debugtype DEBUGTYPE] [--coreDbgEn COREDBGEN]
                                [--coreDbgSecEn COREDBGSECEN]
 
    Generates a x509 debug certificate for run time JTAG debug unlock in HS device
 
    options:
    -h, --help                      show this help message and exit
    -s SOC, --soc SOC               SOC for which debug certificate has to be created. Supported SOCs: am62ax
    --key KEY                       File with signing key inside it. Optional
    --swrv SWRV                     Software revision number. Required if you have specified a non-zero debug certificate revision in the secure boardcfg
    --socUID SOCUID                 SOC unique ID. Required if board config does not allow wild card JTAG unlock
    --debugtype DEBUGTYPE           Debug type. Default to DBG_FULL_ENABLE
    --coreDbgEn COREDBGEN           List of cores for which non-secure debug has to be enabled. Optional
    --coreDbgSecEn COREDBGSECEN     List of cores for which secure debug has to be enabled. Optional

For more details on the TISCI message and the argument values to be used, refer system firmware documentation
For example invoke the script as,

C:> cd ${SDK_INSTALL_PATH}/tools/sysfw/secure_debug

C:> python debug_unlock_x509_cert_gen.py --soc=am62ax

Also check the SDK example, Runtime debug unlock Example

Table of Contents

Introduction

Tool requirements on host PC

Important files and folders

SYSFW Board Config Generation

TIFS and DM Trace Enable

Viewing Trace Output

SYSFW Trace Parser

SYSFW Secure Debug Certificate Generation