Flash 烧写工具(1 拖 N)(跨平台)

资源

下载

概述

AmebaFlash Tool 是为 Realtek Ameba 系列设备开发的跨平台命令行烧写/擦除工具，支持通过本地或远程串口对 NOR/NAND/RAM 介质进行固件下载和擦除操作。适用于自动化生产、研发调试以及多串口并行烧写场景。

硬件环境

固件下载的硬件设置如下所示：

../_images/flash_tool_hardware_topological_uart_usb.svg

软件环境

AmebaFlash.py 需要 python3.8 的环境，请确保安装了 python3.8+环境，并且需要安装 {SDK}/tools/requirements.txt 中的依赖库。具体指令如下：

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

AmebaFlash.exe 是基于 AmebaFlash.py 打包的 exe 版本，可以直接使用，无需安装依赖库。

备注

AmebaFlash.exe 是 python 脚本通过 pyinstaller 打包生成的，打包时使用了 -F (即--onefile) 打包成的单个 EXE 文件。PyInstaller 会将 Python 解释器、源代码、所有依赖库（第三方库）以及必要的资源文件全部压缩进一个可以在 Windows 上直接运行的可执行文件（EXE）中。

当在 Windows 上运行 exe 时，它并不是直接在内存中运行 Python 代码，而是将所有内容解压到临时目录，然后在该目录中运行 Python 解释器。解压过程涉及文件 I/O 操作，这在 Windows 上（尤其是机械硬盘或杀毒软件监控下）是比较耗时的。

进烧录模式

本章节详细内容请参考进烧录模式。

AmebaFlash Tool 目前提供了命令行模式（CLI）下载固件。以下是对这种模式的详细介绍：

命令行模式（CLI）

Flash 烧录

AmebaFlash Tool 命令行模式下载。在命令行窗口执行 python3 {FlashTool}/AmebaFlash.py 并且带着指定的参数。参数释义如下：

必须设置参数项
1. 波特率
  参数 -b/--baudrate <value> 带入下载波特率参数.
  $AmebaFlash.py -b 1500000
  备注
  
  波特率可设置参数为 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000 和 3000000。
2. Profile 选择
  参数 -f/--profile <profile_path> 带入目标 IC 的 profile。
  $AmebaFlash.py --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev
3. 参数 -p/--port <port1> <port2> 带入目标板的端口号。v1.1.0.0 版本之后，支持带入多个端口，即实现 1 拖多烧录。
  $AmebaFlash.py --port COM3 COM4 COM5
4. 参数 -m/--memory-type <value> 带入目标设备 memory 类型。
  目前支持的可烧录 memory 类型有：
  - nor: NOR Flash(默认)
  - nand: NAND Flash
  - ram: RAM
  $AmebaFlash.py --memory-type nor
1. 固件选择
  e1) 参数 -i/--image <image_path> 带入要下载的固件。
  $AmebaFlash.py --image E:\test\image_dir\image_all.bin
  e2) 参数 -a/--start-address <value> 带入要下载固件的起始地址，十六进制格式
  $AmebaFlash.py --start-address 0x08000000
  e3) 参数 -n/--end-address <value> 带入要下载固件的结束地址，十六进制格式
  $AmebaFlash.py --end-address 0x00100000
  
  备注
  
  此参数是 nand flash 烧录必需，如果是 nor flash 烧录，可以忽略。
  e1) SDK 编译出来的固件有可能是多个，flash tool 支持指定固件路径，然后根据 Profile 预定义的固件布局，去指定路径找相应固件逐一烧录。参数 -r/--image-dir <images_dir> 带入要下载的固件所在目录。
  $AmebaFlash.py --image-dir E:\test\image_dir
  备注
  
  此处目标文件夹的多个固件命名需要和 Profile 里预设的固件名称完全一致。Linux xxx.dtb 除外，但是指向的目录中.dts 文件需要唯一。

固件下载

配置好参数之后，参数 -d/--download 后不需要跟任何值，参数本身就表示执行烧录动作。

$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 擦除

AmebaFlash Tool 命令行模式擦除 Flash。在命令行窗口执行 python3 {FlashTool}/AmebaFlash.py 并且带着指定的参数。参数释义如下：

必须设置参数项
1. 波特率
  参数 -b/--baudrate <value> 带入下载波特率参数.
  $AmebaFlash.py -b 1500000
  备注
  
  波特率可设置参数为 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000 和 3000000。
2. Profile 选择
  参数 -f/--profile <profile_path> 带入目标 IC 的 profile。
  $AmebaFlash.py --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev
3. 参数 -p/--port <port1> <port2> 带入目标板的端口号。v1.1.0.0 版本之后，支持带入多个端口，即实现 1 拖多烧录。
  $AmebaFlash.py --port COM3 COM4 COM5
4. 参数 -m/--memory-type <value> 带入目标设备 memory 类型。
  目前支持的可烧录 memory 类型有：
  - nor: NOR Flash(默认)
  - nand: NAND Flash
  - ram: RAM
  $AmebaFlash.py --memory-type nor
1. 擦除参数
  e1) 参数 -e/--erase 表示要 Flash 部分擦除，后不需要带任何值。
  $AmebaFlash.py --erase
  e2) 参数 -a/--start-address <value> 带入要擦除 Flash 区域的起始地址，十六进制格式
  $AmebaFlash.py --start-address 0x08000000
  e3) 参数 -n/--end-address <value> 带入要擦除 Flash 区域的结束地址，十六进制格式
  $AmebaFlash.py --end-address 0x00100000
  备注
  
  此参数是 nand flash 擦除必需，如果是 nor flash，可以忽略。
  
  e4) 参数 -z/--size <value> 带入要擦除 Flash 的范围，十进制格式，单位是 KB
  $AmebaFlash.py --size 1024
  备注
  
  此参数是 nor flash 擦除必需，如果是 nand flash，可以忽略。
  e1) 参数 --chip-erase 表示当前指令要做全片擦除的动作，后不需要带任何值。
  $AmebaFlash.py --chip-erase
  备注
  
  如果需要在烧录开始之前做一次全片擦除的动作，也可以在 Flash 烧录第 1 步带入该参数。

擦除

配置好参数之后，即可开始执行擦除指令。

- 擦除部分 Flash 示例:
$AmebaFlash.py --erase --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --start-address 0x08000000 --size 1024 --memory-type nor --port COM3

- 擦除全片 Flash 示例:
$AmebaFlash.py --chip-erase --baudrate 1500000 --profile E:\test\image_path\AmebaX_FreeRTOS_NOR.rdev --memory-type nor --port COM3

可选参数配置

保存日志

参数 -o/--log-file <log-file> 可以设置保存下载日志文件。

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

该参数需要在 Flash 烧录第 1 步带入。

自定义 Layout

参数 --partition-table 可以自定义固件的分区表，格式为 Base64 编码的 JSON 字符串。

自定义分区 json 格式如下：
[
   {
      "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"
   }
]

自定义分区 Base64 编码后带入参数如下：
$AmebaFlash.exe --partition-table "W3siSW1hZ2VOYW1lIjogIlo6XFx3b3Jrc3BhY2VcXGRlYnVnXFxpbWFnZXNcXGltYWdlX2RwXFxzZWN1cmVcXGttNF9ib290X2FsbC5iaW4iLCAiU3RhcnRBZGRyZXNzIjogMTM0MjE3NzI4LCAiRW5kQWRkcmVzcyI6IDEzNDI5OTY0OCwgIkZ1bGxFcmFzZSI6IGZhbHNlLCAiTWVtb3J5VHlwZSI6IDEsICJNYW5kYXRvcnkiOiB0cnVlLCAiRGVzY3JpcHRpb24iOiAiRHBsdXMgQm9vdGxvYWRlciJ9LCB7IkltYWdlTmFtZSI6ICJaOlxcd29ya3NwYWNlXFxkZWJ1Z1xcaW1hZ2VzXFxpbWFnZV9kcFxcc2VjdXJlXFxrbTBfa200X2FwcC5iaW4iLCAiU3RhcnRBZGRyZXNzIjogMTM0Mjk5NjQ4LCAiRW5kQWRkcmVzcyI6IDEzNjMxNDg4MCwgIkZ1bGxFcmFzZSI6IGZhbHNlLCAiTWVtb3J5VHlwZSI6IDEsICJNYW5kYXRvcnkiOiB0cnVlLCAiRGVzY3JpcHRpb24iOiAiRHBsdXMgc2VjdXJlIGFwcGxpY2F0aW9uIn1d"

备注

ImageName 必需是带文件全路径的待烧录固件。
StartAddress/EndAddress 必需是十进制的地址值。
FullErase 必需是布尔值，表示是否需要擦除整个分区。
MemoryType 必需是十进制的值，目前支持的类型有：
- 0: RAM
- 1: NOR Flash
- 2: NAND Flash
Mandatory 必需是布尔值，表示是否为必须烧录的分区。
Description 描述信息，非必需。

如果自定义分区表，则不需要再指定 --image/--image-dir 参数。

支持远端串口烧录

如果 AmebaFlash Tool 运行在远端服务器上，本地通过 ssh 连接，但是烧录串口在本地 PC，此时需要通过网络连接串口，可以使用参数 --remote-server <REMOTE_SERVER>/--remote-password <REMOTE_PASSWORD> 指定远端服务器访问方式。

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

该参数需要在 Flash 烧录第 1 步带入。

DTR/RTS 配置

如果设备支持 DTR/RTS 控制模块自动进烧录模式，可以修改参数 AutoSwitchToDownloadModeWithDtrRts，同时配置 AutoSwitchToDownloadModeWithDtrRtsTimingFile 参数指定的 Reburn.cfg 文件，其中定义了 DTR/RTS 控制 AutoDownload 电路的时序，默认使用的 Realtek 公板自带的时序。

使能 DTR/RTS 控制模块自动进烧录模式，设置为 1。

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

同理，如果需要通过 DTR/RTS 控制模块烧录结束自动重启，配置 AutoResetDeviceWithDtrRts，同时配置 AutoResetDeviceWithDtrRtsTimingFile 参数指定的 Reset.cfg 文件。其中定义了 DTR/RTS 控制 AutoDownload 电路的时序，默认使用的 Realtek 公板自带的时序。

使能 DTR/RTS 控制模块可以自动重启设备，设置为 1。

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

Flash 写保护处理方法

下载固件过程中，可能会遇到 Flash 写保护置位，导致下载不了的情况，此时下载工具会停留在交互界面，引导使用者做进一步操作处理。参数 FlashProtectionProcess 可以帮助设置是否使能该功能， value 可以配置参数如下：

0： Tool 每次烧录遇到 Flash 写保护的情况，Console 会停留在交互界面，引导使用者做进一步操作处理。

1： Tool 会删除 Flash 写保护位，继续擦除/下载操作，结束后再把写保护置起来。

2： Tool 如果检测到 Flash 写保护，会取消擦除/下载。
"FlashProtectionProcess": 1

烧录结束后操作

参数 PostProcess 可以设置在烧录结束之后，需要对设备做的后续操作。

- NONE： 烧录结束后，不做任何操作。
- INDICATION： 烧录结束后，通过 GPIO/PWM 方式指示设备是否下载成功。
- RESET： 烧录结束后，自动重启设备。
- BOOT： 烧录结束后，自动跳转进 Ram 运行。
- REBURN： 烧录结束后，自动重启设备并进入下载模式。

备注

该参数需要在 Flash 烧录开始之前设置 Settings.json 文件并保存。

GPIO/PWM 指示

在生产线上通过 USB 接口下载固件时，自动识别哪些设备已成功下载，而无需重新连接或手动检查设备是一项重要的功能。利用 GPIO/PWM 指示功能，可以有效地实现这一目标。以下是这种功能的具体配置和实现方法：

参数 ProgramConfig (默认值: 0)，具体的配置位描述，参考下表。

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

备注

该参数需要在 Flash 烧录开始之前设置 Settings.json 文件并保存。

自动设置 4-Byte 寻址方式

在产线上，有可能会遇到大于 16MB 容量的 Flash，这时，如果不使能 4-Byte 寻址方式，会导致烧录过程访问不到大于 16MB 的区域，从而烧录失败。参数 AutoProgramSpicAddrMode4Byte 可以协助用户检查当前模块的容量，并根据该参数决定下一步是直接报错还是使能 4-Byte 寻址方式继续烧录。

0：不使能 4-Byte 寻址方式，直接报错。

1：使能 4-Byte 寻址方式，继续烧录。

备注

该参数需要在 Flash 烧录开始之前设置 Settings.json 文件并保存。

工具版本号查询

参数 -v/--version 可以查询当前工具的版本号。

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

CLI 帮助信息

工具支持的参数列表可以通过 --help 获取，如下所示

$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

配置文件 {AmebaFlash}/Settings.json 中，还支持一些额外的参数，协助用户更便捷地使用 AmebaFlash Tool。

安全启动烧录

如果您需要使用安全启动烧录，Flashloader 同样也需要进行安全启动配置，详细请参考安全启动的使用方法。

生成的前面的 flashloader 二进制文件覆盖至 AmebaFlash\Devices\Floaders 目录。

自动烧录方案

本章节详细内容请参考自动烧录方案。