zhangzhaopeng
/
sdk-hwV1.3
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
sdk-hwV1.3/lichee/xr806/appos/project/image_cfg/readme.md

269 lines
14 KiB
Markdown
Raw Normal View History

chore(other):sdk 裁减
2024-05-07 10:09:20 +00:00
# XRADIO MKimage & CFG File User Guide
> MKimage（打包工具）是XRadio芯片将编译生成的各个bin文件打包成一个image的工具，在各个系统平台均有对应版本的工具。
> MKimage的使用需要搭配一个对应的CFG文件，该文件使用Json语法标记了需要生成的image以及各个bin文件的信息。
> 本工程中提供以下常用工程配置和系统初始化流程的演示：
---
## CFG文件
> CFG文件包含整个image的组织结构，配置文件使用Json标记语言对bin文件的头部信息进行配置。
### 文件字段
> 如下是一个完整的cfg文件示例。
```
{
"magic" :"AWIH",
"version" :"0.5",
"extern":{"chk_ota_area":"false","add_ota_area":"false","verify":"CRC32"},
"image" :{"max_size": "1020K", "bin_num":6},
"OTA" :{"addr": "1024K", "size": "32K"},
"count" :6,
"section" :[
{"id": "0xa5ff5a00", "bin": "boot_40M.bin", "cert": "null", "flash_offs": "0K", "max_len": "32K", "sram_offs": "0x00268000", "ep": "0x00268101", "attr": "0x1"},
{"id": "0xa5fe5a01", "bin": "app.bin", "cert": "null", "flash_offs": "32K", "max_len": "48K", "sram_offs": "0x00201000", "ep": "0x00201101", "attr": "0x1","priv":[{"0":"0x1402000"}, {"2":"0x1430000"}]},
{"id": "0xa5fd5a02", "bin": "app_xip.bin", "cert": "null", "flash_offs": "80K", "max_len": "800K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x2"},
{"id": "0xa5fa5a05", "bin": "wlan_bl.bin", "cert": "null", "flash_offs": "970K", "max_len": "10K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f95a06", "bin": "wlan_fw.bin", "cert": "null", "flash_offs": "980K", "max_len": "36K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f85a07", "bin": "sys_sdd_40M.bin", "cert": "null", "flash_offs": "1016K", "max_len": "4K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{}
],
"raw_bin" :[
{"bin" :"boot.bin", "flash_offs": "901K"},
{"bin" :"sys_sdd.bin", "flash_offs": "1500K"},
{}
]
}
```
各字段含义如下，**加粗字段**为必选字段：
　　**magic** - 固件魔数，表头标识，固定为 AWIH
　　**version** - 版本号
　　extern - 额外参数，非必选项，具体参数如下
　　 chk_ota_area : 默认为true，设置为false时，检查bin文件重叠时不会与OTA区域对比，适用于将某些bin放在flash最后的情况
　　 add_ota_area : 默认为false，设置为true时，打包时候会添加OTA区域，适用于客户使用flash烧写器直接烧写生成的image的情况
　　 verify : 在image的最后添加校验数据（none/CRC32/MD5/SHA1/SHA256)，在OTA升级时会校验，默认为none
　　**image** - image的大小参数
　　 **max_size** : image的最大值（image1和image2区域的最大值）
　　 xz_max_size : ota压缩模式下compressed image的最大值，非ota压缩模式下，禁止使用该字段。
　　 bin_num : 实际进行打包的bin文件个数，不能大于count值
　　**OTA** - ota参数存储地址和大小，需要4K对齐
　　 **addr** : OTA区域的起始地址，必须以4K对齐
　　 **size** : OTA区域的长度，必须以4K对齐
　　count - 打包文件列表中文件的数目，可以忽略不写
　　**section** - 文件列表
　　**id** - bin文件的id
　　 boot_id : 0xa5ff5a00
　　 app_id : 0xa5fe5a01
　　 app_xip_id : 0xa5fd5a02
　　 wlan_bl_id : 0xa5fa5a05
　　 wlan_fw_id : 0xa5f95a06
　　 sys_sdd_id : 0xa5f85a07
　　 app_psram_id : 0xa5f65a09
　　**bin** - bin文件名字
　　**cert** - 该段bin文件对应的证书文件，null表示没有添加证书
　　flash_offs - 该段bin文件存放在 FLASH 中的位置偏移，若不填写，则软件自动放在上一个文件结束的位置，以1024 byte对齐
　　max_len - 该段bin文件可存放的最大空间长度，若不填写，则软件按照文件大小自动计算，以1024 byte对齐
　　**sram_offs** - 该段固件加载到SRAM中的地址偏移，0xFFFFFFFF为无效值，使用时忽略
　　**ep** - 该段固件的ENTRY POINT，0xFFFFFFFF为无效值，使用时忽略
　　**attr** - 表示该段固件属性
　　 [1:0]：文件类型，00-普通文件，01-可执行文件，10-XIP文件，11-保留
　　 [3:2]：加密类型，00-不加密，X1-带证书，1X-flash加密
　　 [4]：是否压缩bin文件，0-不是，1-是
　　 [5]：是否安全文件，0-不是，1-是
　　 [31:6]：保留
　　priv - private数据，用户可以填入每个bin的自定义数据，但某些已被系统使用的字段会被覆盖
　　 boot.bin priv[0]: [7:0]-OTA flash num
　　 boot.bin priv[0]: [31:8]-OTA size
　　 boot.bin priv[1]: [31:0]-OTA address
　　 boot.bin priv[2]: [15:0]-image max size
　　 boot.bin priv[2]: [31:16]-image xz max size
　　 每个bin priv[5]: [31:0]-next safety bin address
　　raw_bin - 裸bin文件，打包时候需要增加 -r 参数才会将其打包
　　 bin - bin文件名字
　　 flash_offs - 该段固件存放在 FLASH 中的位置偏移
### Flash_offs配置
> flash offset的配置要求如下：
> 1. boot.bin固定需要设置为0地址，app.bin地址需要4K对齐，默认设置为32k的偏移地址
> 2. 其他的bin文件的地址并没有强制性的要求，只要没有互相重叠并且不覆盖到sysinfo和OTA区域，都是可以正常运行的
### Bin文件重叠的解决
> 如果bin文件出现了互相重叠的情况，MKimage工具会进行自动计算，然后生成一个“image_auto_cal.cfg”文件
> 用户可以直接使用该cfg文件重新进行打包，也可手动修改默认的image.cfg文件
> **注意:**如果全部的bin文件在经过自动计算后，其大小依然超过sysinfo的默认位置(OTA ADDRESS - 4K)，则不会生成“image_auto_cal.cfg”文件，此时，用户需要自己手动进行cfg文件的修改
```
cfg string:
{
"magic" : "AWIH",
"version" : "0.4",
"OTA" : {"addr": "1024K", "size": "4K"},
"image" : {"max_size": "1020K"},
"count" : 6,
"section" :
[
{"id": "0xa5ff5a00", "bin": "boot_40M.bin", "cert": "null", "flash_offs": "0K", "sram_offs": "0x00268000", "ep": "0x00268101", "attr": "0x1"},
{"id": "0xa5fe5a01", "bin": "app.bin", "cert": "null", "flash_offs": "32K", "sram_offs": "0x00201000", "ep": "0x00201101", "attr": "0x1"},
{"id": "0xa5fd5a02", "bin": "app_xip.bin", "cert": "null", "flash_offs": "50K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x2"},
{"id": "0xa5fa5a05", "bin": "wlan_bl.bin", "cert": "null", "flash_offs": "980K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f95a06", "bin": "wlan_fw.bin", "cert": "null", "flash_offs": "985K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f85a07", "bin": "sys_sdd_40M.bin", "cert": "null", "flash_offs": "1017K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{}
]
}
err: bin 1 and bin 2 were overlaped!
Overlapped size: 2248 Byte(3kB)
bin 1 name:app.bin begin: 0x00008000 end: 0x0000D0C8
bin 2 name:app_xip.bin begin: 0x0000C800
We've rearranged bin files and generated new cfg file 'image_auto_cal.cfg', the new one is recommended.
Generate image file failed
make: *** [image] 错误 255
```
> 上图显示，app.bin和app_xip.bin重叠了，app.bin超出了3K的数据，覆盖了app_xip.bin前面3K数据
> 说明给app.bin的空间太小了，此时可以调整app_xip.bin的flash_offs，由原来的50K调整为80K即可，剩下的27K做为预留空间。
---
## 工具使用
### 参数说明
> MKimage使用命令行方式运行，除了windows平台下的EXE可以双击运行，此时使用的参数都是默认值
> 工具支持的参数说明如下，**加粗**的为常用参数：
| 参数 | 说明 |
| -------------------------- | ----------------------------------------------------------- |
| **-c <cfg file path>** | cfg文件的路径，默认为“image.cfg” |
| -C <image oper> | image操作模式，默认为0<br>0-仅打包<br>1-仅合并（不含OTA区域，包含第二个文件的boot.bin）<br>2-打包并合并固件（不含OTA区域，包含第二个文件的boot.bin）<br>3-仅合并生成裸数据固件（包含OTA区域，不含第二个文件的boot.bin）<br>4-打包并生成裸数据固件（包含OTA区域，不含第二个文件的boot.bin） |
| -e <flash crypto> | Flash加密使用，默认不使用 |
| -f <Combine File 1st> | 生成合并固件所需的第一个文件路径，默认与打包输出的文件路径相同（即-o参数的值）|
| -F <Combine File 2nd> | 生成合并固件所需的第二个文件路径，无默认值 |
| -I <Combine File path> | 生成合并固件的路径，无默认值 |
| **-o <Output image path>** | 打包生成的文件路径，默认为“xr_system.img” |
| **-O** | 使能OTA功能，默认不使能 |
| -p | 使能OTA功能，并且将OTA区域写入生成文件，默认不使能 |
| -r | 打包时一并打入raw bin字段的文件，默认不打入 |
| -h | 帮助信息 |
| -v | 版本查看 |
---
## 使用示例
### 打包生成使能OTA功能的固件
> 使用命令：
```
mkimage.exe -O
```
> 打印输出：
```
E:\project\IOT\tools\xr-mkimage\Release>mkimage.exe -O
cfg string:
{
"magic" : "AWIH",
"version" : "0.4",
"OTA" : {"addr": "1024K", "size": "4K"},
"image" : {"max_size": "1020K"},
"count" : 6,
"section" :
[
{"id": "0xa5ff5a00", "bin": "boot_40M.bin", "cert": "null", "flash_offs": "0K", "sram_offs": "0x00268000", "ep": "0x00268101", "attr": "0x1"},
{"id": "0xa5fe5a01", "bin": "app.bin", "cert": "null", "flash_offs": "32K", "sram_offs": "0x00201000", "ep": "0x00201101", "attr": "0x1","priv":[{"0":"0x1402000"}, {"2":"0x1430000"}]},
{"id": "0xa5fd5a02", "bin": "app_xip.bin", "cert": "null", "flash_offs": "80K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x2"},
{"id": "0xa5fa5a05", "bin": "wlan_bl.bin", "cert": "null", "flash_offs": "980K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f95a06", "bin": "wlan_fw.bin", "cert": "null", "flash_offs": "990K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f85a07", "bin": "sys_sdd_40M.bin", "cert": "null", "flash_offs": "1016K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{}
]
}
generate image: xr_system.img
```
### 打包并生成合并固件
> 使用命令：
```
mkimage.exe -O -C 2 -F xr872_40m_etf-v1.0.0-rel-20200302.img -I xr_system.cimg
```
> 打印输出：
```
E:\project\IOT\tools\xr-mkimage\Release>mkimage.exe -O -C 2 -F xr872_40m_etf-v1.0.0-rel-20200302.img -I xr_system.cimg
cfg string:
{
"magic" : "AWIH",
"version" : "0.4",
"OTA" : {"addr": "1024K", "size": "4K"},
"image" : {"max_size": "1020K"},
"count" : 6,
"section" :
[
{"id": "0xa5ff5a00", "bin": "boot_40M.bin", "cert": "null", "flash_offs": "0K", "sram_offs": "0x00268000", "ep": "0x00268101", "attr": "0x1"},
{"id": "0xa5fe5a01", "bin": "app.bin", "cert": "null", "flash_offs": "32K", "sram_offs": "0x00201000", "ep": "0x00201101", "attr": "0x1","priv":[{"0":"0x1402000"}, {"2":"0x1430000"}]},
{"id": "0xa5fd5a02", "bin": "app_xip.bin", "cert": "null", "flash_offs": "80K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x2"},
{"id": "0xa5fa5a05", "bin": "wlan_bl.bin", "cert": "null", "flash_offs": "980K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f95a06", "bin": "wlan_fw.bin", "cert": "null", "flash_offs": "990K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f85a07", "bin": "sys_sdd_40M.bin", "cert": "null", "flash_offs": "1016K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{}
]
}
generate image: xr_system.img
generate combine image: xr_system.cimg
```
### 打包并生成裸数据固件
> 使用命令：
```
mkimage.exe -O -C 4 -F xr872_40m_etf-v1.0.0-rel-20200302.img -I xr_system_raw.bin
```
> 打印输出：
```
E:\project\IOT\tools\xr-mkimage\Release>mkimage.exe -O -C 4 -F xr872_40m_etf-v1.0.0-rel-20200302.img -I xr_system_raw.bin
cfg string:
{
"magic" : "AWIH",
"version" : "0.4",
"OTA" : {"addr": "1024K", "size": "4K"},
"image" : {"max_size": "1020K"},
"count" : 6,
"section" :
[
{"id": "0xa5ff5a00", "bin": "boot_40M.bin", "cert": "null", "flash_offs": "0K", "sram_offs": "0x00268000", "ep": "0x00268101", "attr": "0x1"},
{"id": "0xa5fe5a01", "bin": "app.bin", "cert": "null", "flash_offs": "32K", "sram_offs": "0x00201000", "ep": "0x00201101", "attr": "0x1","priv":[{"0":"0x1402000"}, {"2":"0x1430000"}]},
{"id": "0xa5fd5a02", "bin": "app_xip.bin", "cert": "null", "flash_offs": "80K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x2"},
{"id": "0xa5fa5a05", "bin": "wlan_bl.bin", "cert": "null", "flash_offs": "980K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f95a06", "bin": "wlan_fw.bin", "cert": "null", "flash_offs": "990K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{"id": "0xa5f85a07", "bin": "sys_sdd_40M.bin", "cert": "null", "flash_offs": "1016K", "sram_offs": "0xffffffff", "ep": "0xffffffff", "attr": "0x1"},
{}
]
}
generate image: xr_system.img
generate raw image: xr_system_raw.bin
```
## 参考文档
> 《XRADIO_MKimage_Tool_User_Guide-CN》