Merge branch 'feature/add_doc_and_trace_menuconfig' into 'main'

gmf_app_utils: Add custom board doc and stack trace records setting

See merge request adf/multimedia/esp-gmf!101

Author: jason-mao

packages/gmf_app_utils/Kconfig.projbuild

@@ -78,6 +78,10 @@ menu "Unit Test"
         int "Critical leak for UT which use LWIP component"
         default 4095
 
+    config UNITY_HEAP_TRACE_RECORDS
+        int "Number of heap trace records to allocate for Unity test"
+        default 200
+
 endmenu
 
 endmenu

packages/gmf_app_utils/README.md

@@ -31,6 +31,8 @@ The `gmf_app_utils` component also provides configuration options via **menuconf
   - SD card initialization and mounting
 - Connectivity management
   - Wi-Fi initialization and connection
+- Use menuconfig to select supported board
+  - For other board support see [Other Board Support](#other-board-support) section
 
 ### System Tools (`esp_gmf_app_sys.h`)
 Provides start/stop functionality for system resource monitoring, facilitating runtime performance tracking and resource usage monitoring. To use this feature, you need to enable `CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID` and `CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS` in menuconfig.
@@ -67,3 +69,43 @@ Provide common functions for GMF application unit tests
   - Call `esp_gmf_app_test_case_uses_tcpip()` in tests that require network functionality
   - Use test annotations like `[leaks]` or `[leaks=1024]` to control leak checking
   - The main function calls' esp_gmf_app_test_main() 'to create the unit test Task
+
+### Other Board Support
+
+Peripheral management currently uses `codec_board` as a reference implementation for fast verification. If you want to use supported peripherals on a custom board, follow these steps:
+
+1. **Get `codec_board`** and put into project `components` folder
+   
+   Can use either of following methods:
+   
+   1.1 Build firstly to trigger auto download then copy it into project folder:
+   ```bash
+   idf.py build
+   mkdir -p components/codec_board
+   cp -rf managed_components/tempotian__codec_board components/codec_board
+   ```
+   
+   1.2 Download [codec_board](https://components.espressif.com/components/tempotian/codec_board/) from component registry and manual copy into project folder
+
+2. **Add a new section** to `components/codec_board/board_cfg.txt` to describe your custom board:
+   ```
+   Board: MY_BOARD
+   i2c: {sda: 1, scl: 2}
+   i2s: {mclk: 42, bclk: 40, ws: 41, dout: 39}
+   out: {codec: ES8311, pa: 38, use_mclk: 0, pa_gain: 6}
+   ```
+
+3. **Set the board type** in your application code before calling any peripheral APIs:
+   ```c
+   #include "codec_board.h"
+   void app_main(void)
+   {
+       set_codec_board_type("MY_BOARD");
+   }
+   ```
+
+4. **Rebuild to take effects**
+   ```bash
+   idf.py fullclean
+   idf.py -p /dev/XXXXX flash monitor
+   ```

packages/gmf_app_utils/README_CN.md

@@ -31,6 +31,8 @@ GMF 应用工具包（gmf_app_utils）是一个为方便 ESP GMF 开发应用程
   - SD 卡初始化和挂载
 - 连接管理
   - Wi-Fi 初始化连接
+- 通过 Menuconfig 选择支持的开发板
+  - 其他开发板支持请参阅 [其他开发板支持](#其他开发板支持) 小节
 
 ### 系统工具（`esp_gmf_app_sys.h`）
 提供系统资源监控功能的启动/停止，便于用户运行时性能跟踪以及资源使用情况监控，使用时需要在 menuconfig 中开启 `CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID` 和 `CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS`。
@@ -67,3 +69,43 @@ GMF 应用工具包（gmf_app_utils）是一个为方便 ESP GMF 开发应用程
   - 使用`esp_gmf_app_test_case_uses_tcpip()`进行网络测试项资源预分配
   - 支持通过测试项描述如 `[leaks]` 或 `[leaks=1024]` 控制泄漏检查阈值
   - main 函数调用 `esp_gmf_app_test_main()` 创建单元测试线程
+
+### 其他开发板支持
+
+外设管理目前使用 `codec_board` 作为参考板卡实现，便于快速验证。若要在自定义开发板上使用支持的外设，请按照以下步骤操作：
+
+1. **获取 `codec_board`** 并将其放入项目的 `components` 文件夹
+   
+   可以使用以下任一方法：
+   
+   1.1 首先构建代码以触发自动下载，然后复制到项目文件夹：
+   ```bash
+   idf.py build
+   mkdir -p components/codec_board
+   cp -rf managed_components/tempotian__codec_board components/codec_board
+   ```
+   
+   1.2 从组件注册表下载 [codec_board](https://components.espressif.com/components/tempotian/codec_board/) 并手动复制到项目文件夹
+
+2. **在 `components/codec_board/board_cfg.txt` 中添加新的开发板配置节**，例如：
+   ```
+   Board: MY_BOARD
+   i2c: {sda: 1, scl: 2}
+   i2s: {mclk: 42, bclk: 40, ws: 41, dout: 39}
+   out: {codec: ES8311, pa: 38, use_mclk: 0, pa_gain: 6}
+   ```
+
+3. **在调用任何外设 API 之前，在应用代码中设置板卡类型**：
+   ```c
+   #include "codec_board.h"
+   void app_main(void)
+   {
+       set_codec_board_type("MY_BOARD");
+   }
+   ```
+
+4. **重新构建代码使修改生效**：
+   ```bash
+   idf.py fullclean
+   idf.py -p /dev/XXXXX flash monitor
+   ```

packages/gmf_app_utils/idf_component.yml

@@ -11,6 +11,8 @@ tags:
 
 dependencies:
   espressif/gmf_core:
+    require: public
     version: "^0.7"
   tempotian/codec_board:
+    require: public
     version: "^0.5.0"

packages/gmf_app_utils/src/esp_gmf_app_unit_test.c

@@ -135,7 +135,7 @@ static size_t gmf_app_get_leak_level(esp_gmf_app_leak_type_t type_of_leak, esp_g
 #ifdef CONFIG_HEAP_TRACING
 static void gmf_app_setup_heap_record(void)
 {
-    const size_t num_heap_records = 200;
+    const size_t num_heap_records = CONFIG_UNITY_HEAP_TRACE_RECORDS;
     static heap_trace_record_t *record_buffer;
     if (!record_buffer) {
         record_buffer = heap_caps_malloc_prefer(sizeof(heap_trace_record_t) * num_heap_records, 2, MALLOC_CAP_SPIRAM, MALLOC_CAP_INTERNAL);