Image Layout

本节主要介绍Image格式和Flash布局。

Image格式

所有可支持升级的image都是由一个1280 Bytes大小的image header和不定长的payload部分组成。Image header会包含image类型、大小、版本号、哈希值和签名信息等。

Image header格式

Image header中各字段定义如下：

Image header中各字段定义

Memory Segment

Size(Bytes)

Functions

image_signature

384

image的签名，用于在开启secure boot时进行认证

image_hash

32

image的哈希校验，用于image完整性校验

image_control_header

12

image的控制信息，详细请参考 Image Control Header格式

uuid

16

image的UUID值

exe_base

4

image的执行地址

load_src

4

加载到RAM的代码起始地址

load_len

4

加载到RAM的代码大小

image_base

4

image的flash地址

dev_id

2

Not used

flash_layout_size_4k

2

flash layout大小(单位: 4K)

magic_pattern

4

image的pattern信息

dec_key

16

Not used

load_dst

4

加载到Flash的代码起始地址

ex_info

24

image的heap和ram信息

git_ver

16

image的版本信息

RSA Public Key

388

用于在开启secure boot时进行认证

flash_sec_cfg

20

flash sec配置信息

image_info

344

OTA Header的image_info为OTA Bank内各image的起始地址和size，其他image的image_info为reserved。

Image Control Header格式

Image Header中image_control_header格式如下：

typedef struct _IMG_CTRL_HEADER_FORMAT
{
    uint16_t crc16;
    uint8_t ic_type;
    uint8_t secure_version;
    union
    {
        uint16_t value;
        struct
        {
            uint16_t xip: 1; // payload is executed on flash
            uint16_t enc: 1; // all the payload is encrypted
            uint16_t load_when_boot: 1; // load image when boot
            uint16_t enc_load: 1; // encrypt load part or not
            uint16_t enc_key_select: 3; // referenced to ENC_KEY_SELECT
            uint16_t not_ready: 1; //for copy image in ota
            uint16_t not_obsolete: 1; //for copy image in ota
            uint16_t integrity_check_en_in_boot: 1; // enable image integrity check in boot flow
            uint16_t compressed_not_ready: 1;
            uint16_t compressed_not_obsolete: 1;
            uint16_t rsvd: 1;
            uint16_t image_type: 3; /*for app 000b: normal image, 001b:compressed image, other for more types
            for patch in temp bank consist of 001b: patch+fsbl, 010b: patch+app, 011b: patch+fsbl+app*/
        };
    } ctrl_flag;
    uint16_t image_id;
    uint32_t payload_len;
} T_IMG_CTRL_HEADER_FORMAT;

  • ic_type表示IC type，RTL87x2G IC type值为15。

  • secure_version表示启动安全检查image的版本。

  • image_id标识不同的image的类型枚举如下，其中SCCD，OCCD不能DFU升级。

typedef enum
{
    IMG_SCCD             = 0x379D,
    IMG_OCCD             = 0x379E,
    IMG_BOOTPATCH        = 0x379F,          /*!< KM4 boot patch */
    IMG_DFU_FIRST        = IMG_BOOTPATCH,
    IMG_OTA              = 0x37A0,          /*!< OTA header */
    IMG_SECUREMCUAPP     = 0x37A2,          /*!< KM4 secure app */
    IMG_SECUREMCUAPPDATA = 0x37A3,          /*!< KM4 secure app data */
    IMG_BT_STACKPATCH    = 0x37A6,          /*!< BT stack patch */
    IMG_BANK_FIRST       = IMG_BT_STACKPATCH,
    IMG_MCUPATCH         = 0x37A7,          /*!< KM4 non-secure rom patch */
    IMG_UPPERSTACK       = 0x37A8,          /*!< KM4 non-secure Upperstack */
    IMG_MCUAPP           = 0x37A9,          /*!< KM4 non-secure app */
    IMG_MCUCFGDATA       = 0x37AA,          /*!< KM4 MCUConfigData */
    IMG_MCUAPPDATA1      = 0x37AE,
    IMG_MCUAPPDATA2      = 0x37AF,
    IMG_MCUAPPDATA3      = 0x37B0,
    IMG_MCUAPPDATA4      = 0x37B1,
    IMG_MCUAPPDATA5      = 0x37B2,
    IMG_MCUAPPDATA6      = 0x37B3,
    IMG_ZIGBEESTACK      = 0x37B4,          /*!< KM4 Zigbee stack */
    IMG_MAX              = 0x37B5,
    IMG_DFU_MAX          = IMG_MAX,

    IMG_RO_DATA1         = 0x3A81,
    IMG_RO_DATA2         = 0x3A82,
    IMG_RO_DATA3         = 0x3A83,
    IMG_RO_DATA4         = 0x3A84,
    IMG_RO_DATA5         = 0x3A85,
    IMG_RO_DATA6         = 0x3A86,

    IMG_USER_DATA8       = 0xFFF7,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA_FIRST  = IMG_USER_DATA8,
    IMG_USER_DATA7       = 0xFFF8,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA6       = 0xFFF9,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA5       = 0xFFFA,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA4       = 0xFFFB,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA3       = 0xFFFC,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA2       = 0xFFFD,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA1       = 0xFFFE,    /*!< the image data only support unsafe single bank ota */
    IMG_USER_DATA_MAX    = 0xFFFF,    /*!< the image data only support unsafe single bank ota */
} IMG_ID;

  • payload_len单位是字节，表示image的大小，不包括1280 Bytes的image header，image total length = payload_len + 1280。

  • crc16表示对image的crc16校验值，image默认使用sha256校验，校验值存在image_hash中，crc16可忽略。

  • ctrl_flag和DFU相关的位域只有 not_ready 和 not_obsolete 。

    • not_ready 标识image是否为有效。默认发布、编译或者通过工具生成的文件的image header中 not_ready 字段均为0。

      • 通过蓝牙传输将image写入到备份区，中间可能存在断电的风险。所以在写入备份区前，需要将 not_ready 修改成1再写入flash。

      • 只有当image传输完成，并且image完整性校验成功后，修改备份区image中的 not_ready 为0，标识备份区image有效。

      • 系统重启后，由BootLoader完成备份image的激活流程。

    • not_obsolete 表示image是否废弃，默认编译的image中 not_obsolete 为1。

      • 当 支持Bank切换 时，not_obsolete 在DFU过程中无效。

      • 当 不支持Bank切换 时，DFU升级完成后，启动代码判断 not_ready 为0且 not_obsolete 为1，此时将image从OTA TMP区搬运到OTA Bank0内的对应image的运行区域，搬运成功后，将OTA TMP区image中 not_obsolete 写为0，防止重复搬运。

Flash布局

Flash布局

RTL87x2G的 Flash布局，由Reserved，OEM Header（即Config File的存储空间），Bank0 Boot Patch，Bank1 Boot Patch，OTA Bank 0，OTA Bank 1，Secure APP，OTA TMP，FTL和APP Defined Section组成。访问flash的起始地址为0x04000000。Flash空间分布和功能说明 如下。

../../../../_images/Flash_Layout.png

Flash布局

Flash空间分布和功能说明

Memory Segment

Starting Address

Size(Bytes)

Functions

是否支持DFU升级

OEM Header

0x04010000

0x1000

配置信息存储区域，包括蓝牙地址和用户可修改的Flash布局等内容。

否

Bank0 Boot Patch

可变

(由Efuse决定)

可变

(由Efuse决定)

Flash boot loader。

Bank0 Boot patch和Bank1 Boot patch作用相同，互为备份区。

是

Bank1 Boot Patch

可变

(由Efuse决定)

可变

(由Efuse决定)

Flash boot loader。

是

OTA Bank0

可变

(OEM Header定义)

可变

(OEM Header定义)

OTA Bank0主要用于存储设备的固件和运行时数据。具体的功能参考 OTA Bank Flash布局。

是

OTA Bank1

可变

(OEM Header定义)

可变

(OEM Header定义)

对于 支持Bank切换 的OTA方案，如果OTA Bank0是运行区，那么OTA Bank1将作为备份区。反之，如果OTA Bank1是运行区，OTA Bank0将作为备份区。

是

Bank0 Secure APP

可变

(OEM Header定义)

可变

(OEM Header定义)

当开启TrustZone时，Secure APP（安全应用程序）可以在TrustZone环境中运行，确保敏感数据和操作得到安全保护。在这种情况下，Bank0 Secure APP和Bank1 Secure APP的作用是相同的，互为备份区。

是

Bank1 Secure APP

可变

(OEM Header定义)

可变

(OEM Header定义)

和Bank0 Secure APP作用相同，互为备份区。

是

OTA TMP

可变

(OEM Header定义)

可变

(OEM Header定义)

使用不切换bank的OTA方式下，作为OTA备份区使用，大小必须不小于OTA Bank0最大的image大小。

是

FTL

可变

(OEM Header定义)

可变

(OEM Header定义)

该区域空间支持以逻辑地址访问flash。

否

APP Defined Section

可变

(OEM Header定义)

可变

(OEM Header定义)

Flash剩余未划分区域，用户可以自由使用，但默认不支持OTA升级。

否

OTA Bank内部的布局和说明如下。

../../../../_images/Layout_of_OTA_Bank.png

OTA Bank布局

OTA Bank Flash Segmentation

Memory Segment

Starting Address

Size(Bytes)

Functions

是否支持DFU升级

OTA Header

由OEM Header定义决定

4KB

存储OTA Header的版本信息，Bank中存在image的起始地址和大小

是（支持Bank切换）

否（不支持Bank切换）

System Patch

由OTA Header定义决定

Variable

对non-secure rom中系统的优化和扩展代码

是

BT Stack Patch

由OTA Header定义决定

Variable

蓝牙controller协议栈优化和扩展代码

是

BT Host

由OTA Header定义决定

Variable

实现HCI及以上蓝牙协议栈部分代码

是

APP

由OTA Header定义决定

Variable

开发方案的运行代码

是

APP Config File

由OTA Header定义决定

Variable

APP Config信息

是

APP Data1

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

APP Data2

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

APP Data3

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

APP Data4

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

APP Data5

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

APP Data6

由OTA Header定义决定

Variable

开发方案中使用的数据区

是

调整Flash布局

Flash布局设置分为两级，其中High Level Flash map是由config文件决定，而OTA Bank map是由OTA Header文件决定。用户可通过MP Tool中 Config Set 选项加载自定义的flash布局文件并生成config文件。

../../../../_images/MPTool_config.png

通过MP Tool生成config文件

为方便用户使用，Realtek提供Flash Map Generate Tool用于生成flash布局文件（flash map.ini 和 flash_map.h ）。flash map.ini 文件可以导入到MP Tool，用于生成config file和OTA header。而 flash_map.h 文件则需要拷贝到APP的工程目录下，编译出正确可运行的APP image。

../../../../_images/FlashMapGenerateTool.png

Flash Map Generate Tool配置Flash Map

但与此同时，必须遵从以下的原则来调整flash布局。

  1. 如果选择 支持bank切换 的OTA方案，保证OTA Bank0的大小等于OTA Bank1的大小，并且将OTA TMP区域的大小设置为0。

  2. 如果选择 不支持Bank切换 的OTA方案，将OTA bank1的大小设置为0，OTA TMP区域的大小不小于OTA Bank0中最大的image的大小。

  3. 为了将所有的code区域都上锁，以防止非预期的flash写入和擦除操作，尽可能地将OTA bank1结束地址相对于flash起始地址的偏移对齐到实际所选用的flash所支持的某个保护级别对应的范围，详细请参考 软件块保护。

  4. 因为存放在OTA bank内的APP Data1、APP Data2、APP Data3、APP Data4、APP Data5或APP Data6区域的数据是有可能落在flash上锁范围内的，所以该区域内一般是存储只读的数据。如需存储要改写的数据应该放在“APP Defined Section”区域。

Flash布局示例

基于 调整Flash布局的规则，本节提供 支持Bank切换方案和 不支持Bank切换方案下的Flash布局示例。

支持Bank切换方案

支持Bank切换方案Flash布局示例

flash总大小为2MB的示例布局

大小(字节)

起始地址

Reserved

4K

0x04000000

OEM Header

4K

0x04001000

Bank0 Boot Patch

32K

0x04002000

Bank1 Boot Patch

32K

0x0400A000

OTA Bank0

596K

0x04012000

  • OTA Header

4K

0x04012000

  • System Patch code

32K

0x04013000

  • BT Stack Patch code

60K

0x0401B000

  • BT Host code

212K

0x0402A000

  • APP code

284K

0x0405F000

  • APP Config File

4K

0x040A6000

  • APP data1

0K

0x040A7000

  • APP data2

0K

0x040A7000

  • APP data3

0K

0x040A7000

  • APP data4

0K

0x040A7000

  • APP data5

0K

0x040A7000

  • APP data6

0K

0x040A7000

OTA Bank1

596K

0x040A7000

  • OTA Header

4K

0x040A7000

  • System Patch code

32K

0x040A8000

  • BT Stack Patch code

60K

0x040B0000

  • BT Host code

212K

0x040BF000

  • APP code

284K

0x040F4000

  • APP Config File

4K

0x0413B000

  • APP data1

0K

0x0413C000

  • APP data2

0K

0x0413C000

  • APP data3

0K

0x0413C000

  • APP data4

0K

0x0413C000

  • APP data5

0K

0x0413C000

  • APP data6

0K

0x0413C000

Bank0 Secure APP code

0K

0x0413C000

Bank0 Secure APP Data

0K

0x0413C000

Bank1 Secure APP code

0K

0x0413C000

Bank1 Secure APP Data

0K

0x0413C000

OTA Temp

32K

0x0413C000

FTL

16K

0x04148000

APP Defined Section

736K

0x040FF000

备注

Flash布局需要根据用户实际image和data的大小进行合理划分。

不支持Bank切换方案

不支持Bank切换flash布局示例

flash总大小为1MB的示例布局

大小(字节)

起始地址

Reserved

4K

0x04000000

OEM Header

4K

0x04001000

Bank0 Boot Patch

32K

0x04002000

Bank1 Boot Patch

32K

0x0400A000

OTA Bank0

612K

0x04012000

  • OTA Header

4K

0x04012000

  • System Patch code

32K

0x04013000

  • BT Stack Patch code

60K

0x0401B000

  • BT Host code

212K

0x0402A000

  • APP code

304K

0x0405F000

  • APP Config File

4K

0x040AC000

  • APP data1

0K

0x040AD000

  • APP data2

0K

0x040AD000

  • APP data3

0K

0x040AD000

  • APP data4

0K

0x040AD000

  • APP data5

0K

0x040AD000

  • APP data6

0K

0x040AD000

OTA Bank1(等于0)

0K

0x040AD000

Bank0 Secure APP code

0K

0x040AD000

Bank0 Secure APP Data

0K

0x040AD000

Bank1 Secure APP code

0K

0x040AD000

Bank1 Secure APP Data

0K

0x040AD000

OTA Temp

312K

0x040AD000

FTL

16K

0x040FB000

APP Defined Section

4K

0x040FF000

备注

此处没有分配APP data，Flash布局需要根据用户实际image和data的大小进行合理划分。