SYSFW Tools

Table of Contents

• Introduction
• Tool requirements on host PC
• Important files and folders
• SYSFW Board Config Generation
  • SYSFW Trace Enable
  • SYSFW Trace Parser
• SYSFW Secure Debug Certificate Generation

Note

To see the exact sequence of steps in which boardcfg generation is done, see the makefile inside the ${SDK_INSTALL_PATH}/tools/sysfw/boardcfg/ folder.

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_defaultBoardCfg/{SOC}/

• Resource Management BoardCfg - sciclient_defaultBoardCfg_rm.c
• Power Management BoardCfg - sciclient_defaultBoardCfg_pm.c
• Security BoardCfg - sciclient_defaultBoardCfg_security.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=am62ax

• 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

SYSFW Trace Enable

To enable the SYSFW trace, change the #undef SYSFW_TRACE_ENABLE to #define SYSFW_TRACE_ENABLE on source/drivers/device_manager/sciclient.h. Then rebuild the boardcfg as explained in the above section.

The DM firmware log shall be available at the wakeup UART (/dev/ttyUSB2). Connect to the UART through minicom to see the logs.

The TIFS logs shall be available at the UART1 (/dev/ttyUSB1). Alternatively it can be obtained from the TIFS memory address as per the system firmware documentation

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