Introduction

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

UART 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/am62px-sk	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_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_multistage), OSPI bootloader (sbl_ospi_linux_multistage), EMMC bootloader (sbl_emmc_linux_multistage) 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_linux.cfg
```

Note: For HS-FS device, use default_sbl_ospi_linux_hs_fs.cfg as the cfg file.

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
```

Flash configuration file for flashing to eMMC

Create a flash configuration file, check the flash configuration file preset at below as reference
```
  ${SDK_INSTALL_PATH}/tools/boot/sbl_prebuilt/{board}/default_sbl_emmc_linux.cfg
```

Note: For HS-FS device, use default_sbl_emmc_linux_hs_fs.cfg as the cfg file.

The flashing application and the eMMC bootloader needs to be specified in this file as

  --flash-writer={path to flash application .tiimage}
  --file={path to eMMC bootloader .tiimage} --operation=flash-emmc --flash-offset=0x0

The user application (.appimage) file needs to be specified in the configuration file as

  --file={path to your application .appimage file} --operation=flash-emmc --flash-offset=0x800000

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 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: make -s sbl DEVICE=am62px

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_stage1.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.

Table of Contents