sdk-hwV1.3/lichee/xr806/appos/project/image_cfg

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文件的路径，默认为“image.cfg”
-C	image操作模式，默认为0 0-仅打包 1-仅合并（不含OTA区域，包含第二个文件的boot.bin） 2-打包并合并固件（不含OTA区域，包含第二个文件的boot.bin） 3-仅合并生成裸数据固件（包含OTA区域，不含第二个文件的boot.bin） 4-打包并生成裸数据固件（包含OTA区域，不含第二个文件的boot.bin）
-e	Flash加密使用，默认不使用
-f <Combine File 1st>	生成合并固件所需的第一个文件路径，默认与打包输出的文件路径相同（即-o参数的值）
-F <Combine File 2nd>	生成合并固件所需的第二个文件路径，无默认值
-I	生成合并固件的路径，无默认值
-o	打包生成的文件路径，默认为“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》