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:

Item	Start address	Size (KB)	Description	Mandatory
SRAM FIXED	0x2000_0000	40	For ROM BSS, MSP, etc.	√
KM4 Bootloader	0x3000_A000	32	KM4 secure bootloader, including code and data	√
KM4 BD RAM TZ	0x2001_2000	64	KM4 IMG3 BD RAM, can be merged into KM4 BD RAM if not required	x
KM4 BD RAM	0x2002_2000	280	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 into KM4 PSRAM if not required, size specified by CONFIG_TZ_S_SIZE	x
KM0 BD PSRAM	0x6001_0000	876	KM0 BD PSRAM code and data, size specified by CONFIG_PSRAM_KM0_IMG2_KB	√
KM4 BD PSRAM	0x600E_B000	7252	KM4 BD PSRAM code and data, occupying all remaining PSRAM space	√

Note

• If TrustZone is not enabled, KM4 BD RAM TZ and KM4 BD PSRAM TZ will be configured as Non-secure regions and merged into KM4 BD RAM and KM4 BD PSRAM respectively.

• The size of KM4TZ Bootloader is configuration-dependent; refer to Bootloader_RAM for details.

• The PSRAM layout is partitioned according to the maximum PSRAM capacity supported by the chip (8MB for RTL8721Dx). The sizes of KM4 BD PSRAM TZ and KM0 BD PSRAM are specified by their respective Kconfig options; KM4 BD PSRAM occupies all the remaining PSRAM space. The sizes listed in the table are default values only, and users may modify the above Kconfig options as needed.

• At runtime, the system detects the actual PSRAM capacity based on the IC BD number and initializes the heap according to that actual capacity.

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:

#if defined(CONFIG_IMG3_SRAM)
#define KM4_RAM_TZ_SIZE             KBYTES(CONFIG_TZ_S_SIZE)
#else
#define KM4_RAM_TZ_SIZE             KBYTES(0)
#endif
#define RAM_KM0_IMG2_SIZE           KBYTES(96)
#define KM4_IMG2_RAM_START          (KM4_RAM_TZ_START + KM4_RAM_TZ_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. KM4_RAM_TZ_SIZE (controlled by CONFIG_TZ_S_SIZE) defines the TZ region’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)
#if defined(CONFIG_IMG3_PSRAM)
#define KM4_PSRAM_TZ_SIZE           KBYTES(CONFIG_TZ_S_SIZE)
#else
#define KM4_PSRAM_TZ_SIZE           KBYTES(0)
#endif
#define PSRAM_KM4_IMG2_SIZE         (KBYTES(3220) - KM4_PSRAM_TZ_SIZE)
#define KM4_IMG2_PSRAM_START        (KM4_PSRAM_TZ_START + KM4_PSRAM_TZ_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 KM4_PSRAM_TZ_SIZE (controlled by CONFIG_TZ_S_SIZE) for the TZ region (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