AM263Px MCU+ SDK  10.00.00
Flashing Tools

Table of Contents

Introduction

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

TI Uniflash

Note
Sitara MCU devices now supports TI Uniflash Tool for loading/flashing images into the target. Please refer TI Uniflash Tool for more details.

JTAG Session

  1. Set the board in DEVBOOT MODE mode and do a power cycle prior to loading.
  2. Choose a Program to Flash:
    • Click the "Browse" button to select the program you want to flash.
    • The default start address is automatically filled. UniFlash requires the full address since flash offsets are not supported.
      Load Binary Image
    • Do not modify the address field for XIP file type. The field is used by the flash loader to recognize XIP files.
  3. Flash Address Table:
    • The table below shows the flash addresses accepted by the ROM/SBL to load programs onto the target:
      Program Start Address
      SBL 0x60000000
      Application 0x60080000
    • Edit the application offset field only, if your sbl is configured with custom application offset
  4. Initiating Programming:
    • After clicking "Load Image," UniFlash starts the programming process, and the console displays a log of each operation. [SUCCESS] Program Load completed successfully will get printed in the console, if the program loads into the target successfully.

Serial (UART) Session

  1. Set the board in UART BOOT MODE mode and do a power cycle.
  2. Enter the appropriate COM Port and select the board type. Make sure the UART port used for terminal is identified as mentioned in Setup UART Terminal
    COM Port Selection
  3. Choose a Program to Flash:
    • Click the "Browse" button to select the program you want to flash. Serial Uniflash session supports three binary image formats - SBL, application image, XIP application image. It is not necessary to have three images in order to carry out the operation.
    • The SBL and application image flash offsets are handled internally based on the device's SBL configuration.
      Load Binary Image
    • Change the application offset from the settings. This step is only needed if you are using sbl with custom application offset.
      Custom Application Offset
  4. Initiating Programming:
    • After clicking "Load Image," UniFlash starts the programming process, and the console displays a log of each operation. [SUCCESS] Program Load completed successfully will get printed in the console, if the program loads into the target successfully.

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/am263px-cc 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 appimage file for all the CPUs
sbl_ospi_multicore_elf OSPI bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user mcelf application file for all the CPUs
sbl_ospi_fastboot OSPI bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user mcelf file for all the CPUs with the fastest boot time.
sbl_can CAN bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user appimage file for all the CPUs
sbl_can_multicore_elf CAN bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the mcelf application file for all the CPUs
sbl_can_uniflash CAN Uniflash application that needs to be flashed at offset 0x0. When in OSPI boot mode, this uniflash application will wait for CAN packets to flash the user appimage file via CAN using the can_uniflash python script. This application has capability to boot the application as well.
sbl_can_uniflash_multicore_elf CAN Uniflash application that needs to be flashed at offset 0x0. When in OSPI boot mode, this uniflash application will wait for CAN packets to flash the user mcelf application file via CAN using the can_uniflash python script. This application has capability to boot the application as well.
sbl_sd SD bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user appimage file from SD card for all the CPUs
sbl_sd_multicore_elf

SD bootloader application that needs to be flashed at offset 0x0. When in OSPI boot mode, this bootloader application will boot the user mcelf application file from SD card 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 / *.mcelf) 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 / *.mcelf 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=0x81000

Configuration file for MCELF image flashing

  • Similar to the default_sbl_xx.cfg file for flashing appimage binaries, for mcelf binaries refer to mcelf_sbl_xx.cfg file in the same path.

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 0x81000 (*.appimage / *.mcelf). The offset 0x81000 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 0x81000.
  • 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.
    • 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

CAN Uniflash

CAN 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_can_uniflash Flash-writer example which uses CAN to write files

Basic steps to flash files

Refer the example SBL CAN UNIFLASH