Merge branch 'feature/mailbox' into 'master'

feat(mailbox): define and implement a mailbox API for the ESP32-P4

See merge request espressif/esp-idf!39925

Author: o-marshmallow

components/esp_hw_support/CMakeLists.txt

@@ -57,6 +57,9 @@ if(NOT non_os_build)
     if(CONFIG_SOC_MODEM_SUPPORT_ETM)
         list(APPEND srcs "modem/modem_etm.c")
     endif()
+    if(CONFIG_SOC_PMU_SUPPORTED)
+        list(APPEND srcs "pmu_share_hw.c")
+    endif()
     if(CONFIG_SOC_LIGHT_SLEEP_SUPPORTED)
         list(APPEND srcs "sleep_modem.c"
                          "sleep_modes.c"

components/esp_hw_support/include/esp_private/pmu_share_hw.h

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Acquire PMU lock
+ *
+ * @note If any of the locks are taken, this API will wait until the lock is successfully acquired.
+ */
+void pmu_lock_acquire(void);
+
+/**
+ * @brief Release PMU lock
+ */
+void pmu_lock_release(void);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_hw_support/pmu_share_hw.c

@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * PMU is currently only used by the software mailbox, but it could be used by multiple components
+ */
+
+#include <esp_types.h>
+#include "sdkconfig.h"
+#include "esp_private/critical_section.h"
+#include "esp_private/pmu_share_hw.h"
+
+
+DEFINE_CRIT_SECTION_LOCK_STATIC(s_pmu_lock);
+
+void pmu_lock_acquire(void)
+{
+    esp_os_enter_critical(&s_pmu_lock);
+}
+
+
+void pmu_lock_release(void)
+{
+    esp_os_exit_critical(&s_pmu_lock);
+}

components/hal/esp32c5/include/hal/pmu_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -522,6 +522,11 @@ FORCE_INLINE_ATTR void pmu_ll_hp_clear_reject_intr_status(pmu_dev_t *hw)
     hw->hp_ext.int_clr.reject = 1;
 }
 
+FORCE_INLINE_ATTR void pmu_ll_hp_enable_sw_intr(pmu_dev_t *hw, bool enable)
+{
+    hw->hp_ext.int_ena.sw = enable;
+}
+
 FORCE_INLINE_ATTR uint32_t pmu_ll_hp_get_wakeup_cause(pmu_dev_t *hw)
 {
     return hw->wakeup.status0;
@@ -703,6 +708,16 @@ FORCE_INLINE_ATTR void pmu_ll_lp_clear_intsts_mask(pmu_dev_t *hw, uint32_t mask)
     hw->lp_ext.int_clr.val = mask;
 }
 
+FORCE_INLINE_ATTR void pmu_ll_lp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.lp_trigger_hp = 1;
+}
+
+FORCE_INLINE_ATTR void pmu_ll_hp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.hp_trigger_lp = 1;
+}
+
 FORCE_INLINE_ATTR void pmu_ll_lp_clear_sw_intr_status(pmu_dev_t *hw)
 {
     hw->lp_ext.int_clr.sw_trigger = 1;

components/hal/esp32c6/include/hal/pmu_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -522,6 +522,11 @@ FORCE_INLINE_ATTR void pmu_ll_hp_clear_reject_intr_status(pmu_dev_t *hw)
     hw->hp_ext.int_clr.reject = 1;
 }
 
+FORCE_INLINE_ATTR void pmu_ll_hp_enable_sw_intr(pmu_dev_t *hw, bool enable)
+{
+    hw->hp_ext.int_ena.sw = enable;
+}
+
 FORCE_INLINE_ATTR uint32_t pmu_ll_hp_get_wakeup_cause(pmu_dev_t *hw)
 {
     return hw->wakeup.status0;
@@ -542,6 +547,16 @@ FORCE_INLINE_ATTR void pmu_ll_lp_clear_intsts_mask(pmu_dev_t *hw, uint32_t mask)
     hw->lp_ext.int_clr.val = mask;
 }
 
+FORCE_INLINE_ATTR void pmu_ll_lp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.lp_trigger_hp = 1;
+}
+
+FORCE_INLINE_ATTR void pmu_ll_hp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.hp_trigger_lp = 1;
+}
+
 FORCE_INLINE_ATTR void pmu_ll_lp_clear_sw_intr_status(pmu_dev_t *hw)
 {
     hw->lp_ext.int_clr.sw_trigger = 1;

components/hal/esp32p4/include/hal/lp_mailbox_ll.h

@@ -0,0 +1,188 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// The LL layer for ESP32-P4 LP Mailbox register operations
+
+#pragma once
+
+#include <stdlib.h>
+#include <stdbool.h>
+#include "soc/soc.h"
+#include "soc/lp_mailbox_struct.h"
+#include "soc/lp_mailbox_reg.h"
+#include "hal/misc.h"
+#include "esp_attr.h"
+
+#define LP_MAILBOX_LL_MSG_COUNT     16U
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/**
+ * @brief Get a message (32-bit value) from the LP mailbox.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param index Index of the message to retrieve (must be less than LP_MAILBOX_LL_MSG_COUNT).
+ *
+ * @return The 32-bit message value at the specified index, or 0 if the index is out of range.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_get_message(lp_mb_dev_t *dev, int index)
+{
+    if (index < LP_MAILBOX_LL_MSG_COUNT) {
+        return (&dev->message_0.val)[index];
+    }
+    return 0;
+}
+
+/**
+ * @brief Set a message in the LP mailbox.
+ *
+ * @note Writing a message in the mailbox will set the corresponding message's intr_raw bit for
+ * both the LP and HP registers, regardless of the writer!
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param index Index of the message to set (must be less than LP_MAILBOX_LL_MSG_COUNT).
+ * @param val Message (32-bit value) to write to the specified message index.
+ */
+FORCE_INLINE_ATTR void lp_mailbox_ll_set_message(lp_mb_dev_t *dev, int index, uint32_t val)
+{
+    if (index < LP_MAILBOX_LL_MSG_COUNT) {
+        (&dev->message_0.val)[index] = val;
+    }
+}
+
+/**
+ * @brief Get the raw status of the LP core interrupt register.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ *
+ * @return Raw interrupt status value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_get_lp_intr_raw(lp_mb_dev_t *dev)
+{
+    return dev->lp_int_raw.val;
+}
+
+/**
+ * @brief Clear LP core interrupt register bits.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to clear, bit `i` represents message `i`.
+ */
+FORCE_INLINE_ATTR void lp_mailbox_ll_lp_intr_clear(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->lp_int_clr.val = mask;
+}
+
+/**
+ * @brief Get the LP core interrupt register status.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ *
+ * @return Interrupt status value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_lp_intr_status(lp_mb_dev_t *dev)
+{
+    return dev->lp_int_st.val;
+}
+
+/**
+ * @brief Enable mailbox interrupts by mask for the LP core.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to enable, bit `i` represents message `i`.
+ *
+ * @return Updated interrupt enable register value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_lp_intr_enable_mask(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->lp_int_ena.val |= mask;
+    return dev->lp_int_ena.val;
+}
+
+/**
+ * @brief Disable LP core mailbox interrupts by mask.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to disable, bit `i` represents message `i`.
+ *
+ * @return Updated interrupt enable register value.
+ */
+
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_lp_intr_disable_mask(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->lp_int_ena.val &= ~mask;
+    return dev->lp_int_ena.val;
+}
+
+/**
+ * @brief Get the raw status of the HP core interrupt register.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ *
+ * @return Raw interrupt status value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_get_hp_intr_raw(lp_mb_dev_t *dev)
+{
+    return dev->hp_int_raw.val;
+}
+
+/**
+ * @brief Clear HP core interrupt register bits.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to clear, bit `i` represents message `i`.
+ */
+FORCE_INLINE_ATTR void lp_mailbox_ll_hp_intr_clear(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->hp_int_clr.val = mask;
+}
+
+/**
+ * @brief Get the HP core interrupt register status.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ *
+ * @return Interrupt status value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_hp_intr_status(lp_mb_dev_t *dev)
+{
+    return dev->hp_int_st.val;
+}
+
+/**
+ * @brief Enable mailbox interrupts by mask for the HP core.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to enable, bit `i` represents message `i`.
+ *
+ * @return Updated interrupt enable register value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_hp_intr_enable_mask(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->hp_int_ena.val |= mask;
+    return dev->hp_int_ena.val;
+}
+
+/**
+ * @brief Disable HP core mailbox interrupts by mask.
+ *
+ * @param dev Pointer to the LP mailbox device structure.
+ * @param mask Bitmask of interrupts to disable, bit `i` represents message `i`.
+ *
+ * @return Updated interrupt enable register value.
+ */
+FORCE_INLINE_ATTR uint32_t lp_mailbox_ll_hp_intr_disable_mask(lp_mb_dev_t *dev, uint32_t mask)
+{
+    dev->hp_int_ena.val &= ~mask;
+    return dev->hp_int_ena.val;
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32p4/include/hal/pmu_ll.h

@@ -493,6 +493,11 @@ FORCE_INLINE_ATTR void pmu_ll_hp_clear_reject_cause(pmu_dev_t *hw)
     hw->wakeup.cntl4.slp_reject_cause_clr = 1;
 }
 
+FORCE_INLINE_ATTR void pmu_ll_hp_enable_sw_intr(pmu_dev_t *hw, bool enable)
+{
+    hw->hp_ext.int_ena.sw = enable;
+}
+
 FORCE_INLINE_ATTR bool pmu_ll_hp_is_sleep_wakeup(pmu_dev_t *hw)
 {
     return (hw->hp_ext.int_raw.wakeup == 1);
@@ -503,6 +508,16 @@ FORCE_INLINE_ATTR bool pmu_ll_hp_is_sleep_reject(pmu_dev_t *hw)
     return (hw->hp_ext.int_raw.reject == 1);
 }
 
+FORCE_INLINE_ATTR void pmu_ll_lp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.lp_trigger_hp = 1;
+}
+
+FORCE_INLINE_ATTR void pmu_ll_hp_trigger_sw_intr(pmu_dev_t *hw)
+{
+    hw->hp_lp_cpu_comm.hp_trigger_lp = 1;
+}
+
 FORCE_INLINE_ATTR void pmu_ll_hp_clear_sw_intr_status(pmu_dev_t *hw)
 {
     hw->hp_ext.int_clr.sw = 1;

components/soc/esp32p4/include/soc/Kconfig.soc_caps.in

@@ -283,6 +283,10 @@ config SOC_LP_VAD_SUPPORTED
     bool
     default y
 
+config SOC_LP_MAILBOX_SUPPORTED
+    bool
+    default y
+
 config SOC_SPIRAM_SUPPORTED
     bool
     default y

components/soc/esp32p4/include/soc/soc_caps.h

@@ -93,6 +93,7 @@
 #define SOC_LP_SPI_SUPPORTED            1
 #define SOC_LP_ADC_SUPPORTED            1
 #define SOC_LP_VAD_SUPPORTED            1
+#define SOC_LP_MAILBOX_SUPPORTED        1
 #define SOC_SPIRAM_SUPPORTED            1
 #define SOC_PSRAM_DMA_CAPABLE           1
 #define SOC_SDMMC_HOST_SUPPORTED        1

components/soc/esp32p4/ld/esp32p4.peripherals.ld

@@ -76,6 +76,7 @@ PROVIDE ( LP_AON_CLKRST = 0x50111000 );
 PROVIDE ( EFUSE         = 0x5012D000 );
 PROVIDE ( LPPERI        = 0x50120000 );
 PROVIDE ( LP_TIMER      = 0x50112000 );
+PROVIDE ( LP_MAILBOX    = 0x50118000 );
 PROVIDE ( LP_UART       = 0x50121000 );
 PROVIDE ( LP_I2C        = 0x50122000 );
 PROVIDE ( LP_SPI        = 0x50123000 );