Flashing Tools

Table of Contents

• Introduction
• UART Uniflash
  • Tool requirements on host PC
  • Important files and folders
  • Basic steps to flash files
    • Getting ready to flash
    • Flash configuration file
    • Flashing the files
    • Flash tool options
  • Flash tool error messages and solutions
  • Detailed sequence of steps that happen when flashing files
  • GUI for UART Uniflash (Experimental)
    • Pre-Requisites for UART Uniflash GUI
  • Using the UART Uniflash GUI
  • Important Notes and Common Pitfalls in UART Uniflash GUI
• JTAG Uniflash
  • Important files and folders
  • Basic steps to flash files

Introduction

Flashing tools allow to flash binaries to the flash on a EVM.

• UART Uniflash
• JTAG Uniflash

UART Uniflash

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/{board}
    

  • The flashing application and OSPI bootloader source code can be found at below path

    {SDK_INSTALL_PATH}/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/{board}/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.

GUI for UART Uniflash (Experimental)

UART Uniflash GUI is a GUI wrapper around the UART Uniflash tool already present (uart_uniflash.py). This is a strictly experimental feature with minimal testing from TI side. Can be used if GUI is more comfortable. Since most of the CLI tool is used underneath, it is the same functionality wise

Pre-Requisites for UART Uniflash GUI

This GUI is built on top of the python based UART Uniflash CLI tool already mentioned, and specifically based on the PyQt5 binding of the QT5 framework. So it is expected that python3 and other dependencies (xmodem, pyserial etc) are already installed. In addition to this, one also needs to install the PyQt5 python library for the GUI to work.

• In windows, you can install PyQt5 by doing below:

  python -m pip install pyqt5

• In Ubuntu (or other Debian based distros) you can install PyQt5 by doing below:

  sudo apt install python3-pyqt5

Using the UART Uniflash GUI

The UART Uniflash GUI can be used to flash files arbitrarily into the device flash

UART Uniflash GUI : Serial Port Selection

At the top there is a drop down to select the UART COM port which will be used for flashing. Please connect the target to the EVM before running the GUI so that the serial port we are interested will show up here.

• For choosing what to flash and how to flash there are two high level choices in UART Uniflash GUI:
  • Manual Config
  • From File

UART Uniflash GUI : Manual Config based flashing

UART Uniflash GUI : Config file based flashing

• Manual Config : Manual configuration of the files to be flashed. There will be drop down file browse options to select the various files you will need to flash/send to the target. It provides options / slots to select below:
  • Flash writer binary : This is the sbl_uart_uniflash binary. This needs to be send first for the ROM to receive and boot. Once this boots up you can send any number of files arbitrarily for flashing.
  • Bootloader binary : It is assumed that the eventual goal of the flashing process is to boot your application from the flash device. For this a bootloader capable of reading an image from flash device needs to be flashed at offset 0 (generally) of the flash. This would be the sbl_ospi or sbl_qspi. Although this is no different than flashing any other file to a particular offset, we have decided to keep it a separate option for better clarity. Although the offset is almost always 0, we have provided an offset edit box as well if there is any change whatsoever.
  • Appimage binary : You can select the application image to be flashed from this slot. SDK convention is to flash at a 512 KB offset (0x80000). This can be changed, but keep in mind that the bootloader booting this application should be aware of this offset as well. It is a configurable option in the Sysconfig of the bootloader.
  • Appimage XIP binary : You can select the XIP component to your application from this slot. These files will be of the format (*.appimage_xip). These files already contain details as to where these need to be flashed, so no need to provide any offset in this case.
  • Custom data : This slot can be used to flash any custom data file at an arbitrary offset. Don't forget to provide the offset
  • Flash PHY tuning data : In certain NOR SPI drivers, for tuning the PHY, known data needs to be present in the flash. This is a fixed size (usually 128 bytes) array written to the last block of the flash. This check box needs to be ticked if you're flashing for the first time to the target so that this known data can be written to the flash.

UART Uniflash GUI : Saving the manual configuration

• There is an option to save the settings you selected manually as a config file using the Save CFG button towards the bottom right of the Manual Config group.

UART Uniflash GUI : Saving the manual configuration

• From File : Flash using a configuration file (*.cfg extension) specifying what needs to be flashed. This is a convenient option if the files to be flashed are pretty much the same for every try. In fact even in the manual config case, a cfg file is created internally and used for flashing. This cfg follows the same format used by the CLI script.

After selecting the config options and files, just press the FLASH button to start the flashing. A progress bar will show the flashing progress.

There is also a log area which will show detailed logs in addition to the pop up messages.

UART Uniflash GUI : LOGS

Important Notes and Common Pitfalls in UART Uniflash GUI

• Make sure that the target device is powered ON and is in UART boot mode before attempting to flash
• Make sure that the correct COM port is selected from the drop down. If the wrong port is selected, the flasher might take time to exit out as it will wait for the device to send the XMODEM control character.
• If the GUI seems to hang, re-check the selected COM port and make sure the EVM is powered ON and in UART boot mode
• The GUI is based on the uart_uniflash.py CLI script, and reuses a lot of objects and functions, so core functionality is the same among both.
• In manual config case, if a drop down is non blank it is assumed that the file provided there needs to be flashed. So it will be picked up and used when FLASH button is clicked. If this is not required, make sure to delete it and keep it blank, the drop down is editable. This is true for the config file drop down as well, but the mishap is more probable in manual config case.

JTAG Uniflash

JTAG is used as the transport or interface to send the file to flash to the EVM.

Important files and folders

Folder/Files	Description
${SDK_INSTALL_PATH}/examples/drivers/boot/
sbl_jtag_uniflash	Flash-writer example which uses JTAG to write files or erase flash

Basic steps to flash files

Refer the example SBL JTAG Uniflash