RAM Layout

Introduction

This chapter describes the default memory layout and provides guidance for customization.

RAM Memory Layout

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

Chipset integrates internal SRAM and expandable PSRAM with the following capacities:

• Internal SRAM: 512KB

• Expandable PSRAM: For capacity, please refer to the datasheet.

RAM & PSRAM Hybrid Layout

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

RAM layout (with PSRAM)

Item	Start address	Size (KB)	Description	Mandatory
SRAM FIXED	0x2000_0000	40	For ROM BSS, MSP, …	√
KM4 Bootloader	0x3000_A000	32	KM4 secure bootloader, including code and data	√
KM4 BD RAM TZ	0x2001_0000	64	KM4 IMG3 BD RAM, can be merged to KM4 BD RAM if not need	x
KM4 BD RAM	0x2002_0000	288	KM4 BDRAM data, BSS and heap	√
KM0 BD RAM	0x2006_8000	96	KM0 BDRAM data, BSS and heap	√
KM4 BD PSRAM TZ	0x6000_0000	64	KM4 IMG3 PSRAM, can be merged to KM4 PSRAM if not need	x
KM4 BD PSRAM	0x6001_0000	3156	KM4 BD PSRAM code and data	√
KM0 BD PSRAM	0x6032_5000	876	KM0 BD PSRAM code and data	√
KM4 HEAP EXT	0x6FFF_FFFF	0	If KM4 heap is not enough, it can be used to extend the heap size	x
KM0 HEAP EXT	0x6FFF_FFFF	0	If KM0 heap is not enough, it can be used to extend the heap size	x

Note

When Trustzone is disabled, the KM4 BD RAM TZ and KM4 BD PSRAM TZ will be configured as Non-secure regions, and will be merged into KM4 BD RAM and KM4 BD PSRAM respectively.

Kconfig Link Option

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

menuconfig provides configuration options for controlling code/data loading locations. Navigate to CONFIG Link Option

IMG1(Bootloader) running on FLASH or SRAM? (FLASH)  --->
[ ] Enable PQC Secure Boot for IMG1 (requires +12KB SRAM)
IMG2(Application) running on FLASH or PSRAM? (FLASH)  --->
IMG2 Data and Heap in SRAM or PSRAM? (SRAM)  --->
[*] PSRAM_ALL_FOR_AP_HEAP

Option descriptions:

• IMG1(Bootloader) running on FLASH or SRAM? :

  • FLASH : Entire bootloader code runs from FLASH.

  • SRAM : Load full bootloader code into SRAM. Typically used for high-security scenarios with sufficient SRAM space.

• Enable PQC Secure Boot for IMG1 (requires +12KB SRAM) :

  • Enable Post-Quantum Cryptography (ML-DSA-65) secure boot verification for IMG1 bootloader. Only available when IMG1 –> SRAM is selected.

  • When enabled, KM4_IMG1_SIZE increases from 32KB to 44KB (+12KB).

  • The additional 12KB is taken from KM4_IMG2_SIZE.

• IMG2(Application) running on FLASH or PSRAM? :

  • FLASH: Execute application code directly from FLASH (NOR FLASH only).

  • PSRAM: Load application code into PSRAM for faster execution or higher security requirements.

• IMG2 Data and Heap in SRAM or PSRAM? :

  • SRAM: Application data and heap are allocated in SRAM.

  • PSRAM: Application data and heap are allocated in PSRAM for scenarios requiring larger heap space.

• PSRAM_ALL_FOR_AP_HEAP :

  • Allocate all PSRAM space to application heap.

  • Only available when IMG2 --> PSRAM and Data & Heap --> PSRAM are not selected.

Note

Verify PSRAM integration (internal/external) before selecting PSRAM-related options.

Bootloader_RAM

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

The ameba_layout.ld contains:

#if defined(CONFIG_IMG1_FLASH)
   #define KM4_IMG1_SIZE               KBYTES(4)
#elif defined(CONFIG_IMG1_PQC_SBOOT)
   #define KM4_IMG1_SIZE               KBYTES(44)
#else
   #define KM4_IMG1_SIZE               KBYTES(32)
#endif

KM4_BOOTLOADER_RAM_S (rwx) : ORIGIN = KM4_IMG1_RAM_START + SECURE_ADDR_OFFSET + IMAGE_HEADER_LEN, LENGTH = KM4_IMG1_SIZE - IMAGE_HEADER_LEN

Configuration in menuconfig affects RAM allocation:

• IMG1 –> FLASH: KM4_BOOTLOADER_RAM_S preset 4KB

• IMG1 –> SRAM: KM4_BOOTLOADER_RAM_S preset 32KB

• IMG1 –> SRAM with Enable PQC Secure Boot for IMG1: KM4_BOOTLOADER_RAM_S preset 44KB (+12KB for Post-Quantum Cryptography secure boot)

Maintain 4KB alignment when modifying (MPC uses 4KB units).

Note

Enabling CONFIG_IMG1_PQC_SBOOT increases bootloader RAM space by 12KB, which is taken from KM4_IMG2_SIZE.

BD_RAM and BD_PSRAM

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

BD_RAM

In ameba_layout.ld:

#define RAM_KM4_IMG3_SIZE           KBYTES(44)
#define RAM_KM0_IMG2_SIZE           KBYTES(96)
#define KM4_IMG2_RAM_START          (KM4_RAM_TZ_SECURE_START + RAM_KM4_IMG3_SIZE)
#define KM0_IMG2_RAM_START          (SRAM_END - RAM_KM0_IMG2_SIZE)

KM4_BD_RAM (rwx) :                  ORIGIN = KM4_IMG2_RAM_START + IMAGE_HEADER_LEN,          LENGTH = KM0_IMG2_RAM_START - KM4_IMG2_RAM_START - IMAGE_HEADER_LEN
KM0_BD_RAM (rwx) :                  ORIGIN = KM0_IMG2_RAM_START + IMAGE_HEADER_LEN,          LENGTH = RAM_KM0_IMG2_SIZE - IMAGE_HEADER_LEN

• Remaining SRAM space (after Fixed RAM and IMG1 allocation) is distributed to KM4_IMG3, KM0_IMG2, and KM4_IMG2. RAM_KM4_IMG3_SIZE defines KM4_IMG3’s SRAM size, RAM_KM0_IMG2_SIZE defines KM0_IMG2’s size. Users can adjust these values.

BD_PSRAM

In ameba_layout.ld:

#define PSRAM_BASE                  (0x60000000)
#define PSRAM_END                   (0x60400000)
#define PSRAM_KM4_IMG3_SIZE         KBYTES(44)
#define PSRAM_KM4_IMG2_SIZE         (KBYTES(3220) - (PSRAM_TZ_NSC_SIZE + PSRAM_TZ_ENTRY_SIZE + PSRAM_KM4_IMG3_SIZE))
#define KM4_IMG2_PSRAM_START        (KM4_PSRAM_TZ_SECURE_START + PSRAM_KM4_IMG3_SIZE)
#define KM0_IMG2_PSRAM_START        (KM4_IMG2_PSRAM_START + PSRAM_KM4_IMG2_SIZE)
#define PSRAM_KM0_IMG2_SIZE         (PSRAM_END - KM0_IMG2_PSRAM_START)

KM4_BD_PSRAM (rwx) :                ORIGIN = KM4_IMG2_PSRAM_START + IMAGE_HEADER_LEN,  LENGTH = PSRAM_KM4_IMG2_SIZE - IMAGE_HEADER_LEN
KM0_BD_PSRAM (rwx) :                ORIGIN = KM0_IMG2_PSRAM_START + IMAGE_HEADER_LEN,  LENGTH = PSRAM_KM0_IMG2_SIZE - IMAGE_HEADER_LEN

• PSRAM space allocation sequence: KM4_IMG3 -> KM4_IMG2 -> KM0_IMG2. Default size 4MB (PSRAM_BASE to PSRAM_END). Adjust PSRAM_END for actual PSRAM size.

• To reallocate space between PSRAM_BASE-PSRAM_END: Modify PSRAM_KM4_IMG3_SIZE for KM4_IMG3, PSRAM_KM4_IMG2_SIZE for KM4_IMG2. Remaining space goes to KM0_IMG2.

• Space after PSRAM_END (if exists) can be used as extended heap xxx_PSRAM_HEAP_EXT (disabled by default).

Heap Memory

Adjusting HEAP Size

1. Adjust BD_RAM/BD_PSRAM regions to modify heap size via remaining space after static loading (see BD_RAM and BD_PSRAM)

2. Define free PSRAM addresses to xxx_PSRAM_HEAP_EXT:

   Default invalid configuration:

   xxx_PSRAM_HEAP_EXT (rwx) :              ORIGIN = 0x6FFFFFFF, LENGTH = 0x6FFFFFFF - 0x6FFFFFFF     /* PSRAM HEAP EXT */
   

   Example configuration (e.g., 0x60400000 ~ 0x60800000):

   xxx_PSRAM_HEAP_EXT (rwx) :              ORIGIN = 0x60400000, LENGTH = 0x60800000 - 0x60400000     /* PSRAM HEAP EXT */
   

Note

• Check __bdram_heap_buffer_size__, __psram_heap_buffer_size__, and __psram_heap_extend_size__ in build_xxx/build/project_xx/image/target_img2.map

• When ALL PSRAM USED FOR APPLICATION HEAP is selected, PSRAM_BDRAM and PSRAM_HEAP_EXT become invalid

API Reference

MALLOC_TYPES

typedef enum {
   TYPE_TCM = 0,
   TYPE_SRAM,
   TYPE_DRAM,
   TYPE_ALL
} MALLOC_TYPES;

Memory types:

TYPE_TCM:

Allocate from TCM/SRAM/DRAM (0x00000000+)

TYPE_SRAM:

Allocate from SRAM/DRAM only (0x20000000+)

TYPE_DRAM:

Allocate from DRAM only (0x60000000+)

TYPE_ALL:

No restrictions (0x00000000+)

malloc

void *rtos_mem_malloc(uint32_t size);

Allocate memory from initialized heap regions (no type restriction).

• Parameters:

  size:

  Memory block size

• Returns: Pointer to allocated memory

void *rtos_heap_types_malloc(uint32_t size, MALLOC_TYPES type);

Allocate memory from initialized heap regions (type-restricted).

• Parameters:

  size:

  Memory block size

  type:

  Memory type

• Returns: Pointer to allocated memory

zmalloc

void *rtos_mem_zmalloc(uint32_t size);

Allocate and zero-initialize memory (no type restriction).

• Parameters:

  size:

  Memory block size

• Returns: Pointer to allocated memory

void *rtos_heap_types_zmalloc(uint32_t size, MALLOC_TYPES type);

Allocate and zero-initialize memory (type-restricted).

• Parameters:

  size:

  Memory block size

  type:

  Memory type

• Returns: Pointer to allocated memory

calloc

void *rtos_mem_calloc(uint32_t elementNum, uint32_t elementSize);

Allocate array with zero-initialization (no type restriction).

• Parameters:

  elementNum:

  Number of elements

  elementSize:

  Element size

• Returns: Pointer to allocated array

void *rtos_heap_types_calloc(uint32_t elementNum, uint32_t elementSize, MALLOC_TYPES type);

Allocate array with zero-initialization (type-restricted).

• Parameters:

  elementNum:

  Number of elements

  elementSize:

  Element size

  type:

  Memory type

• Returns: Pointer to allocated array

realloc

void *rtos_mem_realloc(void *ptr, uint32_t new_size);

Resize memory block (no type restriction). New areas uninitialized.

• Parameters:

  ptr:

  Original memory pointer

  new_size:

  New size

• Returns: New pointer (NULL if failed, original memory remains)

void *rtos_heap_types_realloc(void *ptr, uint32_t new_size, MALLOC_TYPES type);

Resize memory block (type-restricted). New areas uninitialized.

• Parameters:

  ptr:

  Original memory pointer

  new_size:

  New size

  type:

  Memory type

• Returns: New pointer (NULL if failed, original memory remains)

free

void rtos_mem_free(void *pbuf);

void rtos_heap_types_free(void *pbuf);

Release memory block.

• Parameters:

  pbuf:

  Pointer to memory block

• Returns: None