IC: RTL8721Dx RTL8720E RTL8726E RTL8713E RTL8730E RTL8721F

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.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Item	Physical address	Size (KB)	Description
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: 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	1820	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: secure image (code/data)
FTL	0x083D_D000	12	For Bluetooth
VFS	0x083E_0000	128	For file system

Memory Management Unit (MMU)

To achieve firmware flexibility and meet RSIP encryption requirements (firmware encryption requires fixed IV address, see RSIP), the SDK enables Flash MMU mechanism by default. Through MMU, the same logical address can be mapped to either OTA1 physical region or OTA2 physical region, enabling devices to select firmware from different partitions. When OTA updates are not enabled, firmware is programmed to OTA1 region by default. For more information about OTA, refer to OTA.

Default MMU layout:

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Note

Generally, Flash logical addresses should not be modified. Contact Realtek for customization needs.

Flash Layout Modification Guide

Modify physical-to-logical address mapping to adjust Flash layout. All entries except IMG_BOOT can be modified 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

• Example configuration shown; actual ICs may not include all entries. Refer to IC-specific Flash_Layout.

• When modifying VFS/FTL partitions, use ImageTool to erase related regions to prevent data conflicts.

• Ensure no overlap between adjacent entries.

Modifying Bootloader OTA2

Both BOOT and APP firmware have two partitions (OTA1/OTA2) for redundancy and version control. BOOT OTA is disabled by default - enable it via BOOT OTA.

To modify Bootloader OTA2 partition, adjust IMG_BOOT_OTA2 addresses in {SDK}\component\soc\amebaxxx\usrcfg\ameba_flashcfg.c with 4K alignment.

Note

• Bootloader OTA1 address is fixed at 0x0800_0000 and cannot be modified.

• ROM bootloader selects partitions based on version numbers in firmware headers. Higher version gets priority. See Image Pattern and Version Number.

Modifying Application Partitions

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

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)

• Recommended to enable block protection for code segments and read-only data.

• 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