Flash Tool (1-to-N) (Cross-platform)

Resources

Download

Overview

The AmebaFlash Tool is a cross-platform command-line flashing/erasing tool developed for Realtek Ameba series devices. It supports firmware downloading and erasing operations on NOR/NAND/RAM media via local or remote serial ports. It is suitable for automated production, R&D debugging, and multi-serial port parallel flashing scenarios.

Hardware Environment

The hardware setup for firmware download is shown below:

../_images/flash_tool_hardware_topological_uart_usb.svg

Software Environment

AmebaFlash.py requires a Python 3.8 environment. Please ensure that a Python 3.8+ environment is installed, and the dependency libraries in {SDK}/tools/requirements.txt are installed. The specific command is as follows:

$ pip3 install -r {SDK}/tools/requirements.txt

AmebaFlash.exe is the exe version packaged based on AmebaFlash.py and can be used directly without installing dependency libraries.

Note

AmebaFlash.exe is generated from a Python script packaged via PyInstaller, using the -F (i.e., --onefile) option to create a single EXE file. PyInstaller compresses the Python interpreter, source code, all dependency libraries (third-party libraries), and necessary resource files into a single executable file (EXE) that can run directly on Windows. When running the exe on Windows, it does not run Python code directly in memory. Instead, it unpacks all content to a temporary directory and then runs the Python interpreter in that directory. The unpacking process involves file I/O operations, which can be time-consuming on Windows (especially under mechanical hard drives or antivirus software monitoring).

Enter Download Mode

For details on this section, please refer to Automatic download solution.

Currently, the AmebaFlash Tool provides a command-line interface (CLI) mode for firmware downloading. The following is a detailed introduction to this mode:

Command Line Mode (CLI)

Flash Download

AmebaFlash Tool command line mode download. Execute python3 {FlashTool}/AmebaFlash.py in the command line window with specified parameters. The parameter definitions are as follows:

Mandatory Parameters
1. Baudrate
  Parameter -b/--baudrate <value> specifies the download baudrate.
  $AmebaFlash.py -b 1500000
  Note
  
  The baudrate can be set to 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, and 3000000.
2. Profile Selection
  Parameter -f/--profile <profile_path> specifies the profile of the target IC.
  $AmebaFlash.py --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev
3. Parameter -p/--port <port1> <port2> specifies the port number(s) of the target board. After version v1.1.0.0, specifying multiple ports is supported, enabling 1-to-N programming.
  $AmebaFlash.py --port COM3 COM4 COM5
4. Parameter -m/--memory-type <value> specifies the memory type of the target device.
  Currently supported programmable memory types are:
  - nor: NOR Flash (Default)
  - nand: NAND Flash
  - ram: RAM
  $AmebaFlash.py --memory-type nor
1. Image Selection
  e1) Parameter -i/--image <image_path> specifies the firmware image to be downloaded.
  $AmebaFlash.py --image E:\test\image_dir\image_all.bin
  e2) Parameter -a/--start-address <value> specifies the start address for the firmware download in hexadecimal format.
  $AmebaFlash.py --start-address 0x08000000
  e3) Parameter -n/--end-address <value> specifies the end address for the firmware download in hexadecimal format.
  $AmebaFlash.py --end-address 0x00100000
  
  Note
  
  This parameter is required for NAND flash programming; it can be ignored for NOR flash programming.
  e1) The firmware compiled by the SDK may consist of multiple files. The flash tool supports specifying an image directory. Based on the firmware layout predefined in the Profile, it will search the specified path for the corresponding images and program them sequentially. Parameter -r/--image-dir <images_dir> specifies the directory containing the firmware images to be downloaded.
  $AmebaFlash.py --image-dir E:\test\image_dir
  Note
  
  The filenames of the multiple images in the target folder must exactly match the firmware names predefined in the Profile. The exception is Linux xxx.dtb, but the .dts file in the targeted directory must be unique.

Firmware Download

After configuring the parameters, the parameter -d/--download does not require any value to follow it; the parameter itself indicates the execution of the download action.

$AmebaFlash.py --download --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --image E:\test\image_dir\image_all.bin --start-address 0x08000000 --memory-type nor --port COM3

$AmebaFlash.py --download --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --image-dir E:\test\image_dir --memory-type nor --port COM3

Flash Erase

AmebaFlash Tool command line mode erase. Execute python3 {FlashTool}/AmebaFlash.py in the command line window with specified parameters. The parameter definitions are as follows:

Mandatory Parameters
1. Baudrate
  Parameter -b/--baudrate <value> specifies the download baudrate.
  $AmebaFlash.py -b 1500000
  Note
  
  The baudrate can be set to 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, and 3000000.
2. Profile Selection
  Parameter -f/--profile <profile_path> specifies the profile of the target IC.
  $AmebaFlash.py --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev
3. Parameter -p/--port <port1> <port2> specifies the port number(s) of the target board. After version v1.1.0.0, specifying multiple ports is supported, enabling 1-to-N programming.
  $AmebaFlash.py --port COM3 COM4 COM5
4. Parameter -m/--memory-type <value> specifies the memory type of the target device.
  Currently supported programmable memory types are:
  - nor: NOR Flash (Default)
  - nand: NAND Flash
  - ram: RAM
  $AmebaFlash.py --memory-type nor
1. Erase Parameters
  e1) Parameter -e/--erase indicates a Flash partial erase; no value is required after it.
  $AmebaFlash.py --erase
  e2) Parameter -a/--start-address <value> specifies the start address of the Flash area to be erased, in hexadecimal format.
  $AmebaFlash.py --start-address 0x08000000
  e3) Parameter -n/--end-address <value> specifies the end address of the Flash area to be erased, in hexadecimal format.
  $AmebaFlash.py --end-address 0x00100000
  Note
  
  This parameter is required for NAND flash erasing; it can be ignored for NOR flash.
  
  e4) Parameter -z/--size <value> specifies the range (size) of the Flash to be erased, in decimal format, unit is KB.
  $AmebaFlash.py --size 1024
  Note
  
  This parameter is required for NOR flash erasing; it can be ignored for NAND flash.
  e1) Parameter --chip-erase indicates that the current command performs a full chip erase action; no value is required after it.
  $AmebaFlash.py --chip-erase
  Note
  
  If a full chip erase action is required before the download starts, this parameter can also be included in Step 1 of Flash Download.

Erase

After configuring the parameters, the erase command can be executed.

- Partial erase example:
$AmebaFlash.py --erase --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --start-address 0x08000000 --size 1024 --memory-type nor --port COM3

- Full chip erase example:
$AmebaFlash.py --chip-erase --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --memory-type nor --port COM3

Optional Parameter Configuration

Save Log

The parameter -o/--log-file <log-file> can be used to specify a file for saving the download log.

$AmebaFlash.exe --log-file E:/test/AmebaFlash.log

This parameter needs to be included in Step 1 of Flash Download.

Custom Layout

The parameter --partition-table allows customization of the firmware partition table, formatted as a Base64 encoded JSON string.

The custom partition JSON format is as follows:
[
   {
      "ImageName": "/e/temp/test_flash/fw_output/km4_boot_all.bin",
      "StartAddress": 134217728,
      "EndAddress": 134348800,
      "FullErase": false,
      "MemoryType": 1,
      "Mandatory": true,
      "Description": "Dplus Bootloader"
   },
   {
      "ImageName": "/e/temp/test_flash/fw_output/km0_km4_app.bin",
      "StartAddress": 136445952,
      "EndAddress": 137363456,
      "FullErase": false,
      "MemoryType": 1,
      "Mandatory": true,
      "Description": "Dplus nonsecure application"
   }
]

The parameter passed after Base64 encoding of the custom partition is as follows:
$AmebaFlash.exe --partition-table "W3siSW1hZ2VOYW1lIjogIlo6XFx3b3Jrc3BhY2VcXGRlYnVnXFxpbWFnZXNcXGltYWdlX2RwXFxzZWN1cmVcXGttNF9ib290X2FsbC5iaW4iLCAiU3RhcnRBZGRyZXNzIjogMTM0MjE3NzI4LCAiRW5kQWRkcmVzcyI6IDEzNDI5OTY0OCwgIkZ1bGxFcmFzZSI6IGZhbHNlLCAiTWVtb3J5VHlwZSI6IDEsICJNYW5kYXRvcnkiOiB0cnVlLCAiRGVzY3JpcHRpb24iOiAiRHBsdXMgQm9vdGxvYWRlciJ9LCB7IkltYWdlTmFtZSI6ICJaOlxcd29ya3NwYWNlXFxkZWJ1Z1xcaW1hZ2VzXFxpbWFnZV9kcFxcc2VjdXJlXFxrbTBfa200X2FwcC5iaW4iLCAiU3RhcnRBZGRyZXNzIjogMTM0Mjk5NjQ4LCAiRW5kQWRkcmVzcyI6IDEzNjMxNDg4MCwgIkZ1bGxFcmFzZSI6IGZhbHNlLCAiTWVtb3J5VHlwZSI6IDEsICJNYW5kYXRvcnkiOiB0cnVlLCAiRGVzY3JpcHRpb24iOiAiRHBsdXMgc2VjdXJlIGFwcGxpY2F0aW9uIn1d"

Note

ImageName must be the firmware to be programmed with the full file path.
StartAddress/EndAddress must be decimal address values.
FullErase must be a boolean value, indicating whether the entire partition needs to be erased.
MemoryType must be a decimal value. Currently supported types are:
- 0: RAM
- 1: NOR Flash
- 2: NAND Flash
Mandatory must be a boolean value, indicating whether the partition is mandatory for programming.
Description is description information, which is optional.

If a custom partition table is used, the --image/--image-dir parameter is no longer required.

Support Remote Serial Programming

If the AmebaFlash Tool is running on a remote server and connected via SSH locally, but the programming serial port is on the local PC, a network connection to the serial port is required. In this case, use parameters --remote-server <REMOTE_SERVER>/--remote-password <REMOTE_PASSWORD> to specify the remote server access method.

$AmebaFlash.exe --remote-server 192.168.0.1 --remote-password 123456

This parameter needs to be included in Step 1 of Flash Download.

DTR/RTS Configuration

If the device supports the DTR/RTS control module for automatically entering download mode, you can modify the parameter AutoSwitchToDownloadModeWithDtrRts. Simultaneously, configure the Reburn.cfg file specified by the AutoSwitchToDownloadModeWithDtrRtsTimingFile parameter, which defines the timing for the DTR/RTS control AutoDownload circuit. The default uses the timing provided by the Realtek reference board.

To enable the DTR/RTS control module to automatically enter download mode, set it to 1.

"AutoSwitchToDownloadModeWithDtrRts": 1
"AutoSwitchToDownloadModeWithDtrRtsTimingFile": "Reburn.cfg"

Similarly, if you need to automatically reset the device after programming via the DTR/RTS control module, configure AutoResetDeviceWithDtrRts. Simultaneously, configure the Reset.cfg file specified by the AutoResetDeviceWithDtrRtsTimingFile parameter. It defines the timing for the DTR/RTS control AutoDownload circuit. The default uses the timing provided by the Realtek reference board.

To enable the DTR/RTS control module to automatically reset the device, set it to 1.

"AutoResetDeviceWithDtrRts": 1
"AutoResetDeviceWithDtrRtsTimingFile": "Reset.cfg"

Flash Write Protection Handling

During the firmware download process, Flash write protection might be encountered, causing the download to fail. In this case, the tool will pause at the interactive interface to guide the user for further processing. The parameter FlashProtectionProcess can be used to set whether to enable this function. The value can be configured as follows:

0: Whenever the tool encounters Flash write protection, the Console will pause at the interactive interface to guide the user for further processing.

1: The tool will remove the Flash write protection bit, continue with the erase/download operation, and restore the write protection after completion.

2: If the tool detects Flash write protection, it will cancel the erase/download.
"FlashProtectionProcess": 1

Post-Download Operation

The parameter PostProcess allows setting the subsequent operation to be performed on the device after the download finishes.

- NONE: No operation is performed after the download finishes.
- INDICATION: After the download finishes, indicate whether the download was successful via GPIO/PWM.
- RESET: After the download finishes, automatically reset the device.
- BOOT: After the download finishes, automatically jump to RAM to run.
- REBURN: After the download finishes, automatically reset the device and enter download mode.

Note

This parameter needs to be set in the Settings.json file and saved before Flash Download starts.

GPIO/PWM Indication

Automatically identifying which devices have successfully downloaded firmware via the USB interface on the production line, without reconnecting or manually checking, is an important feature. Using the GPIO/PWM indication function can effectively achieve this goal. The specific configuration and implementation methods for this function are as follows:

Parameter ProgramConfig (Default value: 0). For specific configuration bit descriptions, refer to the table below.

Bit

Description

[63:32]

Download indication configuration:

For GPIO indication

Bit[63:33]: Reserved

Bit[32]: GPIO output level

For PWM indication

Bit[63:57]: PWM duty cycle (0~100, unit: percent)

Bit[56:32]: PWM period (unit: us)

[31:30]

Download indication strategy:

0: Disable

1: GPIO indication after download success

2: PWM indication after download success

3: Reserved

[29:16]

Download indication PIN name, refer to the SoC-specific definition of PinName for MBED API

GPIO: all GPIO pins can be selected

PWM: PWM channels can be selected

[15:2]

Reserved

[1:0]

NAND Flash bit flip fail level:

2/3: Reserved

1: Fail at fatal bit flip error, i.e. bit flip count > ECC level

0: Fail at bit flip error, i.e. bit flip count >= ECC level

Note

This parameter needs to be set in the Settings.json file and saved before Flash Download starts.

Auto-Set 4-Byte Addressing Mode

On the production line, Flash capacities larger than 16MB might be encountered. If 4-Byte addressing mode is not enabled, the download process will fail to access areas beyond 16MB, resulting in a failed download. The parameter AutoProgramSpicAddrMode4Byte can assist users in checking the current module capacity and deciding whether to report an error directly or enable 4-Byte addressing mode to continue programming based on this parameter.

0: Do not enable 4-Byte addressing mode; report an error directly.

1: Enable 4-Byte addressing mode; continue programming.

Note

This parameter needs to be set in the Settings.json file and saved before Flash Download starts.

Tool Version Query

The parameter -v/--version can be used to query the current version number of the tool.

$AmebaFlash.exe --version
AmebaFlash.exe x.x.x.x

CLI Help Information

The list of parameters supported by the tool can be obtained via --help, as shown below:

$AmebaFlash.exe/AmebaFlash.py --help
options:
     -h, --help                                        show this help message and exit
     -d, --download                                    download images
     -f PROFILE, --profile PROFILE                     device profile
     -p PORT [PORT ...], --port PORT [PORT ...]        serial port
     -b BAUDRATE, --baudrate BAUDRATE                  serial port baud rate
     -i IMAGE, --image IMAGE                           single image
     -r IMAGE_DIR, --image-dir IMAGE_DIR               image directory
     -a START_ADDRESS, --start-address START_ADDRESS   start address, hex
     -n END_ADDRESS, --end-address END_ADDRESS         end address, hex
     -z SIZE, --size SIZE  size in KB
     -m {nor,nand,ram}, --memory-type {nor,nand,ram}   specified memory type
     -e, --erase                                       erase flash
     -o LOG_FILE, --log-file LOG_FILE                  output log file with path
     -v, --version                                     show program's version number and exit

     --chip-erase                                      chip erase
     --log-level LOG_LEVEL                             log level
     --partition-table PARTITION_TABLE                 layout info, list

     --remote-server REMOTE_SERVER                     remote serial server IP address
     --remote-password REMOTE_PASSWORD                 remote serial server validation password
     --no-reset                                        do not reset after flashing finished

The configuration file {AmebaFlash}/Settings.json also supports some additional parameters to assist users in using the AmebaFlash Tool more conveniently.

Secure Boot Flashing

If Secure Boot flashing is required, the Flashloader must also be configured for Secure Boot. For details, please refer to Usage of Secure Boot.

Copy the generated Flashloader binary to the AmebaFlash\Devices\Floaders directory to overwrite the existing file.

Auto Flash Solution

For details on this section, please refer to Automatic download solution.