Merge branch 'backport/suppport_ot_message_pool_using_PSRAM' into 'release/v5.1'

feat(openthread): support to allocate message pool from PSRAM(backport v5.1)

See merge request espressif/esp-idf!25990

components/openthread/CMakeLists.txt

@@ -149,6 +149,11 @@ if(CONFIG_OPENTHREAD_ENABLED)
             "src/port/esp_openthread_sleep.c")
     endif()
 
+    if(NOT CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT)
+        list(APPEND exclude_srcs
+            "src/port/esp_openthread_messagepool.c")
+    endif()
+
     if(CONFIG_OPENTHREAD_FTD)
         set(device_type "OPENTHREAD_FTD=1")
     elseif(CONFIG_OPENTHREAD_MTD)

components/openthread/Kconfig

@@ -207,11 +207,19 @@ menu "OpenThread"
         help
             Select this option to enable border router features in OpenThread.
 
+    config OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT
+        bool 'Allocate message pool buffer from PSRAM'
+        depends on OPENTHREAD_ENABLED && (SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC)
+        default n
+        help
+            If enabled, the message pool is managed by platform defined logic.
+
     config OPENTHREAD_NUM_MESSAGE_BUFFERS
         int "The number of openthread message buffers"
         depends on OPENTHREAD_ENABLED
         default 65
-        range 50 100
+        range 10 100 if !OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT
+        range 10 8191 if OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT
 
     config OPENTHREAD_DNS64_CLIENT
         bool "Use dns64 client"

components/openthread/private_include/esp_openthread_flash.h

@@ -1,25 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-#pragma once
-
-#include "esp_partition.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * @brief  Set the partition to store OpenThread dataset.
- *
- * @param[in]   partition   The storage partition.
- *
- */
-void esp_openthread_flash_set_partition(const esp_partition_t *partition);
-
-#ifdef __cplusplus
-}
-#endif

components/openthread/private_include/openthread-core-esp32x-ftd-config.h

@@ -517,4 +517,23 @@
 #define OPENTHREAD_CONFIG_OPERATIONAL_DATASET_AUTO_INIT 1
 #endif
 
+
+/**
+ *
+ * Define as 1 to enable support for allocating message pool buffer in PSRAM
+ *
+ */
+#if CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT
+
+/**
+ * @def OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT
+ *
+ * The message pool is managed by platform defined logic when this flag is set.
+ * This feature would typically be used when operating in a multi-threaded system
+ * and multiple threads need to access the message pool.
+ *
+ */
+#define OPENTHREAD_CONFIG_PLATFORM_MESSAGE_MANAGEMENT 1
+#endif
+
 #define OPENTHREAD_FTD 1

components/openthread/src/esp_openthread_platform.cpp

@@ -11,7 +11,6 @@
 #include "esp_log.h"
 #include "esp_openthread_alarm.h"
 #include "esp_openthread_common_macro.h"
-#include "esp_openthread_flash.h"
 #include "esp_openthread_lock.h"
 #include "esp_openthread_radio.h"
 #include "esp_openthread_spi_slave.h"

components/openthread/src/port/esp_openthread_flash.c

@@ -1,65 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-#include "esp_openthread_flash.h"
-#include "esp_partition.h"
-#include "openthread/instance.h"
-#include "openthread/platform/flash.h"
-#include "openthread/platform/settings.h"
-
-#define ESP_OT_FLASH_PAGE_NUM 2
-#define ESP_OT_FLASH_PAGE_SIZE 4096
-
-static const esp_partition_t *s_ot_partition = NULL;
-
-void esp_openthread_flash_set_partition(const esp_partition_t *partition)
-{
-    s_ot_partition = partition;
-}
-
-void otPlatFlashInit(otInstance *instance)
-{
-    assert(s_ot_partition != NULL);
-    assert(s_ot_partition->size >= otPlatFlashGetSwapSize(instance));
-}
-
-uint32_t otPlatFlashGetSwapSize(otInstance *instance)
-{
-    return ESP_OT_FLASH_PAGE_SIZE;
-}
-
-void otPlatFlashErase(otInstance *instance, uint8_t index)
-{
-    uint32_t address = ESP_OT_FLASH_PAGE_SIZE * (index != 0);
-    uint32_t size = ESP_OT_FLASH_PAGE_SIZE;
-    esp_err_t err = ESP_OK;
-
-    err = esp_partition_erase_range(s_ot_partition, address, size);
-
-    assert(err == ESP_OK);
-}
-
-void otPlatFlashRead(otInstance *instance, uint8_t index, uint32_t offset, void *data, uint32_t size)
-{
-    esp_err_t err = ESP_OK;
-
-    offset += ESP_OT_FLASH_PAGE_SIZE * (index != 0);
-
-    err = esp_partition_read(s_ot_partition, offset, data, size);
-
-    assert(err == ESP_OK);
-}
-
-void otPlatFlashWrite(otInstance *instance, uint8_t index, uint32_t offset, const void *data, uint32_t size)
-{
-    esp_err_t err = ESP_OK;
-
-    offset += ESP_OT_FLASH_PAGE_SIZE * (index != 0);
-
-    err = esp_partition_write(s_ot_partition, offset, data, size);
-
-    assert(err == ESP_OK);
-}

components/openthread/src/port/esp_openthread_messagepool.c

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "openthread-core-config.h"
+#include "esp_openthread_common_macro.h"
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_heap_caps.h"
+#include "openthread/instance.h"
+#include "openthread/platform/messagepool.h"
+
+int s_buffer_pool_head = -1;
+otMessageBuffer **s_buffer_pool_pointer = NULL;
+
+void otPlatMessagePoolInit(otInstance *aInstance, uint16_t aMinNumFreeBuffers, size_t aBufferSize)
+{
+    otMessageBuffer *buffer_pool = (otMessageBuffer *)heap_caps_calloc(aMinNumFreeBuffers, aBufferSize, MALLOC_CAP_SPIRAM);
+    s_buffer_pool_pointer = (otMessageBuffer **)heap_caps_calloc(aMinNumFreeBuffers, sizeof(otMessageBuffer **), MALLOC_CAP_SPIRAM);
+    if (buffer_pool == NULL || s_buffer_pool_pointer == NULL) {
+        ESP_LOGE(OT_PLAT_LOG_TAG, "Failed to create message buffer pool");
+        assert(false);
+    }
+    for (uint16_t i = 0; i < aMinNumFreeBuffers; i++) {
+        s_buffer_pool_pointer[i] = buffer_pool + i * aBufferSize / sizeof(otMessageBuffer);
+    }
+    s_buffer_pool_head = aMinNumFreeBuffers - 1;
+    ESP_LOGI(OT_PLAT_LOG_TAG, "Create message buffer pool successfully, size %d", aMinNumFreeBuffers*aBufferSize);
+}
+
+otMessageBuffer *otPlatMessagePoolNew(otInstance *aInstance)
+{
+    otMessageBuffer *ret = NULL;
+    if (s_buffer_pool_head >= 0) {
+        ret = s_buffer_pool_pointer[s_buffer_pool_head];
+        s_buffer_pool_head--;
+    }
+    return ret;
+}
+
+void otPlatMessagePoolFree(otInstance *aInstance, otMessageBuffer *aBuffer)
+{
+    s_buffer_pool_head++;
+    s_buffer_pool_pointer[s_buffer_pool_head] = aBuffer;
+}
+
+uint16_t otPlatMessagePoolNumFreeBuffers(otInstance *aInstance)
+{
+    return s_buffer_pool_head + 1;
+}

docs/en/api-guides/performance/ram-usage.rst

@@ -41,6 +41,7 @@ To minimize static memory use:
 
    - Constant data can be stored in flash memory instead of RAM, thus it is recommended to declare structures, buffers, or other variables as ``const``. This approach may require modifying firmware functions to accept ``const *`` arguments instead of mutable pointer arguments. These changes can also help reduce the stack usage of certain functions.
    :SOC_BT_SUPPORTED: - If using Bluedroid, setting the option :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY` will cause Bluedroid to allocate memory on initialization and free it on deinitialization. This does not necessarily reduce the peak memory usage, but changes it from static memory usage to runtime memory usage.
+   - If using OpenThread, enabling the option :ref:`CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT` will cause OpenThread to allocate message pool buffers from PSRAM, which will reduce static memory use.
 
 .. _optimize-stack-sizes:
 

docs/zh_CN/api-guides/performance/ram-usage.rst

@@ -41,6 +41,7 @@ ESP-IDF 包含一系列堆 API，可以在运行时测量空闲堆内存，请
 
    - 由于常量数据可以存储在 flash 中，不占用 RAM，建议尽量将结构体、缓冲区或其他变量声明为 ``const``。为此，可能需要修改固件参数，使其接收 ``const *`` 参数而非可变指针参数。以上更改还可以减少某些函数的栈内存使用。
    :SOC_BT_SUPPORTED: - 若使用 Bluedroid，请设置 :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY` 选项，Bluedroid 将在初始化时分配内存，并在去初始化时释放内存。这并不一定会降低内存使用峰值，但可以将使用静态内存改为运行时使用动态内存。
+   - 若使用 OpenThread，请设置 :ref:`CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT` 选项，OpenThread 将从外部 PSRAM 中分配消息池缓冲区，从而减少对内部静态内存的使用。
 
 .. _optimize-stack-sizes: