User Configuration

Introduction

This chapter mainly introduces various configuration files that require special attention and modification during the development process.​

ameba_bootcfg

This section introduces the boot-related configurations including SoC clock switch and boot log.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_bootcfg.c

The KM4 boots at 200MHz at the BootRom Stage, and switches to a higher frequency during the bootloader Stage.

There are some limitations when changing the SoC clock:

Clock	Frequency	Core voltage
PLL	300MHz ~ 688.128MHz
KM0	≤105MHz	0.9V
KM0	≤115MHz	1.0V
KM4	≤262MHz	0.9V
KM4	≤345MHz	1.0V

Note

• By default, the SDK assumes the Flash is powered at 3.3V. And during initialization, it will automatically switch the Flash to the highest speed rate that does not exceed the 104MHz limit.

• For wide voltage range ICs, the maximum operating frequency of the Flash should comply with the speed limitations in the 1.65V to 2.3V power supply range. You can refer to ameba_flashcfg to reduce the speed or contact Realtek for assistance.

SoC & PSRAM Clock Set Flow

1. Check the value of Boot_SocClk_Info_Idx and SocClk_Info[] in ameba_bootcfg.c.

   // for km4, max 345MHz under 1.0v, max 262MHz under 0.9v
   // for km0, max 115MHz under 1.0v, max 105MHz under 0.9v
   // PLL can be 300MHz~688.128MHz
   // KM4_CKD range is [1, 8], KM0_CKD range is [1, 16] or USEXTAL
   const SocClk_Info_TypeDef SocClk_Info[] = {
      /* PLL_CLK,     Vol_Type,      KM4_CKD,    KM0_CKD,    PSRAMC_CKD*/
      /* This group is to reduce the impact of PSRAM on RF, the frequency is specially selected */
      {PLL_524M,      CORE_VOL_0P9,  CLKDIV(2),  CLKDIV(5),  CLKDIV(2)},  // For SiP Psram
      {PLL_392M,      CORE_VOL_0P9,  CLKDIV(2),  CLKDIV(4),  CLKDIV(1)},  // For SiP Psram
      {PLL_334M,      CORE_VOL_1P0,  CLKDIV(1),  CLKDIV(3),  CLKDIV(1)},  // For SiP Psram
      /* This group is to reduce the impact of Flash on RF, the frequency is specially selected.
         Single die use the same settings. */
      {PLL_512M,      CORE_VOL_0P9,  CLKDIV(2),  CLKDIV(5),  CLKDIV(2)},  // For SiP Flash or single die (No Psram)
      {PLL_400M,      CORE_VOL_0P9,  CLKDIV(2),  CLKDIV(4),  CLKDIV(1)},  // For SiP Flash or single die (No Psram)
      {PLL_334M,      CORE_VOL_1P0,  CLKDIV(1),  CLKDIV(3),  CLKDIV(1)},  // For SiP Flash or single die (No Psram)
      /* The following frequency settings are not adjustable */
      {PLL_480M,      CORE_VOL_0P9,  CLKDIV(2),  CLKDIV(5),  CLKDIV(2)},  // 48M for usb, both For SiP Psram / SiP Flash / single die
      {PLL_677P376M,  CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),  CLKDIV(2)},  // Audio
      {PLL_688P128M,  CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),  CLKDIV(2)},  // Audio
   };
   
   /**
   * @brif  SocClk_Info select. One of Valid_Boot_Idx_for_SiP_Psram or Valid_Boot_Idx_for_No_Psram depend on different chip types
   * Boot_SocClk_Info_Idx is [0, sizeof(SocClk_Info)), Soc will set socclk by SocClk_Info[Boot_SocClk_Info_Idx]
   */
   #ifdef CONFIG_USB_DEVICE_EN
   u8 Boot_SocClk_Info_Idx = 6; /* Make sure the PLL_CLK for USB is an integer multiple of 48MHz */
   #else
   u8 Boot_SocClk_Info_Idx = 6; /* 480M has an acceptable impact on the RF performance of SiP Psram and SiP Flash */
   #endif
   

2. Due to certain frequencies of PSRAM or Flash interfering with RF, the BOOT_ChipInfo_ClkInfoIdx() function in the bootloaderbootloader_km4.c file only allows indices represented by Boot_SocClk_Info_Idx within the SocClk_Info array.”

   Note

   It is not recommended to modify SocClk_Info. If frequency combinations outside of SocClk_Info are needed, it is necessary to confirm whether such configurations would affect RF performance.

   u32 BOOT_ChipInfo_ClkInfoIdx(void)
   {
      /* PSRAM die is wb955 which can run up to 200MHz */
      ...
      return Boot_SocClk_Info_Idx;
   }
   

   The Bootloader will configure the SoC voltage and clock according to the definition of SocClk_Info[Boot_SocClk_Info_Idx]. The PSRAMC (twice the PSRAM clock) rate will also be adjusted synchronously with the SoC clock. The clock speeds for other modules will be automatically set to reasonable values by the software based on their maximum operating speeds. The cases where the value of Boot_SocClk_Info_Idx is 0 and 4 serve as examples:

   PSRAM type	PSRAM speed	SocClk_Info[x]	Clock Info
   No PSRAM		SocClk_Info[4]	PLL: 400MHz KM4: PLL/2 KM0: PLL/4
   With PSRAM	≤200MHz	SocClk_Info[0]	PLL: 524MHz KM4: PLL/2 KM0: PLL/5 PSRAMC: PLL/2

3. Refer to one of the following methods to change the SoC clock if needed.

   • Modify Boot_SocClk_Info_Idx to a value within the range of [0, sizeof(SocClk_Info)], then customize the clock configuration information in SocClk_Info [Boot_SocClk_Info_Idx].

   Note

   Consider the limitations of the hardware and do not set the clock info illogically.

4. Rebuild the project and download the new image again.

Boot_Agg_En

The Boot_Agg_En is used with Trace Tool to sort out boot logs from different cores. It can be enabled through Boot_Agg_En.

/**
* @brif  Loguart AGG enable or disable
*    FALSE: disable
*    TRUE: enable
*/
u8 Boot_Agg_En = FALSE;

Note

Refer to Chapter Trace Tool for more information.

ameba_flashcfg

This section introduces the Flash-related configurations including speed, read mode, layout and protect mode.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_flashcfg.c

Flash_Speed

The frequency of the SPIC controller is set to XTAL (40MHz) during the BootRom stage, and switches to a higher frequency during the Bootloader stage. The Flash runs at half the speed of the SPIC controller. By default, the SPIC controller’s speed is derived from the PLL divider, but it must remain below SPIC_CLK_LIMIT (208MHz).

If the Flash needs to run slower, modify the value of Flash_Speed (for SPIC0) or Data_Flash_Speed (for SPIC1), which is the PLL division factor.

const u16 Flash_Speed = CLKDIV(2);
const u16 Data_Flash_Speed = CLKDIV(2);

Note

• Refer to ameba_bootcfg for details about the Frequency of PLL.

• The maximum clock of Flash is SPIC_CLK_LIMIT/2. The initial flow will automatically check whether the configured speed is higher than the maximun one or not.

• Flash has already been set to optimal performance during initialization, so it is not recommended to modify Flash_Speed and Flash_ReadMode, or Data_Flash_Speed and Data_Flash_ReadMode.

Flash_ReadMode

During the BootRom stage, the SPIC operates in 1IO mode, and switches to the mode specified by Flash_ReadMode (default is 4IO) during the Bootloader stage. If the currently configured read mode is not supported, the system will automatically try other modes until a compatible mode is found.

Flash_Layout

The default Flash layout in the SDK are illustrated in Chapter Flash Layout . If you want to modify the Flash layout, refer to Section Flash Layout Modification Guide.

Flash Protect Enable

For more information about this function, refer to Section Flash Protection Mechanism .

ameba_boot_trustzonecfg

This section introduces TrustZone-related configurations, focusing primarily on the configuration of the MPC and SAU in chips that support Secure features. If the chip does not support the Secure feature, this configuration profile will be ignored.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_boot_trustzonecfg.c

sau_config

Users can configure the security attributes of KM4 by modifying the values in sau_config. Within the specified interval [Start, End], users can set NSC to 0 or 1 to designate whether the area is non-secure.

• If NSC is set to 1, the area will be treated as secure code, i.e., Non-secure Callable (NSC);

• If NSC is set to 0, the area will be treated as non-secure code, and Non-secure KM4 will be able to access this area.

• Areas that are not set will be treated as secure code, accessible by Secure KM4.

mpc1_config

Users can configure the security attributes of certain SRAM intervals by modifying the values in mpc1_config:

• Within the specified interval [Start, End], Non-secure Master can access this area;

• Areas that are not set can only be accessed by Secure Master.

mpc2_config

Users can configure the security attributes of certain PSRAM intervals by modifying the values in mpc2_config:

• Within the specified interval [Start, End], Non-secure Master can access this area;

• Areas that are not set can only be accessed by Secure Master.

Note

• If the chip supports the TrustZone Secure Image Protection(RDP) feature, this file will be compiled and linked into the Bootloader; Otherwise, this file will be ignored.

• You can refer to TrustZone Layout to modify ameba_boot_trustzonecfg.c.

ameba_intfcfg

This section introduces peripheral pin assignment, which refers to mapping the physical pins of the chip to various peripheral functions.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_intfcfg.c

sdio_config

Users can select different pin group of the SDIO device by modifying SDIO_Pin_Grp.

/* sdio pinmux group: 0x0-0x4 */
/* Please refer to SDIO_PAD for more details. */
u8 SDIO_Pin_Grp = 0x2;

SDIO_PAD array is provided by Realtek, which contains multiple pin groups supporting high-speed communication.

/* Please do not modify this table!!! */
const u8 SDIO_PAD[5][6] = {
   /* CLK     CMD     D3      D2      D1      D0 */
   {_PA_16, _PA_15, _PA_14, _PA_13, _PA_18, _PA_17}, // Group0: PA13-PA18
   {_PA_29, _PA_28, _PA_27, _PA_26, _PA_31, _PA_30}, // Group1: PA26-PA31
   {_PB_9,  _PB_8,  _PB_7,  _PB_6,  _PB_14, _PB_13}, // Group2: PB6-PB9, PB13-PB14, default
   {_PB_19, _PB_18, _PB_17, _PA_12, _PB_21, _PB_20}, // Group3: PA12, PB17-PB21
   {_PB_26, _PB_25, _PB_24, _PB_23, _PB_28, _PB_27}  // Group4: PB23-PB28
};

Note

To ensure the high-speed transmission performance of SDIO, please do not modify the SDIO_PAD array.

ameba_pinmapcfg

This section introduces the pull-up and pull-down status of each pin configged by pinmap_init() during the initialization phase.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_pinmapcfg.c

pmap_func

The pmap_func array is mainly used to configure the pull-up and pull-down status of each pin:

• The Func PU/PD controls the default pull-up and pull-down states of pins when the SOC is Active. In main() or subsequent tasks, the pull-up and pull-down states of pins need to be set according to the specific IP requirements when the SOC is Active.

• The Slp PU/PD controls the pull-up and pull-down states when the SOC is in Sleep mode. If not set correctly, leakage current may occur on that pin during sleep, Please modify according to the hardware status.

const PMAP_TypeDef pmap_func[] = {
   // Pin Name    Func PU/PD           Slp PU/PD
   {_PA_0,        GPIO_PuPd_UP,        GPIO_PuPd_UP},
   {_PA_1,        GPIO_PuPd_UP,        GPIO_PuPd_UP},
   {_PA_2,        GPIO_PuPd_KEEP,      GPIO_PuPd_UP},
   ...
};

ameba_sleepcfg

Please reference Power-Saving User Config chapter for detail information.

ameba_wificfg

Please reference Wi-Fi User Configuration chapter for detailed Wi-Fi configuration information.