2.6. 烧录镜像¶
Luban SDK 编译的最终输出结果是一个用于烧录到目标平台的镜像文件。
2.6.1. 镜像格式¶
ArtInChip 的烧录镜像文件由组件(FirmWare Component) 以及对应的组件元信息组成。 数据分布如下图所示。
图 2.47 烧录镜像格式¶
其中一些需要打包的数据文件，都被当做组件(FWC)进行处理，包括 SPL，U-Boot，Kernel，DTB 等数据。
Image Header 的具体格式如下：
struct artinchip_fw_hdr{
char magic[8]; // 固定为 "AIC.FW"
char platform[64]; // 该镜像文件适用的芯片平台
char product[64]; // 该镜像文件适用的产品型号
char version[64]; // 该镜像的版本
char media_type[64]; // 该镜像文件可烧录的存储介质
u32 media_dev_id; // 该镜像文件可烧录的存储介质 ID
u8 nand_array_org[64]; // NAND Cell Array 的组织
u32 meta_offset; // FWC Meta Area start offset
u32 meta_size; // FWC Meta Area size
u32 file_offset; // FWC File data Area start offset
u32 file_size; // FWC File data Area size
u8 padding[]; // Pad to 2048
};
FWC Meta 的格式如下：
struct artinchip_fwc_meta {
char magic[8]; // 固定为 "META"
char name[64]; // 对应组件的名字
char partition[64]; // 该组件要烧录的分区名字
u32 offset; // 该组件数据在镜像文件中的偏移
u32 size; // 该组件数据的大小
u32 crc32; // 该组件数据的CRC32校验值
u32 ram; // 当组件要下载到平台 RAM 时，要下载的地址
char attr[64] // 该组件的属性，字符串表示
u8 padding[296]; // Pad to 512
};
2.6.2. 制作工具¶
工具 |
说明 |
|---|---|
mkimage |
用于：
- 制作 uImage 格式的 U-Boot 镜像
- 制作 FIT 镜像
- 对 FIT 镜像进行签名
|
mkenvimage |
用于：编译生成 env.bin
|
mk_image.py |
用于：
- 制作 AIC 格式的启动镜像，包括签名和加密
- 打包固件组件，生成用于升级的固件镜像文件。
tools/scripts/mk_image.py
|
2.6.3. 配置文件¶
使用 mk_image.py 制作烧录镜像时，需要提供 image_cfg.json 镜像配置文件。
该配置文件通过嵌套对象的方式，描述一个待生成的镜像文件所包含的信息和数据。如下面的示例，该描述文件分为几部分：
镜像烧录的目标设备描述：分区表的配置
最终镜像的内容描述：信息和内容排布
中间文件的描述
{
"mmc": { // Media type
"size": "8G", // Size of SD/eMMC
"partitions": { // Partition table apply to device
"spl_1": { "offset": "0x4400", "size": "128k" },
"spl_2": { "size": "367k" },
"uboot": { "size": "1m" },
"env": { "size": "512k" },
"kernel": { "size": "16m" },
"rootfs": { "size": "64m" },
"user": { "size": "-" },
},
},
"image": {
"info": { // Header information about image
"platform": "d211",
"product": "per1_mmc",
"version": "1.0.0",
"media": {
"type": "mmc",
"device_id": 0,
}
},
"updater": { // Image writer which is downloaded to RAM by USB
"spl": {
"file": "u-boot-spl-dtb.aic",
"attr": ["required", "run"],
"ram": "0x00103000"
},
"env": {
"file": "env.bin",
"attr": ["required"],
"ram": "0x83100000"
},
"uboot": {
"file": "u-boot-dtb.aic",
"attr": ["required", "run"],
"ram": "0x80007F00"
}
},
"target": { // Image components which will be burn to device's partitions
"spl": {
"file": "u-boot-spl-dtb.aic",
"attr": ["required"],
"part": ["spl_1"]
},
"uboot": {
"file": "u-boot-dtb.img",
"attr": ["block", "required"],
"part": ["uboot"]
},
"env": {
"file": "env.bin",
"attr": ["block", "required"],
"part": ["env"]
},
"kernel": {
"file": "kernel.itb",
"attr": ["block", "required"],
"part": ["kernel"]
},
"rootfs": {
"file": "rootfs.ext4",
"attr": ["block", "required"],
"part": ["rootfs"]
},
"app": {
"file": "user.ext4",
"attr": ["block", "optional"],
"part": ["user"]
},
},
},
"temporary": { // Pre-proccess to generate image components from raw data
"aicboot": {
"u-boot-spl-dtb.aic": {
"head_ver": "0x00010000",
"loader": {
"file": "u-boot-spl-dtb.bin",
"load address": "0x103100",
"entry point": "0x103100",
},
},
"u-boot-dtb.aic": {
"head_ver": "0x00010000",
"loader": {
"file": "u-boot-dtb.bin",
"load address": "0x80008000",
"entry point": "0x80008000",
},
},
},
"uboot_env": {
"env.bin": {
"file": "env.txt",
"size": "0x4000",
},
},
"itb": {
"kernel.itb": {
"its": "kernel.its"
},
},
},
}
2.6.3.1. 分区表描述¶
image_cfg.json 文件的开头首先描述的是当前要烧录的目标存储设备，以及在设备上的分区配置。
"<media type>": {
"size": "xx",
"partitions": {
"<part n>": {
"offset": "yy",
"size": "zz",
"ubi": {
"offset": "ii",
"size": "jj",
}
}
}
}
存储设备 |
说明 |
|---|---|
“mmc” |
eMMC 和 SD Card 设备 |
“spi-nand” |
SPI NAND 设备 |
“spi-nor” |
SPI NOR 设备 |
存储设备 的名字仅可使用上述列表所指定的名字。
存储设备 的可设置属性有：
存储设备对象的属性名 说明 |
|
|---|---|
“size” |
值为字符串。
设备的存储大小(Byte)，可使用 “K,M,G” 单位，e.g. “8G”
|
“partitions” |
是
分区表 对象。包含该存储设备的详细分区列表，每一个子对象为一个
分区。 |
分区 对象的属性有：
分区对象的属性名 说明 |
|
|---|---|
“offset” |
值为16进制字符串。
表示该
分区 的开始位置离 存储设备 的开始位置的偏移（字节）。如果 “offset” 不出现，表示当前分区紧接上一个分区。
|
“size” |
值为字符串。
设备的存储大小(Byte)，可使用 “K,M,G” 单位，e.g. “8G”。
最后一个分区可以使用 “-” 表示使用剩下所有的空间。
|
“ubi” |
是
UBI Volume 表 对象。当存储设备为 “spi-nand” 时出现，表示当前 MTD 分区是一个 UBI 设备。
该对象描述 UBI 设备中的 Volume 表。每一个子对象为一个
UBI Volume 。 |
UBI Volume 对象的属性有:
UBI Volume对象的属性名 |
说明 |
|---|---|
“offset” |
值为16进制字符串。
表示该
Volume 的开始位置离 MTD 分区的开始位置的偏移（字节）如果 “offset” 不出现，表示当前 Volume 紧接上一个 Volume。
|
“size” |
值为字符串。
设备的存储大小(Byte)，可使用 “K,M,G” 单位，e.g. “8G”
最后一个分区可以使用 “-” 表示使用剩下所有的空间。
|
2.6.3.2. Image 文件描述¶
“image” 对象描述要生成的镜像文件的基本信息，以及要打包的数据。包含几个部分：
“info”
“updater”
“target”
"image": {
"info": {
...
}
"updater": {
...
}
"target": {
...
}
}
2.6.3.2.1. Info 数据描述¶
“info” 对象用于描述该烧录镜像的基本信息，这些信息用于生成 Image Header。
"info": {
"platform": "<soc name>",
"product": "<product name>",
"version": "x.y.z",
"media": {
"type": "<media type>",
"device_id": n,
"array_organization": {
"page": "xx",
"block": "yy",
}
}
}
info 属性 |
说明 |
|---|---|
“platform” |
字符串，当前项目所使用的 SoC 的名字 |
“product” |
字符串，产品名字、产品型号 |
“version” |
字符串，按照 “x.y.z” 格式提供的版本号，其中 x,y,z 都是数字 |
“media” |
对象，描述存储设备 |
media 属性 |
说明 |
|---|---|
“type” |
字符串，取值可参考 存储设备类型 |
“device_id” |
整数，要烧录的存储设备在 U-Boot 中的索引。 |
“array_organization” |
对象，当存储设备为 “spi-nand” 时使用，描述存储单元的排列结构 |
array_organization 属性 |
说明 |
|---|---|
“page” |
当前 SPI NAND 的 Page 大小，取值 “2K”, “4K”, |
“block” |
当前 SPI NAND 的 Block 大小, 取值 “128K”, “256K” |
2.6.3.2.2. Updater 数据描述¶
Updater 是指进行 USB 刷机或者进行 SD 卡刷机时需要运行的刷机程序，该程序通常由 SPL/U-Boot 实现， 可能与正常启动时所运行的 SPL/U-Boot 相同，也可能不同，因此需要单独列出。
“updater” 对象描述在刷机过程中需要使用到的组件数据，其包含多个子对象，每个子对象即为一个 组件 。
其中下列的 组件 是已知且必要的。
组件名称 |
说明 |
|---|---|
“spl” |
第一级引导程序 |
“env” |
刷机版 U-Boot 所需要使用的环境变量内容 |
“uboot” |
第二级引导程序，同时也是刷机程序 |
上述的组件名字并非固定，可根据项目的需要修改、增加或者删除。
Updater 中的 组件 对象都有以下的配置字段：
Updater 组件属性 |
说明 |
|---|---|
“file” |
指定该组件的数据来源文件
|
“ram” |
USB 刷机时，指定该文件下载的内存地址
|
“attr” |
该数据对象的属性，可选的内容有:
- “required” : 该数据是必需的，如果指定文件不存在，则生成镜像文件出错。
- “optional” : 该数据不是必需的，如果指定文件不存在，则在生成镜像文件时忽略该数据对象。
- “run” : 该数据是可执行文件，USB 升级时，该数据下载完成之后会被执行。
|
重要
“updater” 中 组件 对象的顺序很重要。
在 USB 升级的过程中，组件数据传输和执行的顺序即为 “updater” 中组件数据出现的顺序， 因此如果组件数据之间有顺序依赖关系，需要按照正确的顺序排布。
2.6.3.2.3. Target 数据描述¶
“target” 描述要烧录到设备存储介质上的 组件 。与 “updater” 中的组件一样，”target”
中出现的组件根据实际需要进行添加，组件的名字也可自行定义。
“target” 中的组件，都有下面的配置字段：
Target 组件属性 |
说明 |
|---|---|
“file” |
指定该组件的数据来源文件
|
“part” |
指定该组件被烧录的分区
分区名字通过字符串数组的形式提供，如果一个组件被烧录到多个分区，则在数组中提供多个分区的名字，
如 [“uboot1”, “uboot2”]。
对于 UBI 的卷，使用 “<MTD Part>:<UBI Volume>” 的形式提供，如 [“ubiboot:kernel”]。
这里 “ubiboot” 是该 UBI 设备所在的 MTD 分区名字，”kernel” 是该 UBI 设备中的 Volume 名字。
|
“attr” |
该数据对象的属性，可选的内容有:
- “required” : 该组件数据是必需的，如果指定文件不存在，则生成镜像文件出错。
- “optional” : 该组件数据不是必需的，如果指定文件不存在，则在生成镜像文件时忽略该数据对象。
- “burn” : 该组件数据是需要烧录到指定分区当中。
- “mtd” : 表示该组件要烧录的设备是 MTD 设备。
- “ubi” : 表示该组件要烧录的设备是 UBI 设备。
- “block” : 表示该组件要烧录的设备是块设备。
|
重要
“target” 中组件对象的顺序
在 USB 升级的过程中，组件数据传输和烧录的顺序即为 “target” 中组件数据出现的顺序。
2.6.3.3. 中间文件描述¶
“temporary” 描述的是镜像文件生成过程中需要生成的中间文件。通过描述数据对象的方式， 描述不同类型的中间文件的生成过程，可用于对组件的签名、加密、再次打包等处理。
当前支持下列两种不同的数据处理：
“aicboot”
描述 AIC 启动镜像的生成
“itb”
描述 FIT Image 的打包
AIC 启动镜像
AIC 启动镜像是 BROM 解析和执行的启动程序文件。 当需要在打包过程中生成一个中间的 AIC 启动镜像文件时，需要在 “aicboot” 对象中添加一个子对象， 其对象名字即为生成的文件名字，可配置的内容如下面的示例所示。所列的属性中，只有 “loader” 是必需的， 其他的可根据项目需要进行删减。
"aicboot": {
"u-boot-spl.aic": {
"head_ver": "0x00010000",
"anti-rollback counter": 1,
"loader": {
"file": "u-boot-spl.bin",
"load address": "0x103100",
"entry point": "0x103100",
},
"resource": {
"private": "private.bin",
"pubkey": "rsa_pub_key.der",
"pbp": "d211.pbp",
},
"encryption": {
"algo": "aes-128-cbc",
"key": "aes-128-cbc-key.bin",
"iv": "aes-128-cbc-iv.bin",
},
"signature": {
"algo": "rsa,2048",
"privkey": "rsa-2048-private.der",
},
},
}
FIT Image
FIT Image 是 U-Boot 中常用的数据打包方式，用于将一些相关的启动数据打包在一起，
使用 .its 文件描述打包过程。
如果生成烧录镜像文件的过程中，有些数据需要打包组合为一个 FIT Image 文件，则可以在
“itb” 对象中添加一个子对象，其对象名字即为生成的文件名字，可配置的内容位描述该打包
过程的 .its 文件。
"itb": {
"u-boot.itb": {
"its": "u-boot.its"
},
},
烧录镜像文件生成过程中，会调用相应的 mkimage 工具生成 itb 文件。