IC:

Supported Chips

Ameba SoC

RTL8721Dx

RTL8726E

RTL8720E

RTL8730E

Supported

Y

Y

Y

Y

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.

GitHub

RTL8721Dx 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

Cut

Frequency

Core voltage

PLL

300MHz ~ 600MHz

KM0

A-Cut

≤115MHz

KM4

A-Cut

≤260MHz

0.9V

KM4

A-Cut

≤345MHz

1.0V

Note

The maximum operating speed of Flash with Wide Range VCC 1.65V~3.6V should use the speed limit of 1.65V~2.3V power supply.

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. 260MHz under 0.9V
// For KM0, max. 115MHz under 1.0V, max. 104MHz 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
   {PLL_520M,     CORE_VOL_0P9,  CLKDIV(2),       CLKDIV(5),   CLKDIV(2)},
   {PLL_331M,     CORE_VOL_1P0,  CLKDIV(1),       CLKDIV(3),   CLKDIV(1)},
   {PLL_400M,     CORE_VOL_0P9,  CLKDIV(2),       CLKDIV(4),   CLKDIV(1)},
   {PLL_480M,     CORE_VOL_0P9,  CLKDIV(2),       CLKDIV(5),   CLKDIV(2)},  // 48M for USB
   {PLL_677P376M, CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),   CLKDIV(2)},
   {PLL_688P128M, CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),   CLKDIV(2)},
};

/**
* @brief SocClk_Info selection
* Boot_SocClk_Info_Idx is [0, sizeof(SocClk_Info)), Soc will set the SoC clock by SocClk_Info[Boot_SocClk_Info_Idx]
* /

#ifdef CONFIG_USB_DEVICE_EN
u8 Boot_SocClk_Info_Idx = 3; // Make sure the PLL_CLK for USB is an integer multiple of 48MHz
#else
u8 Boot_SocClk_Info_Idx = 0;
#endif

  2. Check the BOOT_ChipInfo_ClkInfoIdx() function in \bootloader\bootloader_km4.c.

    u32 BOOT_ChipInfo_ClkInfoIdx(void)
{
   /* PSRAM die is wb955 which can run up to 200MHz */
   /* Boot_SocClk_Info_Idx is valid, use user config socclk */
   return Boot_SocClk_Info_Idx;
}

    The bootloader will set the SoC clock defined by SocClk_Info[Boot_SocClk_Info_Idx], and PSRAM rate will also be changed with SoC clock.

    PSRAM type

    PSRAM speed

    SocClk_Info[x]

    Clock Info

    No PSRAM

    SocClk_Info[0]

    • PLL: 520MHz

    • KM4: 260MHz

    • KM0: 86.6MHz

    WB955

    ≤200MHz

    SocClk_Info[1]

    • PLL: 330MHz

    • KM4: PLL/1

    • KM0: PLL/4

    • PSRAM: PLL/2

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

    • Modify SocClk_Info[0] in ameba_bootcfg.c.

    • Modify Boot_SocClk_Info_Idx to [0, sizeof(SocClk_Info)], and then define your own clock info in SocClk_Info [Boot_SocClk_Info_Idx].

    Note

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

    Example

    Change KM4_CKD of SocClk_Info[0] to CLKDIV(3) if KM4 is wanted to run at 520MHz/3.

    // For KM4, max. 345MHz under 1.0V, max. 260MHz under 0.9V
// For KM0, max. 115MHz under 1.0V, max. 104MHz 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
   {PLL_520M,     CORE_VOL_0P9,  CLKDIV(2),    CLKDIV(5),   CLKDIV(2)},
   {PLL_331M,     CORE_VOL_1P0,  CLKDIV(1),    CLKDIV(3),   CLKDIV(1)},
   {PLL_400M,     CORE_VOL_0P9,  CLKDIV(2),    CLKDIV(4),   CLKDIV(1)},
   {PLL_480M,     CORE_VOL_0P9,  CLKDIV(2),    CLKDIV(5),   CLKDIV(2)},  // 48M for USB
   {PLL_677P376M, CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),   CLKDIV(2)},
   {PLL_688P128M, CORE_VOL_1P0,  CLKDIV(2),  CLKDIV(6),   CLKDIV(2)},
};

    Based on the example configuration, the clock of KM4 is 173.3MHz, KM0 is 86.6MHz, PSRAM controller is 260MHz (twice the PSRAM), and core power is 0.9V. The clocks of left modules will be set to a reasonable value by software automatically based on their maximum speeds.

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

ameba_flashcfg

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

GitHub

RTL8721Dx ameba_flashcfg.c

Flash_Speed

Flash runs half as fast as the SPI Flash controller. By default, the speed of the SPI Flash controller is divided by the PLL, and the speed of the SPI Flash controller shall be less than SPIC_CLK_LIMIT (208MHz). If the Flash needs to run slower, change the value of Flash_Speed (SPIC0) or Data_Flash_Speed (SPIC1).

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

Value of Flash_Speed

Description

Flash baudrate

CLKDIV(10)

Flash baudrate will be 1/10 of PLL

PLL/20

CLKDIV(9)

Flash baudrate will be 1/9 of PLL

PLL/18

CLKDIV(8)

Flash baudrate will be 1/8 of PLL

PLL/16

CLKDIV(7)

Flash baudrate will be 1/7 of PLL

PLL/14

CLKDIV(6)

Flash baudrate will be 1/6 of PLL

PLL/12

CLKDIV(5)

Flash baudrate will be 1/5 of PLL

PLL/10

CLKDIV(4)

Flash baudrate will be 1/4 of PLL

PLL/8

CLKDIV(3)

Flash baudrate will be 1/3 of PLL

PLL/6

CLKDIV(2)

Flash baudrate will be 1/2 of PLL

PLL/4

Flash_ReadMode

Value of Flash_ReadMode

Description

0xFFFF

Address & Data 4-bit mode

0x7FFF

Just data 4-bit mode

0x3FFF

Address & Data 2-bit mode

0x1FFF

Just data 2-bit mode

0x0FFF

1-bit mode

Note

If the configured read mode is not supported, other modes would be searched until finding out the appropriate mode.

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 .

Flash Pinmap

For more information about pinmap configuration, refer to User Manual (Chapter I/O Control).

ameba_boot_trustzonecfg

TBD

ameba_pinmapcfg

TBD

ameba_sleepcfg

GitHub

RTL8721Dx ameba_sleepcfg.c

Wakeup Mask Setup

For sleep mode, only one CPU is required to wake up to execute the program in some situations. The wakeup mask module is designed to implement this function. By setting a wakeup mask, you can choose to wake up only one CPU core. If KM4 is chosen, KM0 will be waked up first and then KM0 will resume KM4.

Users can set the wakeup attribute in sleep_wevent_config[] in ameba_sleepcfg.c to choose which CPU you want to wake up. The wakeup attribute of each wakeup source can be set to WAKEUP_KM4 or WAKEUP_KM0 or WAKEUP_NULL, respectively indicating that this wakeup source is only to wake up KM4, or wake up KM0, or not used as a wakeup source.

/* Wakeup entry can be set to WAKEUP_NULL/WAKEUP_KM4/WAKEUP_KM0 */
WakeEvent_TypeDef sleep_wevent_config[] = {
   //   Module              Wakeup
   {WAKE_SRC_SDIO,          WAKEUP_NULL},
   {WAKE_SRC_AON_WAKEPIN,      WAKEUP_NULL},
   {WAKE_SRC_AON_TIM,        WAKEUP_NULL},
   {WAKE_SRC_Keyscan,        WAKEUP_NULL},
   {WAKE_SRC_PWR_DOWN,        WAKEUP_NULL},
   {WAKE_SRC_BOR,          WAKEUP_NULL},
   {WAKE_SRC_ADC,          WAKEUP_NULL},
   {WAKE_SRC_RTC,          WAKEUP_NULL},
   {WAKE_SRC_CTOUCH,        WAKEUP_NULL},
   {WAKE_SRC_I2C1,          WAKEUP_NULL},
   {WAKE_SRC_I2C0,          WAKEUP_NULL},
   {WAKE_SRC_GPIOB,        WAKEUP_NULL},
   {WAKE_SRC_GPIOA,        WAKEUP_NULL},
   {WAKE_SRC_UART_LOG,        WAKEUP_NULL},
   {WAKE_SRC_UART2_BT,        WAKEUP_NULL},
   {WAKE_SRC_UART1,        WAKEUP_NULL},
   {WAKE_SRC_UART0,        WAKEUP_NULL},
   {WAKE_SRC_pmc_timer1,      WAKEUP_KM0},  /* Internal use, do not change it*/
   {WAKE_SRC_pmc_timer0,      WAKEUP_KM4},  /* Internal use, do not change it*/
   {WAKE_SRC_Timer7,        WAKEUP_NULL},
   {WAKE_SRC_Timer6,        WAKEUP_NULL},
   {WAKE_SRC_Timer5,        WAKEUP_NULL},
   {WAKE_SRC_Timer4,        WAKEUP_NULL},
   {WAKE_SRC_IPC_KM4,        WAKEUP_KM4},  /* IPC can only wake up KM4, do not change it*/
   {WAKE_SRC_BT_WAKE_HOST,      WAKEUP_NULL},
   {WAKE_SRC_KM4_WAKE_IRQ,      WAKEUP_KM0},  /* Internal use, do not change it*/
   {WAKE_SRC_WIFI_FTSR_MAILBOX,  WAKEUP_KM0},  /* Wi-Fi wakeup, do not change it*/
   {WAKE_SRC_WIFI_FISR_FESR_IRQ,  WAKEUP_KM0},  /* Wi-Fi wakeup, do not change it*/
   {0xFFFFFFFF,          WAKEUP_NULL},
};

AON Wakepin Configuration

AON wakepin is one of the peripherals that can be set as a wakeup source. SoC has two AON wakepins (PB30 and PB31), which can be configured in sleep_wakepin_config[] in ameba_sleepcfg.c. The config attribute can be set to DISABLE_WAKEPIN or HIGH_LEVEL_WAKEUP or LOW_LEVEL_WAKEUP, meaning not wake up, or GPIO level high will wake up, or GPIO level low will wake up respectively.

/* can be used by sleep mode & deep sleep mode */
/* config can be set to DISABLE_WAKEPIN/HIGH_LEVEL_WAKEUP/LOW_LEVEL_WAKEUP */
WAKEPIN_TypeDef sleep_wakepin_config[] = {
   //   wakepin      config
   {WAKEPIN_0,    DISABLE_WAKEPIN},  /* WAKEPIN_0 corresponding to _PB_30 */
   {WAKEPIN_1,    DISABLE_WAKEPIN},  /* WAKEPIN_1 corresponding to _PB_31 */
   {0xFFFFFFFF,  DISABLE_WAKEPIN},
};

Note

  • By default, AON_WAKEPIN_IRQ will not be enabled in sleep_wakepin_config[], and users need to enable it by themselves.

  • The wakeup mask will not be set in sleep_wakepin_config[]. If wakepin is used for sleep mode, WAKE_SRC_AON_WAKEPIN entry needs to be set in sleep_wevent_config[].

Clock and Voltage Configuration

The XTAL, OSC4M state, and sleep mode voltage are configurable in ps_config[] in ameba_sleepcfg.c. Users can use this configuration for peripherals that need XTAL or OSC4M on in sleep mode.

PSCFG_TypeDef ps_config = {
   .keep_OSC4M_on = FALSE,        /* Keep OSC4M on or off for sleep */
   .xtal_mode_in_sleep = XTAL_OFF,    /* Set XTAL mode during sleep mode, see enum xtal_mode_sleep for details */
   .sleep_to_08V = FALSE,        /* Default sleep to 0.7V, setting this option to TRUE will sleep to 0.8V */
};

Sleep mode Configuration

  • Application software can set sleep mode to CG or PG by calling pmu_set_sleep_type(uint32_t type)().

  • Users can get CPU’s sleep mode by calling pmu_get_sleep_type().

Note

  • KM0 and KM4 are in the same power domain, so they will have the same sleep type, thus pmu_set_sleep_type() should be set to KM4, and KM0 will follow KM4’s sleep mode type.

  • Sleep mode is set to PG by default. If users want to change the sleep type, pmu_set_sleep_type() needs to be called before sleep.

ameba_wifi_country_code_table_usrcfg

TBD

ameba_wifi_power_table_usrcfg

TBD

ameba_wificfg

TBD