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.

RTL8721Dx:
../../../_images/flash_layout_dplus.svg

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

1960

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:

RTL8721Dx:
../../../_images/flash_mmu_layout_dplus.svg

Note

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

Flash Layout Modification Guide

Adjust Flash layout by configuring partition offsets and sizes through Menuconfig. All partitions except IMG_BOOT can be customized. The IMG_BOOT start address is fixed at 0x0800_0000.

To modify the Flash layout:

  1. Run make menuconfig.

  2. Navigate to User Config > Flash Layout Configuration.

  3. Configure the offset and size for each partition as needed.

  4. Save and exit menuconfig.

  5. Re-build the project.

Note

  • Actual ICs may not include all partition entries. Refer to IC-specific flash layout for available partitions.

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

  • Ensure no overlap between adjacent partitions. An overlap check is performed automatically when exiting menuconfig.

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 the Bootloader OTA2 partition, set BOOT OTA2 Offset and BOOT OTA2 Size in User Config > Flash Layout Configuration of menuconfig. Ensure the offset is 4K-aligned.

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

RTL8721Dx:

APP OTA1

  1. In menuconfig, navigate to User Config > Flash Layout Configuration and set APP OTA1 Offset and APP OTA1 Size.

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

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

    ../../../_images/app_ota1_step3_dplus.png

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. In menuconfig, navigate to User Config > Flash Layout Configuration and set APP OTA2 Offset and APP OTA2 Size.

  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\usrcfg\amebaxxx\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