Booting Tools

Table of Contents

• Introduction
• Important files and folders
• Out2RPRC
• Multi-core Image Gen
• Signing Scripts
• XIP Image Generator Tool
• UART Bootloader Python Script

Note

To see the exact sequence of steps in which applications and secondary bootloader (SBL) are converted from compiler generated .out files to boot images, see the makefile makefile_ccs_bootimage_gen that is included in every example and secondary bootloader (SBL) CCS project.

If you are using makefile based build, then see the file named makefile in the example folder.

Introduction

This section describes the various tools that are used to create boot images for all the SDK applications

Important files and folders

Folder/Files	Description
${SDK_INSTALL_PATH}/tools/boot/
multicoreImageGen/	Tool to combine multiple RPRC into a single binary
out2rprc/	Tool to convert compiler generated ELF .out for a CPU to a compact and loadable binary representation, called RPRC.
sbl_prebuilt/	Pre-built secondary bootloader (SBL) images and flash configuration files for different supported EVMs, see also Flashing Tools
signing/	Security signing scripts need to create boot images that can be booted by ROM bootloader (RBL)
xipGen/	Tool to split a RPRC file generated from out2rprc into two files containing non-XIP and XIP sections.
uart_bootloader.py	Python script used to send the SBL and appimage binaries over UART using XMODEM protocol in UART boot mode
uart_uniflash.py	Python script used to flash SBL and applications to EVM flash using UART. See Flashing Tools for more details.

Out2RPRC

• This tool converts the application executable (.out) into custom TI RPRC (.rprc) image - an image loadable by the secondary bootloader (SBL).
• This tool strips out the initialized sections from the executable file (*.out) and places them in a compact format that the SBL can understand.
• The output RPRC file is typically much smaller than the original executable (*.out) file.
• The RPRC files are intermediate files in a format that is consumed by MulticoreImageGen tool that generates the final binary that is flashed (*.appimage)
• The RPRC file format contains header to various sections in the executable like section run address, size and a overall header which mentions the number of sections and the start offset to the first section.
• The RPRC magic word is 0x43525052 - which is ASCII equivalent for RPRC
• Shown below is the file header and section format for RPRC files.

RPRC File Format

• In Windows, use the following command to convert application executable into RPRC image file

  cd ${SDK_INSTALL_PATH}/tools/boot/out2rprc
  out2rprc {input application executable file (.out) {output application rprc file (.rprc)}

• In Linux, use mono to invoke this executable (see Mono Runtime)

  cd ${SDK_INSTALL_PATH}/tools/boot/out2rprc
  mono out2rprc.exe {input application executable file (.out) {output application rprc file (.rprc)}

Note

In windows, the out2rprc.exe has a dependency on .NET framework 3.5. Make sure that this is installed. You can check this via Control Panel -> Programs and Features.

Multi-core Image Gen

• This tool converts the RPRC files created for each CPU into a single combined multicore application image that can be booted by the secondary bootloader (SBL)
• Shown below is the file format for multicore image files.

Multi-core Image File Format

• The number of meta headers present is equal to the number of cores included.
• The meta header magic word is 0x5254534D - which is ASCII equivalent for MSTR
• In Windows or Linux, use the following command to convert RPRC images into a multicore .appimage file

  cd ${SDK_INSTALL_PATH}/tools/boot/multicoreImageGen
  MulticoreImageGen {ENDIAN} {DEV_ID} {Output image file (.appimage)} {core 1 id} {core 1 rprc file} [ {core n id} {core n rprc file} ... ]

• In case of AM243X, ENDIAN should be LE and DEV_ID is 55.
• The various core ID to be used are as below.

CORE	CORE ID
r5fss0-0	4
r5fss0-1	5
r5fss1-0	6
r5fss1-1	7
m4fss0-0	14

Signing Scripts

• To run these scripts, one needs openssl installed as mentioned here, OpenSSL
• Signing scripts are a collection of scripts needed to sign the secondary bootloader (SBL) image as required by ROM bootloader (RBL).
• The RBL requires the boot image (in this case SBL), to be signed always, even if we are not using secure boot.
• Use the following command to sign the SBL image.

  cd ${SDK_INSTALL_PATH}/tools/boot/signing
  x509CertificateGen.ps1 -b {BOOTIMAGE_BIN_NAME} -o {BOOTIMAGE_NAME} -c R5 -l {SBL_RUN_ADDRESS} -k {BOOTIMAGE_CERT_KEY} -d DEBUG -j DBG_FULL_ENABLE -m SPLIT_MODE

• In Windows, use powershell to execute the script file.

  powershell -executionpolicy unrestricted -command x509CertificateGen.ps1

  • Here,
    • SBL_RUN_ADDRESS is 0x70000000
    • BOOTIMAGE_CERT_KEY is rom_degenerateKey.pem

XIP Image Generator Tool

• This tool, splits a input RPRC application file, into two RPRC files,
  • First RPRC file, containing non-XIP sections and the application entry point
  • Second RPRC file, containing XIP sections. Here, adjacent sections are merged into one section
• The final number of sections in both RPRC files taken together can be less than the sections in the input file due to section merging in the XIP RPRC file.

XIP Image Generation Tool flow

• The non-XIP RPRC file should be flashed and booted via SBL as usual
• The XIP RPRC file should be flashed via the SDK flash writer, using the command --flash-xip, the flash writer in this case will flash sections at the flash address mentioned in the RPRC section header.
• To see the detailed options supported by the tool, run this tool with the option --help. Example, output in Windows is shown below,

> cd {SDK_INSTALL_PATH}/tools/boot/xipGen
> xipGen.exe
 
  XIP Image Creation Tool  - (c) Texas Instruments 2021, created on Apr 19 2021
 
  Usage: xipGen [options]
 
  Description,
  This tool, splits a input RPRC application file, into two RPRC files,
  - First RPRC file, containing non-XIP sections. The application entry point is assumed
      to be in non-XIP region.
  - Second RPRC file, containing XIP sections. The RPRC entry point is set to 0 and
      adjacent XIP sections are merged
 
  Note, the final number of sections in both RPRC files taken together can be less
  than the sections in the input file due to section merging in the XIP RPRC file.
 
  The non-XIP RPRC file should be flashed and booted via SBL as usual
 
  The XIP RPRC file should be flashed via the SDK flash writer, the flash writer will
  flash sections at the flash address mentioned in the RPRC sections
 
  Options,
  --input, -i : input RPRC file,
  --output, -o : output RPRC file of non-XIP sections,
  --output-xip, -x : output RPRC file of XIP sections,
  --flash-start-addr, -f : XIP flash address space start, specified in hex. If not specified 0x60000000 is used
  --flash-size, -s : XIP flash address space size in units of mega bytes, specified as integer. If not specified 256 MB is used
  --verbose, -v : Verbose prints are enabled during the tool execution
  --help, -h : Shows this help

UART Bootloader Python Script

• This script is used in UART boot mode for sending the SBL and appimage binaries to the EVM via UART using XMODEM protocol
• Make sure that python3 and its dependent modules are installed in the host machine as mentioned in Python3
• Booting via UART is slow, but is useful if application loading via CCS or OSPI boot is not an option
• Make sure the UART port used for terminal is identified as mentioned in Setup UART Terminal
• Make sure you have the EVM power cable and UART cable connected as shown in Cable Connections
• To boot applications using this script, POWER OFF the EVM
• Switch to UART BOOT MODE.
• POWER ON the EVM
• To confirm that the board is in UART boot mode, open the UART terminal and confirm that you see the character 'C' getting printed on the console every 2-3 seconds.
• Now close the terminal. This is important as the script won't be able to function properly if the UART terminal is open.
• Open a command prompt and run the below command to send the SBL and application binary to the EVM

  cd ${SDK_INSTALL_PATH}/tools/boot
  python uart_bootloader.py -p COM13 --bootloader=sbl_prebuilt/{board}/sbl_uart.release.tiimage --file=< path to multicore appimage of application binary >

• When you execute this, the script first sends the uart bootloader, and then the multicore appimage
• After the multicore appimage is successfully parsed, the uart bootloader sends an acknowledgment to the script and waits for 5 seconds before running the application binary
• Upon receiving the ack, the script will exit successfully
• Connect to the UART terminal within 5 seconds to see logs from the application
• Below are the logs of the script after all the files have been sent

  Sending the UART bootloader sbl_prebuilt/{board}/sbl_uart.release.tiimage ...
  Sent bootloader sbl_prebuilt/{board}/sbl_uart.release.tiimage of size 243975 bytes in 23.94s.
   
  Sending the application ../../examples/drivers/udma/udma_memcpy_polling/{board}/r5fss0-0_nortos/ti-arm-clang/udma_memcpy_polling.release.appimage ...
  Sent application ../../examples/drivers/udma/udma_memcpy_polling/{board}/r5fss0-0_nortos/ti-arm-clang/udma_memcpy_polling.release.appimage of size 99580 bytes in 11.74s.
  [STATUS] Application load SUCCESS !!!
  Connect to UART in 5 seconds to see logs from UART !!!