烧录镜像配置文件

使用 mk_image.py 制作烧录镜像时，需要提供 image_cfg.json 镜像配置文件。

通过嵌套对象的方式，image_cfg.json 描述了一个待生成的镜像文件所包含的信息和数据，如下列代码所示，该描述文件分为以下部分：

镜像烧录的目标设备描述，详情可查看分区表描述。
最终Image 文件描述，包括信息和内容排布，由 info 数据，updater 数据和 target 数据组成。
中间文件描述，制作 image 的过程中需要生成和使用的临时文件。

{
    "spi-nand": { // Device, The name should be the same with string in image:info:media:type
        "size": "128m", // Size of SPI NAND
        "partitions": {
            "spl": { "size": "1m" },
            "os":  { "size": "2m" },
            "rodata":  { "size": "4m" },
            "data":  { "size": "28m" },
        },
    },
    "image": {
        "info": { // Header information about image
            "platform": "d21x",
            "product": "demo128_nand",
            "version": "1.0.0",
            "media": {
                "type": "spi-nand",
                "device_id": 0,
                "array_organization": [
                    { "page": "2k", "block": "128k", "oob": "64" },
        //            { "page": "4k", "block": "256k", "oob": "128" },
                ],
            }
        },
        "updater": { // Image writer which is downloaded to RAM by USB
            "ddr": {
                "file": "usbupg-ddr-init.aic",
                "attr": ["required", "run"],
                "ram": "0x00103000"
            },
            "bootloader": {
                "file": "bootloader.aic",
                "attr": ["required", "run"],
                "ram": "0x41000000"
            },
        },
        "target": { // Image components which will be burn to device's partitions
            "bootloader": {
                "file": "bootloader.aic",
                "attr": ["mtd", "required"],
                "part": ["spl"]
            },
            "os": {
                "file": "os.aic",
                "attr": ["mtd", "required"],
                "part": ["os"]
            },
            "res": {
                "file": "app.fatfs",
                "attr": ["mtd", "optional"],
                "part": ["rodata"]
            },
            "app": {
                "file": "page_2k_block_128k_oob_64_data.uffs",
                "attr": ["uffs", "optional"],
                "part": ["data"]
            },
        },
    },
    "temporary": { // Pre-proccess to generate image components from raw data
        "aicboot": {
            "usbupg-ddr-init.aic": { // No loader, only PreBootProgram to initialize DDR
                "head_ver": "0x00010001",
                "resource": {
                    "private": "ddr_init.bin",
                    "pbp": "d21x.pbp",
                },
            },
            "bootloader.aic": {
                "head_ver": "0x00010001",
                "loader": {
                    "file": "bootloader.bin",
                    "load address": "0x42000000",
                    "entry point":  "0x42000100",
                },
                "resource": {
                    "private": "ddr_init.bin",
                    "pbp": "d21x.pbp",
                },
            },
            "os.aic": {
                "head_ver": "0x00010001",
                "loader": {
                    "file": "d21x.bin",
                    "load address": "0x40000000",
                    "entry point":  "0x40000100",
                    "run in dram": "false",
                }
            },
        },
    },
}

Edit online

分区表描述

image_cfg.json 文件的开头描述的是当前要烧录的目标存储设备，以及在设备上的分区配置，以 spi-nand 为例：

"spi-nand": { // Device, The name should be the same with string in image:info:media:type
    "size": "128m", // Size of SPI NAND
    "partitions": {
        "spl": { "size": "1m" },
        "os":  { "size": "2m" },
        "rodata":  { "size": "4m" },
        "data":  { "size": "28m" },
    },
},

该示例中各字段具体描述如下表所示：

表 1. 分区表描述
字段	值类型	描述
`media type`	String	存储设备类型该字段名字仅可使用此列表所指定的名字。 mmc：eMMC 和 SD Card 设备 spi-nand：SPI NAND 存储设备 spi-nor：SPI NOR 存储设备
size	String	存储设备的存储大小 (byte)，可设置。设备的存储大小 (Byte)，单位可为 K、M 或 G ，例如，8 G。
partitions	Object	分区表对象。包含该存储设备的详细分区列表，每一个子对象为一个分区。
offset	String	16 进制字符串。表示该分区的开始位置离存储设备的开始位置的偏移（字节）。如果此字段未出现，表示当前分区紧接上一个分区。
size	String	size：设备的存储大小 (Byte)，单位可为 K、M 或 G ，例如：2 m。最后一个分区可以使用 “-” 表示使用剩下所有的空间。
ubi	Object	UBI Volume 对象。当存储设备为 `spi-nand` 时出现，表示当前 MTD 分区是一个 UBI 设备。该对象描述 UBI 设备中的 Volume 表。每一个子对象为一个 UBI Volume 。 UBI Volume对象： offset：值为 16 进制字符串。表示该 Volume 的开始位置离 MTD 分区的开始位置的偏移（字节）。如果 offset不出现，表示当前 Volume 紧接上一个 Volume。 size：设备的存储大小 (byte)，单位为 K、M 或 G ，例如 2 m。最后一个分区可以使用 “-” 表示使用剩下所有的空间。

Edit online

Image 文件描述

“image” 对象描述要生成的镜像文件的基本信息，以及要打包的数据。包含几个部分：

“info”
“updater”
“target”

"image": {
    "info": {
        ...
    }
    "updater": {
        ...
    }
    "target": {
        ...
    }
}

Info 数据描述

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

"info": { // Header information about image
    "platform": "d211",
    "product": "demo128_nand",
    "version": "1.0.0",
    "media": {
        "type": "spi-nand",
        "device_id": 0,
        "array_organization": [
        //      { "page": "4k", "block": "256k" },
                { "page": "2k", "block": "128k" },
        ],
    }
},


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”

Updater 数据描述

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

“updater” 对象描述在刷机过程中需要使用到的组件数据，其包含多个子对象，每个子对象即为一个组件。其中下列的组件是已知且必要的。


组件名称	说明
“spl”	第一级引导程序
“U-Boot”	第二级引导程序，同时也是刷机程序

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

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


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

重要：

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

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

Target 数据描述

“target” 描述要烧录到设备存储介质上的组件。与 “updater” 中的组件一样，”target” 中出现的组件根据实际需要进行添加，组件的名字也可自行定义。

“target” 中的组件，都有下面的配置字段：

表 2. Target 组件属性
属性名	说明
“file”	指定该组件的数据来源文件。
“part”	指定该组件被烧录的分区，分区名字通过字符串数组的形式提供。
“attr”	该数据对象的属性，可选的内容有: “required” : 该组件数据是必需的，如果指定文件不存在，则生成镜像文件出错。 “optional” : 该组件数据不是必需的，如果指定文件不存在，则在生成镜像文件时忽略该数据对象。 “burn” : 该组件数据是需要烧录到指定分区当中。 “mtd” : 表示该组件要烧录的设备是 MTD 设备。 “ubi” : 表示该组件要烧录的设备是 UBI 设备。 “block” : 表示该组件要烧录的设备是块设备。

重要：

“target” 中组件对象的顺序

在 USB 升级的过程中，组件数据传输和烧录的顺序即为 “target” 中组件数据出现的顺序。

Edit online

中间文件描述

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

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

“aicboot”：描述 AIC 启动镜像的生成

AIC 启动镜像

AIC 启动镜像是 BROM 解析和执行的启动程序文件。当需要在打包过程中生成一个中间的 AIC 启动镜像文件时，需要在 “aicboot” 对象中添加一个子对象，其对象名字即为生成的文件名字，可配置的内容如下面的示例所示。所列的属性中，只有 “loader” 是必需的，其它的可根据项目需要进行删减：

"aicboot": {
    "usbupg-ddr-init.aic": { // No loader, only PreBootProgram to initialize DDR
        "head_ver": "0x00010001",
        "resource": {
            "private": "ddr_init.bin",
            "pbp": "d21x.pbp",
        },
    },
    "bootloader.aic": {
        "head_ver": "0x00010001",
        "loader": {
            "file": "bootloader.bin",
            "load address": "0x42000000",
                "entry point":  "0x42000100",
        },
        "resource": {
            "private": "ddr_init.bin",
            "pbp": "d21x.pbp",
        },
    },
    "os.aic": {
        "head_ver": "0x00010001",
        "loader": {
            "file": "d21x.bin",
            "load address": "0x40000000",
            "entry point":  "0x40000100",
            "run in dram": "false",
        }
    },
}