IC: RTL8721Dx RTL8720E RTL8726E RTL8730E

Flash Layout

Introduction

This chapter describes the default Flash memory layout and customization methods.

The SDK adopts the default Flash layout shown below (using an 8MB Flash chip as an example). The boot manifest start address is fixed at 0x0800_0000, while other regions support flexible address configuration.

RTL8721DxRTL8726ERTL8720E

Item	Physical address	Size (KB)	Description	Mandatory
KM4 Bootloader manifest	0x0800_0000	4	KM4 bootloader manifest	√
KM4 Bootloader	0x0800_1000	76	KM4 bootloader (code/data), containing KM4 bootloader IMG, mapped to the virtual address 0x0F80_0000.	√
Key Certificate	0x0801_4000	4	Public key hash information for other images.	√
IMG2 manifest	0x0801_5000	4	KM0 & KM4 Application & KM4 IMG3 manifest	√
KM0 & KM4 Application	0x0801_6000	1912	Combines KM0 image, KM4 image2 and KM4 image3 (if exists) KM0_IMG: KM0 image (code/data), mapped to the virtual address 0x0C00_0000. KM4_IMG2: KM4 non-secure image (code/data), mapped to the virtual address 0x0E00_0000. KM4_IMG3[1]: secure image (code/data)	√
KM4 Bootloader manifest OTA2	0x0820_0000	4	KM4 bootloader manifest	√
KM4 Bootloader OTA2	0x0820_1000	76	KM4 bootloader (code/data), containing KM4 bootloader IMG, mapped to the virtual address 0x0F80_0000.	√
Key Certificate OTA2	0x0821_4000	4	Public key hash information for other images.	√
IMG2 manifest OTA2	0x0821_5000	4	KM0 & KM4 Application & KM4 IMG3 manifest	√
KM0 & KM4 Application OTA2	0x0821_6000	1912	Combines KM0 image, KM4 image2 and KM4 image3 (if exists) KM0_IMG: KM0 image (code/data), mapped to the virtual address 0x0C00_0000. KM4_IMG2: KM4 non-secure image (code/data), mapped to the virtual address 0x0E00_0000. KM4_IMG3[1]: secure image (code/data)	√
FTL	0x0870_0000	12	For Bluetooth	×
VFS	0x0870_3000	128	For file system	×

Memory Management Unit (MMU)

To enable image flexibility and RSIP encryption requirements (fixed IV address needed for image encryption, see RSIP documentation), the SDK enables Flash MMU by default. The default MMU layout is:

RTL8721DxRTL8726ERTL8720E

Flash Layout Modification Guide

Modifiable flash regions include:

Partition Name	Description
Bootloader OTA2 Partition	IMG_BOOT_OTA2
Application Partitions	APP OTA1: IMG_APP_OTA1 APP OTA2: IMG_APP_OTA2
DSP Firmware Partition	IMG_DSP (if present)
FTL/VFS Partition	FTL/VFS1

Modify corresponding entries in {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c:

FlashLayoutInfo_TypeDef Flash_Layout[] = {
   /*Region_Type,   [StartAddr,   EndAddr]      */
   {IMG_BOOT,      0x08000000, 0x08013FFF}, //Boot Manifest(4K) + KM4 Bootloader(76K)
   //Users should modify below according to their own memory
   {IMG_APP_OTA1,  0x08014000, 0x081F3FFF}, //Certificate(4K) + Manifest(4K) + KR4 & KM4 Application OTA1 + Manifest(4K) + RDP IMG OTA1

   {IMG_BOOT_OTA2, 0x08200000, 0x08213FFF}, //Boot Manifest(4K) + KM4 Bootloader(76K) OTA
   {IMG_APP_OTA2,  0x08214000, 0x083DCFFF}, //Certificate(4K) + Manifest(4K) + KR4 & KM4 Application OTA2 + Manifest(4K) + RDP IMG OTA2
   {FTL,           0x083DD000, 0x083DFFFF}, //FTL for BT(>=12K), The start offset of flash pages allocated to FTL physical map
   {VFS1,          0x083E0000, 0x083FFFFF}, //VFS region 1 (128K)
   {IMG_DSP,       0x08400000, 0x086FFFFF}, //Manifest(4K) + DSP firmware, only one DSP region in layout
   {VFS2,          0xFFFFFFFF, 0xFFFFFFFF}, //VFS region 2
   {USER,          0xFFFFFFFF, 0xFFFFFFFF}, //reserve for user

   /* End */
   {0xFF,          0xFFFFFFFF, 0xFFFFFFFF},
};

Note

This code is an example. Actual IC implementations may not include all configuration lines. Refer to the IC-specific Flash_Layout for details.

Modifying Bootloader OTA2

The OTA2 partition requires 4KB alignment (disabled by default). To enable:

1. Right-shift OTA2 start address by 12 bits and program into OTP 0x36C~0x36D

2. Modify IMG_BOOT_OTA2 address in {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c

3. After OTA programming, Boot ROM selects OTA1/OTA2 based on version numbers

Note

• If the anti-rollback function is enabled to ensure that the bootloader version can only be incremented and cannot be rolled back, the bootloader version needs to be changed before compilation.

• The IMG_VER_xxxxx field in the {SDK}amebaxxx_gcc_projectmanifest.json file needs to be modified if you want to use it.

"MANIFEST_VER": 1,

"boot":
{
   "IMG_ID": "0",
   "IMG_VER_MAJOR": 1,
   "IMG_VER_MINOR": 1,

   "SEC_EPOCH": 1,

   "HASH_ALG": "sha256",

   "RSIP_IV": "0102030405060708",
},

Note

The bootloader OTA1 is permanently located at 0x0800_0000 and cannot be altered.

Modifying Application Partitions

RTL8721DxRTL8720ERTL8726E

APP OTA1

1. Modify the address of IMG_APP_OTA1 in {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c.

2. Re-build the project to generate the bootloader and APP OTA1.

3. Modify the address of km0_km4_app.bin through ImageTool, and download the new bootloader and APP OTA1.

   

After that, the bootloader will load the image from the new location of APP OTA1 if the version of APP OTA1 is bigger.

APP OTA2

1. Modify the address of IMG_APP_OTA2 in {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c.

2. Re-build and download the new bootloader and APP OTA2 as described in Section APP OTA1.

After burning the APP OTA2 into Flash through OTA, bootloader will load the image from the new location of APP OTA2 if the version of APP OTA2 is bigger.

Flash Protection Mechanism

Before loading APP images, the bootloader checks the Flash status register:

• If bitwise AND result with status_mask in Flash_AVL (path: {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c) sets only QE bit, retain current status

• Otherwise write the result to the status register

/**
* @brif Flash_AVL maintains the flash IC supported by SDK.
*     If users want to adpot new flash, add item in the following AVL.
*     Note that, if new flash can be classfied as one of the Realtek-defined categories according to Classification SPEC,
*     filling in the defined class index is necessary. Otherwise, FlashClassUser can be used to indicate new class.
*     If (Status Register of flash & status_mask in Flash_AVL) != (1 << QE Bit), set (1 << QE Bit) to Status Register of flash
*/
const FlashInfo_TypeDef Flash_AVL[] = {
   /*flash_id,                flash_id_mask,  flash_class,            status_mask,    FlashInitHandler */

   /* case1: Realtek defined class, any modification is not allowed */
   {0xEF,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* Winbond: MANUFACTURER_ID_WINBOND */
   {0xA1,                     0x000000FF,             FlashClass1,            0x0000FFFC,             NULL},  /* Fudan Micro: MANUFACTURER_ID_FM */
   {0x0B,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* XTX */
   {0x0E,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* XTX(FT) */
   {0xC8,                     0x000000FF,             FlashClass2,            0x000043FC,             NULL},  /* GD normal: MANUFACTURER_ID_GD */
   {0x28C2,           0x0000FFFF,             FlashClass6,            0x000200FC,             NULL},  /* MXIC wide-range VCC: MANUFACTURER_ID_MXIC */
   {0xC2,                     0x000000FF,             FlashClass3,            0x000000FC,             NULL},  /* MXIC normal: MANUFACTURER_ID_BOHONG */
   {0x68,                     0x000000FF,             FlashClass3,            0x000000FC,             NULL},  /* Hua Hong */
   {0x51,                     0x000000FF,             FlashClass3,            0x000000FC,             NULL},  /* GD MD serial */
   {0x1C,                     0x000000FF,             FlashClass4,            0x000000FC,             NULL},  /* ESMT: MANUFACTURER_ID_EON */
   {0x20,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* XMC: MANUFACTURER_ID_WINBOND */
   {0x85,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* Puya: 85-20-16 */
   {0x5E,                     0x000000FF,             FlashClass1,            0x000043FC,             NULL},  /* Zbit: 5E-50-16 */
   //{0x20,                   0x000000FF,             FlashClass5,            0x000000FC,             NULL},  /* Micron: MANUFACTURER_ID_MICRON */

   /* case2: new flash, ID is not included in case1 list, but specification is compatible with FlashClass1~FlashClass6 */
   //{0xXX,                   0x0000XXXX,             FlashClassX,            0x0000XXXX,             NULL},

   /* case3: new flash, ID is not included in case1 list, and specification is not compatible with FlashClass1~FlashClass6 */
   {0x00,                     0x000000FF,             FlashClassUser,         0xFFFFFFFF,             &flash_init_userdef},

   /* End */
   {0xFF,                     0xFFFFFFFF,             FlashClassNone,         0xFFFFFFFF,             NULL},
};

Note

• Default QE setting disables all block protection. To preserve protection, clear corresponding bits in status_mask (e.g., set Winbond’s mask to 0x000043C0)

• When using LittleFS, recommend placing FTL partition in the last 64KB region with block protection

• Disable protection during OTA updates and re-enable afterward

• For Flashes that cannot protect only the last block, enable protection for the first half region