AM263Px MCU+ SDK: Flashing Tools

| AM263Px MCU+ SDK 26.00.00 |

Flashing Tools

# Introduction

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

- TI Uniflash
- UART Uniflash
- JTAG Uniflash
- CAN Uniflash

# 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 | 0x60081000

   - 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_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_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_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_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 (`*.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 `*.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}/mcelf_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 (`.mcelf`) file

        --file={path to your application .mcelf file} --operation=flash-sector-write --flash-offset=0x81000

### 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 (`*.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.
  - Application binary : You can select the application image to be flashed from this slot. SDK convention is to flash at a 512 KB offset (0x81000). 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.
  - Application XIP binary : You can select the XIP component to your application from this slot. These files will be of the format (`*.mcelf_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(Joint Test Action Group) is used as the transport or interface to send the file to flash to the EVM.
- It uses a serial protocol to communicate with the DAP (Debug Access Port) on the EVM.

## Sequence of steps that happen when flashing via JTAG

- Debugger initializes the SOC
  - CCS connects using the JTAG interface and uses gel scripts to initialize PLLs, clocks and memory.
- Flash driver gets loaded into RAM
  - A flash programming algorithm is loaded into RAM via JTAG.
  - This algorithm contains a program that can write to the flash memory.
- Then your binary (.mcelf/.tiimage) is streamed over the JTAG. The driver receives chunks of the application, unlocks the target flash memory regions, erases the sectors and performs flash write operation.
- Once the JTAG has successfully received the SBL and application binaries, switch to OSPI bootmode and reset the board.
- ROM bootloader will boot the flashed SBL(secondary bootloader) and the SBL will boot up the application.

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

# ENET Uniflash

UDP over ethernet 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.
  - 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/
enet_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_qspi_enet | QSPI bootloader application and Flashing application that is run on the EVM to receive files to flash. To be flashed at offset 0x0. When in QSPI boot mode, this bootloader application will boot the user application file for all the CPUs

## Basic steps to flash files over ethernet

### Getting ready to flash

- Make sure the QSPI Ethernet bootloader (`sbl_qspi_enet`) has been flashed using the steps provided in Basic steps to flash files.
- Make sure the user application (`*.appimage`) you want to flash over ethernet is built for the EVM.

### Flash configuration file

- Create a flash configuration file, using the default flash configuration file present

        ${SDK_INSTALL_PATH}/tools/boot/sbl_prebuilt/{board}/default_sbl_qspi.cfg

- In this config file, modify the paths to the application to be flashed only.

  Remove or comment out the flash-writer path

       --flash-writer={path to flash application .tiimage}

  Remove or comment out the bootloader path

       --file={path to QSPI 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=0xA0000

### Flashing the files over ethernet

- 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 enet_uniflash.py --cfg={path to your edited config file}

- When the python script starts, it will display the message "Starting Linkup ...".

  Based on the MACRO ENETSBL_TRANSFER_START_MODE set in sbl_enet.h of the sbl_qspi_enet bootloader, do either of the below when the above message is observed,

  - If in ENETSBL_TIMER_MODE, Press the reset button SW1 on the EVM.
  - If in ENETSBL_BUTTON_MODE, Press the reset button SW1 while holding down the user switch SW2.
- After flashing is successful, the flashed application code will be automatically run after the SBL completes. See Sample Output for a sample of the python script output after a successful flash.

### 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 enet_uniflash.py --help