IC: RTL8721Dx RTL8720E RTL8726E RTL8713E RTL8730E RTL8721F

RAM Layout Configuration Guide

Introduction

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

RAM Memory Layout

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

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

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

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_2000	64	KM4 IMG3 BD RAM, can be merged to KM4 BD RAM if not need	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 to KM4 PSRAM if not need	x
KM4 BD PSRAM	0x6001_0000	3220	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

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

IMG1(Bootloader) running on FLASH or SRAM? (FLASH)  --->
IMG2(Application) running on FLASH, SRAM, or PSRAM? (FLASH)  --->
IMG2 Data and Heap in SRAM or PSRAM? (SRAM)  --->
IMG3(SecureImage) running on PSRAM or SRAM? (PSRAM)  --->
[*] ALL PSRAM USED FOR APPLICATION 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.

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

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

  • SRAM: Load application code into SRAM for specific scenarios.

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

• IMG2 Data and Heap in SRAM or PSRAM? :

  • SRAM: Application data in SRAM, both SRAM and PSRAM remaining space are used for heap.

  • PSRAM: Application data in PSRAM, only PSRAM remaining space used for heap (SRAM typically reserved for DSP).

• IMG3(SecureImage) running on PSRAM or SRAM? :

  • SRAM: TrustZone code runs from SRAM (higher security, more SRAM consumption).

  • PSRAM: TrustZone code runs from PSRAM.

• ALL PSRAM USED FOR APPLICATION HEAP: When PSRAM isn’t used for code/data, allocate all PSRAM space to application heap.

Note

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

Bootloader_RAM

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

The ameba_layout.ld contains:

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

KM4_BOOTLOADER_RAM_S (rwx) : ORIGIN = KM4_IMG1_RAM_SATRT + 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

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

BD_RAM and BD_PSRAM

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

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 xxx_gcc_project/project_xx/xsdk/image/target_img2.map

• When ALL PSRAM USED FOR APPLICATION HEAP is selected, PSARM_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