AM243x MCU+ SDK  08.01.00
Flashing Tools

Introduction

Flashing tools allow to flash binaries to the flash on a EVM. UART is used as the transport or interface to send the file to flash to the EVM.

Tool requirements on host PC

  • The tool is implemented using python and needs python version 3.x
  • The tool uses additional python packages as listed below.
    • pyserial for UART access on PC
    • xmodem for the file transfer protocol
    • tqdm for progress bar when the tool is run
  • 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/boot/
uart_uniflash.py Flashing tool
sbl_prebuilt/am243x-evm Pre-built bootloader images and default flash configuration files for a supported EVM
${SDK_INSTALL_PATH}/examples/drivers/boot/
sbl_uart_uniflash Flashing application that is run on the EVM to receive files to flash
sbl_ospi OSPI bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user application file for all the CPUs
sbl_null SOC init bootloader application that can be used to init the SOC when working in CCS IDE environment.

Basic steps to flash files

Getting ready to flash

  • Make sure the flashing application (sbl_uart_uniflash), OSPI bootloader (sbl_ospi), and the user application (*.appimage) you want to flash is built for the EVM.
    • For every supported EVM pre-built flashing application and OSPI bootloader can be found below
      {SDK_INSTALL_PATH}/tools/boot/sbl_prebuilt/am243x-evm
      
    • The flashing application and OSPI bootloader source code can be found at below path
      {SDK_INSTALL_PATH}/tools/examples/drivers/boot
      
    • If you have modified the flashing or bootloader applications, make sure to rebuild these applications and note the path to the .tiimage files that are generated as part of the build.
    • To build your application follow the steps mentioned in Build a Hello World example to build the application you want. Note the path to the *.appimage file that is generated as part of the build.
  • Make sure you have installed python as mention in Python3
  • Make sure you have identified the UART port on the EVM as mentioned in EVM Setup

Flash configuration file

  • Create a flash configuration file, using the default flash configuration file present at below as reference
      ${SDK_INSTALL_PATH}/tools/boot/sbl_prebuilt/am243x-evm/default_sbl_ospi.cfg
    
  • In this config file, modify the paths to the flashing application and OSPI bootloader, in case you are not using the pre-built applications
      --flash-writer={path to flash application .tiimage}
      --file={path to OSPI bootloader .tiimage} --operation=flash --flash-offset=0x0
    
  • Edit below line to point to the user application (.appimage) file
      --file={path to your application .appimage file} --operation=flash --flash-offset=0x80000
    
  • Edit below line to point to the user application XIP image (.appimage_xip) file. When not using XIP mode, this file input is optional.
      --file={path to your application .appimage_xip file} --operation=flash-xip
    

Flashing the files

  • Set EVM in UART BOOT MODE and power on the EVM
  • Run below python command on the Windows command prompt (cmd.exe) or Linux bash shell to flash the files.
      cd ${SDK_INSTALL_PATH}/tools/boot
      python uart_uniflash.py -p {name of your UART com port} --cfg={path to your edited config file}
    
  • At each step in the flashing your will see success or error messages, including progress as the file is being transferred.
  • If flashing is successful, power OFF the EVM, set the EVM to OSPI BOOT MODE and power ON the EVM to run the flashed application.
  • If flashing is not successful, then check the error messages and take appropriate action (See Flash tool error messages and solutions).

Flash tool options

  • Type below to see all the possible options with the flashing tool and also see the default .cfg file for syntax and options possible in the config file
      cd ${SDK_INSTALL_PATH}/tools/boot
      python uart_uniflash.py --help
    

Flash tool error messages and solutions

If the flashing fails, the error message will give a hint as to why it failed. Some common error messages, reasons and potential solutions are listed below.

Error Possible Reason Solution
Serial port not found or not accessible Wrong UART port passed as argument or the UART port is open in some other terminal application. Check the UART port, UART ports are named as COM1, COM2, and so on in Windows and as /dev/ttyUSB0, /dev/ttyUSB1, and so on in Linux. Also make sure to close all open UART terminals and try again.
No response or error response from EVM. Either EVM is not in power-ON state or EVM is not setup in UART boot mode. Use Ctrl-C to terminate the script if it is stuck. Check UART boot mode switch setting, check power to EVM, power-cycle EVM and try again
Flashing failed error message This should not happen ideally on TI EVMs. On custom EVM this could happen if there is some issue in the flash driver on the EVM. Power cycle EVM and try again. If the problem still does not go away, then likely the flash on the EVM has gone bad. Try other SOC initialization options and check the flash driver via CCS IDE debug.
Config file parsing error Wrong config file passed or input files not found. Check the message that is printed, and edit the config file to fix the parsing errors. Make sure to specify file paths with forward slash /, including in Windows. The default config file should not have any errors though.
Python not found error or python packages not not found error Python or python packages needed for this script are not installed Follow steps mentioned in Python3 to install python and related packages
Parsing config file error SBL binaries are missing from the prebuilt folder Build sbl using below command:
gmake -s sbl DEVICE=am243x

Detailed sequence of steps that happen when flashing files

Note
This section has more detailed sequence of steps that happen underneath the tools and on the EVM for reference.

The detailed sequence of steps that happen when flashing files is listed below, refer to the EVM Setup page to see how to setup the EVM in different boot modes that are needed for this sequence of steps.

  • Set EVM in UART boot mode and power it on, the SOC ROM bootloader waits to receive a file using the UART+XMODEM protocol.
  • PC sends the flashing application file (sbl_uart_uniflash.release.tiimage) via the flashing tool using UART+XMODEM protocol underneath.
  • The ROM bootloader, boots the flashing application
  • The flashing application now initializes the flash on the EVM and waits for additional commands using UART+XMODEM protocol
  • The PC tool can now send one or more of below commands with the file data, one after the other, until it is done.
    • Flash a file at a given offset in the flash
    • Verify a previously flashed file at a given offset in the flash
    • Erase a region of flash memory
  • The flashing application as such does not care what the file contains, it will simply flash it at the user specified location.
  • However typically one needs to at least send the below files to flash
    • Send a OSPI flash bootloader application and flash it at offset 0x0 (sbl_ospi.release.tiimage). If the OSPI bootloader is already flashed previously then this step can be skipped.
    • Send your application image multi-core image and flash it at offset 0x80000 (*.appimage). The offset 0x80000 is the offset that is specified in the OSPI bootloader and when the EVM boots in OSPI mode, it will attempt to find a application at this location.
  • After flashing is done, power OFF the EVM
  • Set EVM in OSPI boot mode and power ON the EVM.
    • The ROM bootloader will now boot the OSPI bootloader by reading offset 0x0
    • And the OSPI bootloader will boot the application by reading from offset 0x80000.
  • The initial flashing application and the subsequent commands to send and flash the OSPI bootloader and application files are all specified in a single configuration file which is provided as input to the tool.