3.11.5. 镜像配置文件

当使用 mk_image.py 打包生成烧录镜像文件时，需要使用对应的 JSON 配置文件描述具体的打包数据和处理流程。

3.11.5.1. 配置文件总览

该 JSON 文件通过嵌套对象的方式，描述一个待生成的镜像文件所包含的数据和信息。其中最终输出的 “image” 对象，由 “info” 数据，”updater” 数据，”target” 数据组成，制作 “image” 的过程中需要生成和使用的临时文件由 “temporary” 描述。

{
    "image": {
            "info": {
                    "platform": "m4",
                    "product": "fpga_nand",
                    "version": "1.0.0",
                    "media": {
                            "type": "spi-nand",
                            "device_id": 0,
                            "nand_id" : ["0xef", "0xba", "0x21"],
                    }
            },

            "updater": {
                    "spl": {
                            "file": "u-boot-spl-updater.aic",
                            "attr": ["required", "run"],
                            "ram": "0x00103000"
                    },
                    "bootui": {
                            "file": "bootui.img",
                            "attr": "optional",
                            "ram": "0x80300000"
                    },
                    "env": {
                            "file": "env.bin",
                            "attr": ["required"],
                            "ram": "0x83100000"
                    },
                    "uboot": {
                            "file": "u-boot-updater.aic",
                            "attr": ["required", "run"],
                            "ram": "0x80007F00"
                    }
            },

            "target": {
                    "spl": {
                            "file": "u-boot-spl.aic",
                            "attr": ["mtd", "required", "burn"],
                            "part": ["spl"]
                    },
                    "uboot": {
                            "file": "u-boot-dtb.img",
                            "attr": ["mtd", "required", "burn"],
                            "part": ["uboot"]
                    },
                    "env": {
                            "file": "env.bin",
                            "attr": ["mtd", "required", "burn"],
                            "part": ["env", "envbak"]
                    },
                    "bootui": {
                            "file": "bootui.img",
                            "attr": ["mtd", "optional", "burn"],
                            // <mtd part name>:<ubi volume name>
                            "part": ["bootui"]
                    },
                    "dtb": {
                            "file": "u-boot.dtb",
                            "attr": ["mtd", "required", "burn"],
                            "part": ["dtb"]
                    },
                    "kernel": {
                            "file": "Image.gz",
                            "attr": ["mtd", "required", "burn"],
                            "part": ["kernel"]
                    },
                    "rootfs": {
                            "file": "rootfs.ubifs",
                            "attr": ["ubi", "optional", "burn"],
                            "part": ["ubiroot:rootfs"]
                    },
                    "app": {
                            "file": "user.img",
                            "attr": ["ubi", "optional", "burn"],
                            "part": ["ubisystem:user"]
                    }
            }
    },

    "temporary": {
            "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": "m4.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",
                            },
                    },
            },
            "itb": {
                    "u-boot.itb": {
                            "its": "u-boot.its"
                    },
            },
    },
}

3.11.5.2. Info 数据描述

“info” 对象用于描述该烧录镜像的基本信息，这些信息用于生成 Image Header。

其中 “info” 对象可配置的信息有：

“platform”

当前项目所使用的芯片型号。以字符串形式提供。

“product”

使用镜像文件的产品型号/名字。以字符串形式提供。

“version”

镜像的版本信息，以字符串形式提供。

“media”

镜像文件可烧录的存储介质信息组成的对象。其中包含

“type”: 存储介质的类型，以字符串形式提供。可填写的类型:
- “mmc” 当存储介质为 eMMC/SD Card 时填写 “mmc”
- “spi-nand”
- “spi-nor”
“device_id”: 要烧录的存储介质 ID 号

当设备上有多个相同类型的存储设备是，需要提供存储设备的 ID 号。比如设备上同时又 eMMC 和 SD 卡。
“nand_id”: NAND 器件的厂商 ID 号，当存储设备为 “spi-nand” 时，需要提供。

NAND ID 应以16进制字符串的数组的形式提供，如 [“0xef”, “0xba”, “0x21”]。填写 NAND ID 的原因是在制作 UBIFS 时，需要知道具体的 NAND 器件的参数，如 Block 大小， Page 大小等。因此这里提供 NAND ID，以便在制作 UBIFS 时查询。

3.11.5.3. Updater 数据描述

Updater 是进行 USB 升级或者进行 SD 卡时需要运行的 SPL/U-Boot 程序，该程序可能与正常启动时所运行的 SPL/U-Boot 相同，也可能不同，因此需要单独列出。

“updater” 对象描述在升级过程中需要使用到的组件数据。其中下列的组件数据是已知和必要的。

“spl”: 第一级引导程序。
“env”: 升级时 U-Boot 所用的环境变量内容。
“uboot”: 第二级引导程序，升级的具体功能实现在里面。

上述的组件名字并非固定，可根据项目的需要修改、增加或者删除。

Updater 中的组件数据对象都有以下的配置字段：

“file” : 指定该组件的数据来源文件
“ram” : USB 升级时，指定该文件下载的内存地址
“attr” : 该数据对象的属性，可选的内容有:
- “required” : 该数据是必需的，如果指定文件不存在，则生成镜像文件出错。
- “optional” : 该数据不是必需的，如果指定文件不存在，则在生成镜像文件时忽略该数据对象。
- “run” : 该数据是可执行文件，USB 升级时，该数据下载完成之后会被执行。

重要

“updater” 中组件对象的顺序很重要。

在 USB 升级的过程中，组件数据传输和执行的顺序即为 “updater” 中组件数据出现的顺序，因此如果组件数据之间有顺序依赖关系，需要按照正确的顺序排布。

3.11.5.4. Target 数据描述

“target” 描述要烧录到设备存储介质上的组件数据。与 “updater” 中的组件一样，”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” 中组件数据出现的顺序。

3.11.5.5. Temporary 数据描述

“temporary” 描述的是镜像文件生成过程中需要生成的中间文件。通过描述数据对象的方式，描述不同类型的中间文件的生成过程，可用于对组件的签名、加密、再次打包等处理。

当前支持下列两种不同的数据处理：

“aicboot” 描述 AIC 启动镜像的生成
“itb” 描述 FIT Image 的打包

AIC 启动镜像

AIC 启动镜像是 BROM 解析和执行的启动程序文件，其格式如 AIC启动镜像格式所描述。当需要在打包过程中生成一个中间的 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": "m4.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 文件。