Flashing Tools

Introduction

Flashing tools allow flashing binaries to the flash on an EVM.

Snagfactory
UART Uniflash

Note

It is recommended to flash using snagfactory for AM62x, AM62Ax, AM62Px, AM62Dx.

Snagfactory

Snagfactory is an open-source tool developed by Bootlin for flashing and recovery using the fastboot protocol over USB. It is based on Snagboot — a fully open-source and vendor-agnostic recovery and flashing tool. It is designed to simplify the process of flashing non-volatile storage devices and recovering target boards during development and production environments.

Snagfactory is composed of two components:

Snagrecover — Loads recovery firmware binaries (tiboot3, tispl, u-boot) to the board over USB DFU, initializes the SOC, and enables Fastboot mode for subsequent flashing.
Snagflash — Flashes binaries to the on-board memory using the Fastboot protocol over USB.

Important files and folders

Folder/Files	Description
${SDK_INSTALL_PATH}/tools/boot/snagfactory/
snagfactory_flash.py	Main flash utility script. Wraps `snagrecover` and `snagflash` for AM62x family boards. Accepts a `.cfg` file and board name to generate snagflash `.cmd` files and snagrecover YAML files.
${SDK_INSTALL_PATH}/tools/boot/snagfactory/{board}/
params.yaml	Per-board configuration file. Defines USB IDs, SOC model, framebuffer settings, recovery firmware paths, and flash targets (`emmc`, `ospi-nor`, `ospi-nand`).
{board}_{target}_{sec}.cmd	Generated snagflash command file. Contains `set target`, `set fb-addr`, `set fb-size`, `set eraseblk-size` (OSPI only), and `flash` commands with offsets and `hwpart` (eMMC only).
{board}_{target}_{sec}.yaml	Generated snagrecover YAML file. Contains board USB ID mapping, SOC firmware paths, and flash task definitions with offsets and partition settings.
${SDK_INSTALL_PATH}/tools/boot/snagfactory/logs/
flash_{board}_{target}_{timestamp}.log	Timestamped log file generated per flash run. Contains output from `snagrecover`, `snagflash`, validation results, and error messages.

Tool requirements on host PC

The tool is implemented using Python and needs Python version 3.x. Refer to Python3 to install Python and the required Python packages on your PC.
Snagboot — provides Snagrecover and Snagflash.
- Snagfactory tool is hosted here Snagfactory.
- More info about installation can be found in Snagfactory Readme.
- Snagfactory is also available on pip.
```
$ python3 -m pip install --user snagboot
$ python3 -m pip install --user snagboot[gui]
```

Flash configuration file

Create a flash configuration file using a default configuration file as reference:

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

In this configuration file, specify only the application binaries to flash with their offsets:
```
  --file={path to application .appimage.hs_fs} --operation=flash --flash-offset=0x80000
```

Note

Recovery binaries (tiboot3, tispl, u-boot) are specified separately in params.yaml under the board-specific directory. Snagfactory automatically loads these during the recovery phase via snagrecover.

The .cfg file is processed by snagfactory_flash.py script which generates:
- .cmd file — Contains Fastboot commands for snagflash
- .yaml file — Contains board configuration and USB parameters for snagrecover
These generated files are used directly by the Snagfactory GUI or CLI for flashing.

Example .cmd file

The .cmd file contains Fastboot commands that snagflash executes in sequence:

    set target mmc0
    set fb-addr 0x82000000
    set fb-size 0x7000000

    flash "/path/to/sbl_emmc_linux_stage1.release.hs_fs.tiimage" 0x0 hwpart 1
    flash "/path/to/sbl_emmc_linux_stage2.release.appimage.hs_fs" 0x80000 hwpart 1
    flash "/path/to/hsm.appimage.hs_fs" 0x240000 hwpart 1
    flash "/path/to/hello_world.release.appimage.hs_fs" 0x800000 hwpart 1
    flash "/path/to/linux.appimage.hs_fs" 0x1200000 hwpart 1
    flash "/path/to/u-boot.img" 0x280000 hwpart 1

    exit

Example .yaml file

The .yaml file contains board configuration and recovery firmware paths for snagrecover.

    boards:
      "0451:6165": "<soc-model>"
    soc-models:
      <soc-model>-firmware:
        tiboot3:
          path: <board-directory>/tiboot3.bin
        tispl:
          path: <board-directory>/tispl.bin
        u-boot:
          path: <board-directory>/u-boot.img
      <soc-model>-tasks:
      - target-device: mmc0
        fb-buffer-addr: 0x82000000
        fb-buffer-size: 0x7000000
      - task: reset
      - task: flash
        args:
        - image: /path/to/sbl_emmc_linux_stage1.release.hs_fs.tiimage
          image-offset: 0x0
          part: "hwpart 1"
        - image: /path/to/sbl_emmc_linux_stage2.release.appimage.hs_fs
          image-offset: 0x80000
          part: "hwpart 1"
        - image: /path/to/hsm.appimage.hs_fs
          image-offset: 0x240000
          part: "hwpart 1"
        - image: /path/to/hello_world.release.appimage.hs_fs
          image-offset: 0x800000
          part: "hwpart 1"
        - image: /path/to/linux.appimage.hs_fs
          image-offset: 0x1200000
          part: "hwpart 1"
        - image: /path/to/u-boot.img
          image-offset: 0x280000
          part: "hwpart 1"

Basic steps to flash files

Getting ready to flash

Make sure the required bootloader binaries are built for the EVM. For Snagrecover, bootloader images must support DFU boot and fastboot download. In addition to USB DFU fragment config (which enables DFU boot) for the u-boot build, an additional fragment config am6x_a53_snagfactory.config needs to be used, which enables fastboot support in U-Boot and other required configs for snagfactory.

To build bootloader images for recovery using SDK, following change is needed in Rules.make file present in the top level of Linux SDK Installer.

    UBOOT_MACHINE_R5=am62dx_evm_r5_defconfig am62dx_r5_usbdfu.config
    UBOOT_MACHINE_A53=am62dx_evm_a53_defconfig am62dx_a53_usbdfu.config am6x_a53_snagfactory.config

Generate the bootloader images using top-level makefile by running following commands on the terminal from the top-level of the Linux SDK installer.

    $ make u-boot_clean
    $ make u-boot
    $ make u-boot_stage

Save the bootloader binaries generated in a separate directory. These bootloader images will be used for recovery and to start flashing the images. The bootloader images after make can be found in board-support/built-images. Copy the generated binaries to the board-specific snagfactory directory:

    $ cp board-support/built-images/tiboot3.bin  $(MCU_PLUS_SDK_PATH)/tools/boot/snagfactory/<board>/
    $ cp board-support/built-images/tispl.bin    $(MCU_PLUS_SDK_PATH)/tools/boot/snagfactory/<board>/
    $ cp board-support/built-images/u-boot.img   $(MCU_PLUS_SDK_PATH)/tools/boot/snagfactory/<board>/

Note

CONFIG_FASTBOOT_BUF_SIZE is defined in am6x_a53_snagfactory.config and specifies the maximum buffer size for flashing files. Its value must be equal or greater than the largest file size being flashed. If smaller, non-sparse images will not flash correctly due to issues with chunked processing.

Make sure you have Snagfactory installed on your host machine.

Make sure you have identified the correct USB DFU interface on the EVM.

Create a flash configuration file, refer to the Flash configuration file section for more details.

Flash tool options

Type below to see all the possible options with the flashing tool:

  cd ${SDK_INSTALL_PATH}/tools/boot/snagfactory
  python3 snagfactory_flash.py --help

Flashing using GUI

Set EVM in USB DFU boot mode (see Getting ready to flash) and power on the EVM.
Run the below command to generate the configuration files (.cmd and .yaml) required by Snagfactory GUI, replacing <boot-media> with the appropriate target and <path-to-edited-cfg-file> with the path to your edited flash configuration file.

    cd ${SDK_INSTALL_PATH}/tools/boot/snagfactory
    python3 snagfactory_flash.py --board am62dx-evm --target <boot-media> --cfg-file <path-to-edited-cfg-file> --gen-cfg

Step 1: Launch SnagFactory GUI Tool

Launch the SnagFactory GUI tool to begin the configuration and device flashing process.

The following steps outline the process for configuring and flashing a device by using the SnagFactory GUI tool.

SnagFactory GUI

Step 2: Select Configuration File Option

Upon launch, the SnagFactory GUI tool will present the option to add a configuration file. Select the conf option to proceed with loading the configuration file.

Step 3: Load YAML Configuration File

Load the Generated YAML configuration file for the platform. The YAML file follows the naming pattern: {board}_{target}_{security}.yaml (e.g., am62px-sk_emmc_hs_fs.yaml, am62x-sk_ospi-nor_hs_fs.yaml).
This file contains the platform-specific settings and parameters required for device flashing, including:
- Board USB Device Mapping: Maps the USB device ID (vendor:product code) to the corresponding SOC model name
- Recovery Firmware Paths: Specifies locations of tiboot3.bin, tispl.bin, and u-boot.img for ROM-level bootloader initialization
- Flash Target Configuration: Defines the target storage medium (eMMC, OSPI-NOR, or OSPI-NAND) and its associated parameters
- Memory Buffer Settings: Provides framebuffer address and size for recovery operations
- Flash Task Definitions: Contains detailed flash commands with image file offsets, partition information (hwpart), and execution sequence

The board name mapping for the params.yaml file is as follows. This mapping defines the SOC model name used in the generated YAML configuration file for Snagfactory, which must match the board being flashed:

Evaluation Board

Family

Board

am62pxx-evm

am6x

am62p

am62xx-evm

am6x

am625

am62xx-lp-evm

am6x

am625

am62sip-evm

am6x

am625

am62ax-evm

am6x

am62a7

am62dxx-evm

am6x

am62d2

Step 4: Flash the Device

Once you load the generated YAML configuration file (.yaml file with format {board}_{target}_{security}.yaml), the SnagFactory GUI tool will execute the flashing sequence.
The tool automatically runs snagrecover to load recovery firmware and then snagflash to flash application images at their specified offsets.
Monitor the progress display and wait for the flashing to complete successfully.

If flashing fails at any point, check the Show Logs option in the GUI for more details.

Flashing using CLI

Set EVM in USB DFU boot mode (see Getting ready to flash) and power on the EVM.
If the USB ID has changed, update the usb-path parameter in the params.yaml file of the respective board (it is null by default). You can find the correct USB path by running:
```
  dfu-util -l
```
Run the below command to flash the files, replacing <boot-media> with the appropriate target and <path-to-edited-cfg-file> with the path to your edited flash configuration file.

    cd ${SDK_INSTALL_PATH}/tools/boot/snagfactory
    python3 snagfactory_flash.py --board am62dx-evm --target <boot-media> --cfg-file <path-to-edited-cfg-file>

At each step of the flashing you 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 Error messages and solutions).
Detailed logs for each flashing session are also saved to:
```
  ${SDK_INSTALL_PATH}/tools/boot/snagfactory/logs
```
Review the log files in this directory for a full trace of the flashing process, which can be helpful for diagnosing failures.

Error messages and solutions

If the tool 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
Unknown board 'BOARD'. Available: [...]	The board name passed to `--board` is not defined in `BOARD_CONFIGS`.	Check the supported board names using `--help` and pass a valid `--board` value.
Unknown target 'TARGET' for board 'BOARD'. Available: [...]	The flash target passed to `--target` is not defined for the selected board in `BOARD_CONFIGS`.	Run the script with `--help` to see supported targets, or check `board_configs.py` for valid targets for your board.
Config generation failed: ...	`generate_cmd()` raised a `ValueError` or `FileNotFoundError` — either a bad configuration or a missing input file.	Check the error detail printed below the message. Verify board config entries and ensure all referenced files exist.
snagrecover not found in PATH. Is snagboot installed?	The `snagrecover` utility is not installed or not available in the system PATH.	Install snagboot using: `pip install snagboot`
Recovery firmware not found: FILE_PATH	One or more recovery firmware binaries defined in `board_configs.py` under `recovery_fw` are missing from the Processor SDK path.	Verify the `--proc-sdk-path` argument points to a valid Processor SDK installation and that all recovery firmware binaries are present at the expected paths.
snagrecover failed (exit code CODE). Aborting.	The `snagrecover` tool exited with a non-zero return code during ROM-level firmware upload over USB DFU.	Check USB connection and ensure the board is powered on in `BOOTMODE_USB_DFU` mode. Verify that the recovery firmware binaries are correct for the SOC and Processor SDK version.
snagflash not found in PATH. Is snagboot installed?	The `snagflash` utility is not installed or not available in the system PATH.	Install snagboot using: `pip install snagboot`
snagflash failed (exit code CODE).	The `snagflash` tool exited with a non-zero return code during Fastboot image flashing.	Review the generated `.cmd` file under the `configs/` directory. Verify flash offsets and image paths are correct, and ensure the board enumerated successfully as a Fastboot device after `snagrecover` completed.
eMMC target requires a GPT image.	The `--target emmc` was selected but no `--gpt-image` argument was provided.	Generate a GPT binary and pass it using `--gpt-image /path/to/gpt.bin`. Refer to the error output for the exact `sgdisk` and `dd` commands to generate the GPT image.
SDK path not found: PATH	The path passed to `--sdk-path` does not exist on the host machine.	Verify the MCU+ SDK installation path and pass the correct value to `--sdk-path`.
Processor SDK path not found: PATH	The path passed to `--proc-sdk-path` does not exist on the host machine.	Verify the TI Processor SDK installation path and pass the correct value to `--proc-sdk-path`.

Detailed sequence of steps that happen when flashing files

Note

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

Set EVM in USB DFU boot mode (see Getting ready to flash) and power on the EVM.
The host PC runs snagrecover, which loads the recovery firmware binaries over USB DFU.
U-Boot initializes and enumerates the board as a USB Fastboot device on the host PC.
The host PC detects the Fastboot device and runs snagflash, which sends one or more of the below commands with the file data, one after the other, until it is done:
- Flash a file at a given offset in the flash memory
- Verify a previously flashed file at a given offset in the flash memory
- Erase a region of flash memory
The flashing application does not care what the file contains — it will simply flash it at the user specified location.
On successful completion, the tool logs Flash complete! and exits. If any step fails, an error message is logged with the exit code and the script exits immediately (See Error messages and solutions).

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/{{ VAR_BOARD_NAME_LOWER }}	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_multistage), EMMC bootloader (sbl_emmc_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](../../getting_started/getting_started_build.md) 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_hs_fs.cfg
```

Note

For HS-SE device, use default_sbl_ospi_hs.cfg as the cfg file.

Note

For HS-FS device, use default_sbl_ospi_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}/examples/drivers/boot/sbl_emmc_linux/am64x-evm/r5fss0-0_nortos/default_sbl_emmc_linux.cfg

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

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-SE device, use default_sbl_emmc_linux_hs.cfg as the cfg file.

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

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

Note

For HS-SE device, use default_sbl_emmc_hs.cfg as the cfg file.

Note

For HS-FS device, use default_sbl_emmc_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

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_qspi.cfg
```
In this config file, modify the paths to the flashing application and QSPI bootloader, in case you are not using the pre-built applications
```
  --flash-writer={path to flash application .tiimage}
  --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=0x80000

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: \n make -s sbl DEVICE={{ VAR_SOC_NAME_LOWER }}

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 appropriate EVM Setup guide to setup the EVM in different boot modes that are needed for this sequence of steps:

EVM Setup

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.

Evaluation Board	Family	Board
am62pxx-evm	am6x	am62p
am62xx-evm	am6x	am625
am62xx-lp-evm	am6x	am625
am62sip-evm	am6x	am625
am62ax-evm	am6x	am62a7
am62dxx-evm	am6x	am62d2