HiSpark编程指南
前言¶
概述
本文档主要介绍BurnTool的使用方法。用于指导工程人员快速使用BurnTool工具进行镜像烧写。
产品版本
与本文档相对应的产品版本如下。
产品名称 |
产品版本 |
|---|---|
BS2X |
V100 |
读者对象
本文档主要适用于以下工程师：
技术支持工程师
软件工程师
硬件工程师
符号约定
在本文中可能出现下列标志，它们所代表的含义如下。
符号 |
说明 |
|---|---|
|
表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。 |
|
表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。 |
|
表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。 |
|
用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。 |
|
对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。 |
修改记录
文档版本 |
发布日期 |
修改说明 |
|---|---|---|
04 |
2025-01-14 |
更新“手动烧写”小节内容。 |
03 |
2024-09-14 |
|
02 |
2024-07-05 |
|
01 |
2024-05-15 |
第一次正式版本发布。 |
00B03 |
2024-01-08 |
|
00B02 |
2023-10-27 |
删除“命令行烧写”小节。 |
00B01 |
2023-09-27 |
第一次临时版本发布。 |
BurnTool工具简介¶
功能说明¶
BurnTool是芯片配套的烧写工具，通过打断程序启动的方式，对单板烧写镜像文件。
应用场景¶
BurnTool主要适用于以下场景：
镜像烧写
导出镜像
界面说明¶
选择Chip¶
通过“Option”-“Change chip”打开芯片选择框，用于选择与单板匹配的芯片类型，部分芯片还可选择需要的烧写方式，界面如图1所示。
图 1 选择Chip界面示意图
表 1 选择Chip界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
BurnTool¶
BurnTool界面如图1所示。
图 1 BurnTool界面示意图
表 1 BurnTool界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
Send file：按照表格选中信息依次烧写镜像。 |
6 |
镜像表格：显示可被烧写的镜像信息。各列含义为：
|
7 |
烧写进度。 |
8 |
回显视图：显示打断之后单板上报的数据。 |
9 |
|
10 |
Reset：重启单板。(本功能仅在烧写loader之后生效) Erase all：全片擦除。(本功能仅在烧写loader之后生效) |
11 |
Export：导出镜像。(本功能仅在烧写loader之后生效) |
12 |
|
13 |
Multiple burn：进入工厂烧写界面。 |
14 |
|
BurnTool-Dfu¶
DFU升级界面如图1所示，Auto DFU烧写界面如图2所示，Hid DFU升级界面如图3所示
图 1 DFU升级界面
图 2 Auto DFU烧写界面
图 3 Hid DFU升级界面
表 1 Dfu烧写界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
镜像表格：显示可被烧写的镜像信息。各列含义为：
|
7 |
|
8 |
|
9 |
|
10 |
|
BurnTool-Jlink¶
Jlink烧写界面如图1所示
图 1 Jlink烧写界面
表 1 Jlink烧写界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
Select file：选择格式为fwpkg的烧写镜像。 |
3 |
Start burn：按照表格选中信息依次烧写镜像。 |
4 |
镜像表格：显示可被烧写的镜像信息。各列含义如下。
|
5 |
烧写进度。 |
6 |
日志视图：显示烧写过程中单板上报的日志及工具打印的日志。 |
BurnTool-OTA升级¶
OTA升级界面如图1所示
图 1 OTA升级界面示意图
表 1 Jlink烧写界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
镜像表格：显示可被烧写的镜像信息。各列含义如下。
|
9 |
|
10 |
|
工厂烧写¶
工厂烧写功能用于大批量烧写场景。在打断之后根据表格中的选中顺序发送文件。工厂烧写界面如图1所示。
图 1 工厂烧写界面示意图
表 1 工厂烧写界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
3 |
烧写结果统计：成功数，失败数，成功率，本次烧写时间。 |
设置界面¶
设置界面主要用于设置串口参数，设置界面如图1所示。
图 1 设置界面示意图
表 1 设置界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
3 |
|
选择Jlink执行程序界面¶
通过“Setting”-“Jlink Settings”打开Jlink设置，用来配置Jlink执行程序路径，界面如图1所示。
图 1 选择Jlink执行程序界面
表 1 选择JJlink执行程序界面说明
区域 |
说明 |
|---|---|
1 |
|
2 |
|
操作指南¶
手动烧写¶
串口烧写¶
在BurnTool界面中单击“Select file”按钮，选择各产品编译生成的固件包，并单击“OK”。
在表格中选中需要烧写的文件（请参考各产品文档中关于烧写的部分）。
选择“Setting”→“Com settings”，配置串口参数，默认配置如图1所示。
说明：
Force Read Time：定时读取的时间，以毫秒为单位。勾选时为定时读取串口，不勾选时为事件触发读取串口。适用于不勾选该选项无法正常烧录的场景。图 1 串口设置示例
选择目标串口号并单击“Connect”按钮（单击后“Connect”变为“Disconnect”），复位单板。打断后效果如图2所示。
图 2 打断效果示意图
当界面显示字符串“CCC”时，单击“Send file”按钮。不同产品“CCC”上方的字符串可能不同。
等待传输完成后结束烧写，烧写完成会出现“All images burn successfully”。烧写完成效果如图3所示。
图 3 烧写完成示意图
DFU烧写¶
使用管理员权限打开程序（右键点击应用程序，点击以管理员身份运行，如图1所示）。
图 1 以管理员身份运行示意图
参考“选择Chip”章节选择带DFU后缀的芯片，如“XXX-USB”。
选择烧写模式，如图2所示，选择dfu升级模式。
图 2 烧写模式选择示意图
根据3选择的模式选择设备或者填写设备信息。Dfu模式时选择设备信息如图3所示。Auto dfu和 Hid dfu模式时填写设备信息如图4所示。
图 3 选择USB设备
图 4 填写usb设备信息
在BurnTool界面中单击“Select file”按钮，选择产品编译生成的固件包，并单击“打开”。
在表格中选中需要烧写的文件。
单击“Start burn”按钮（单击后“Start burn”变为“Stop burn”）。
等待传输完成后结束烧写，烧写完成会出现“All images burn successfully”。烧写完成效果如图5所示。
图 5 烧写完成示意图
警告：
警告：在打印“All images burn successfully”之前请一定不要断电，否则单板将有概率异常。
工厂烧写¶
在BurnTool界面中单击“Select file”按钮，选择各产品编译生成的固件包，并单击“OK”。
在表格中选中需要烧写的文件。
选择“Setting”→“Com settings”，配置串口参数，默认配置如图1所示。
图 1 串口设置示例
说明：
Total num在研发测试中最大已压测个数为20，实际烧录最大个数上限理论不限制，一般与电脑性能、夹具、接线稳定性有关。单击“Multiple burn”按钮，打开工厂烧写窗口，若已有配置会自动读取。若无配置手动选择串口后，可以选择“Setting”→“Save config”生成配置。
单击“Connect all”按钮，并复位所有单板。
等待所有回显视图都显示绿色“PASS”或红色“Fail”。
命令行烧写¶
串口烧写¶
在Windows环境下，BurnTool.exe支持以命令行的方式调用，可用于集成到用户已有的工厂产线烧写程序中，调用命令如下：
BurnTool.exe params
命令之间用空格隔开，如果命令带有参数，命令与参数之间用冒号隔开，最简示例如下：
BurnTool.exe -com:1 -bin:C:\test_bin\xxx.fwpkg -signalbaud:921600
BurnTool.exe烧写命令可以配置的params参数如表1所示。
表 1 BurnTool.exe烧写命令参数表
命令 |
参数 |
说明 |
|---|---|---|
-com: |
x |
PC端的串口号（例如：1）。 |
-bin: |
path\xxx.bin |
固件包xxx.bin的绝对路径。固件包的名称和文件类型根据各产品实际情况可能有所不同。（路径不能存在空格字符） |
-signalbaud: |
115200 |
RomBoot下传输固件包时的串口波特率，默认为115200bit/s。建议根据硬件支持情况，配置成921600bit/s或更高波特率，以提升烧写效率。 |
-2ms |
无 |
使用2ms间隔发送打断报文，常用于快速启动场景。不包含此参数时，间隔则为10ms。 |
-forceread: |
10 |
包含此参数表示打开串口定时读功能，读数据间隔为10ms。 一般无需打开，在如下场景可考虑打开：
|
-erasemode: |
x |
擦除模式。其中：
|
-timeout: |
x |
打断的超时时间，单位ms。 |
-console |
无 |
使用标准输入输出，为重定向做准备。 |
-clearlog |
无 |
屏蔽单板打印的日志。 |
-onlyeraseall |
无 |
仅进行全片擦除 |
-onlyburn: |
name |
指定烧写对应名字的文件，可重复传参，效果累加。 |
-reset |
无 |
烧写完成后自动重启设备。 |
-packagesize: |
x |
每次传输的包大小，当前支持1024，2048，4096，8192 |
-switchafterloader |
无 |
在加载loader完成后再切换波特率。 |
其他典型场景
如果需要使用标准输入输出获取烧写过程的打印，命令如下：
BurnTool.exe -com:1 -bin:C:\test_bin\xxx.fwpkg -signalbaud:921600 -console如果需要指定烧写一个烧录包中的其中两个bin文件，命令如下：
BurnTool.exe -com:1 -bin:C:\test_bin\xxx.fwpkg -signalbaud:921600 -onlyburn:a.bin -onlyburn:b.bin如果需要使用全片擦除且烧写完之后自动复位单板，命令如下：
BurnTool.exe -com:1 -bin:C:\test_bin\xxx.fwpkg -signalbaud:921600 -erasemode:1 -reset
DFU烧写¶
BurnTool.exe支持不打开界面，直接通过命令行进行参数设置与工具启动调度并烧写，可用于集成到用户已有的工厂产线烧写程序中。需在管理员权限下执行命令。调用命令如下：
BurnTool.exe params
使用C++代码管理员权限调用示例如下：
#include <windows.h>
int main(int argc, char *argv[])
{
char cmd[] = "D:\\BurnTool\\BurnTool.exe";
ShellExecuteA(NULL, "runas", cmd, "-dfu -vid:0x01 -pid:0x01 -usage:0x01 -usagepage:0x01 -bin:C:\test_bin\xxx.fwpkg -console", NULL, SW_NORMAL);
return 0;
}
命令之间用空格隔开，如果命令带有参数，命令与参数之间用冒号隔开，最简示例如下：
BurnTool.exe -dfu -pid:0x01 -vid:0x01 -usage:0x01 -usagepage:0x01 -bin:C:\test_bin\xxx.fwpkg
BurnTool.exe dfu模式烧写命令可以配置的params参数如表1所示
表 1 BurnTool.exe dfu模式烧写命令参数表
命令 |
参数 |
说明 |
|---|---|---|
-dfu |
- |
hid状态下dfu烧写模式。和-autodfu，-hiddfu互斥。 |
-autodfu |
- |
dfu状态下直接烧写模式。和-dfu, -hiddfu互斥。 |
-hiddfu |
- |
hid状态下直接进行usb烧写。和-autodfu，-dfu互斥。 |
-bin: |
path\xxx.fwpkg |
固件包xxx.fwpkg的绝对路径。固件包的名称和文件类型根据各产品实际情况可能有所不同。 说明：
路径不能包含空格字符。 |
-pid: |
0x... |
待烧写设备的pid。 说明：
参数为16进制数字。 |
-vid： |
0x... |
待烧写设备的vid。 说明：
参数为16进制数字。 |
-usage: |
0x... |
待烧写设备的usage。 说明：
参数为16进制数字。 |
-usagepage: |
0x... |
待烧写设备的usagepage。 说明：
参数为16进制数字。 |
-console |
无 |
使用标准输入输出，为重定向做准备。 |
其他典型场景
如果需要使用标准输入输出获取烧写过程的打印，命令如下：
BurnTool.exe -dfu -pid:0x01 -vid:0x01 -usage:0x01 -usagepage:0x01 -bin:C:\test_bin\xxx.fwpkg -console
读eFuse¶
导出镜像¶
按照“串口烧写”烧写完成loader文件。
单击“Select target”按钮，选择导出文件的存放位置。
在“addr”编辑框中输入读取的Flash起始地址，在“size”编辑框中输入读取的Flash大小。
注意：“addr”应填写flash相对地址，相对地址等于绝对地址减去基地址0x90100000。
单击“Export”按钮，如图1所示。
图 1 导出文件结束示例
OTA升级¶
参考“选择Chip”章节选择带SLE后缀的芯片，如“XXX-SLE”。
选择设备信息如图1所示。
图 1 选择设备信息示意图
点击“Open”按钮，打开所选设备，并将扫描到的对端设备地址加载到Address中。
选择想要升级的地址，点击“Connect”连接设备，打印出"Device connected successfully"代表连接成功，如图2所示。
图 2 连接成功示意图
选择所升级的文件，如图3所示。
图 3 选择文件示意图
点击“Start”开始升级，“Start”按钮变更为“Stop”按钮（点击“Stop”按钮可停止升级），升级成功打印“Upgrade successfully”。如图4所示
图 4 升级成功示意图
FAQ¶
工具未进入打断状态¶
问题描述
单击连接、断电重启后，工具并没有进入打断状态。
解决办法
可能是串口选择错误或没有正常连接串口，请检查串口配置。
可能单板设置了1ms快速启动，需要在BurnTool“Setting”→“Burn interval”中选择2ms间隔。
可能使用win7系统产生部分兼容性问题，可切换至win10尝试。
如何获取符合格式的固件包¶
问题描述
如何获取BurnTool可识别的固件包。
解决办法
请参见各产品关于编译或固件生成的文档。
加载配置文件时出现错误提示¶
问题描述
在启动BurnTool后，如果同级目录或C盘BurnTool路径下有配置文件，则会提示“是否加载已存在的配置文件？”；如果选择加载配置文件且配置文件格式不正确，则会提示“文件格式错误，是否继续”。
解决办法
提示“文件格式错误，是否继续”表示当前的配置文件中有部分内容没有配置或配置值不符合预期，造成此问题的原因可能是由于手动修改过配置文件或当前版本没有主动保存过配置文件。此时可以选择不加载配置文件，全部重新手工配置并保存配置文件。
工厂烧写时随机串口无法进入doing状态¶
问题描述
因串口驱动配合问题，在工厂烧写时，可能会出现随机串口无法进入工作（doing）状态的情况。
解决办法
在“Setting”→“Settings”中查看“Reopen Com Everytime”的勾选状态。
如果未勾选，则尝试勾选并重新开始工厂烧写；如果已勾选，则尝试取消勾选并重新开始工厂烧写。
如何提升镜像烧录速度¶
问题描述
产线上烧录大镜像所需时间过长，导致生产成本增加。
解决办法
将烧写工具波特率设置为所能支持的最大值（目前单板所支持最大值为6M波特率，需串口小板支持6M及以上波特率）。
将每包大小设置为20480。如图1所示。
图 1 烧写工具配置示意图
按照“手动烧写”章节步骤进行烧写即可。
一拖多烧写时反复烧写该如何解决¶
问题描述
一拖多烧写时，每次烧写完成会重新开始烧写，具体表现为在没有进行手动复位的情况下，进度条达到100%后又从0%开始烧录。
解决办法
将设置中的“Reset after success”去勾选。