Merge branch 'feat/gdma_burst_size_fallback' into 'master'

fix(gdma): treat burst size 0 and 1 as burst disabled See merge request espressif/esp-idf!52209
2026-10-01 18:50:34 +03:00 · 2026-09-09 11:05:33 +08:00
parent 5286f60b26 f5afb99e3b
commit 8284596d78
35 changed files with 203 additions and 111 deletions
@@ -101,7 +101,7 @@ When creating a driver instance, you need to configure:

 - **backlog**: Maximum number of pending CRC requests that can be queued. Higher values use more memory but provide better throughput for bursty workloads.
 - **intr_priority**: DMA interrupt priority. Set to ``0`` to use the default low/medium priority, or set a non-zero value to request a specific interrupt priority.
- **dma_burst_size**: DMA transfer burst size in bytes.
+- **dma_burst_size**: DMA transfer burst size in bytes. Set to ``0`` to use the driver default (16 bytes), or to ``1`` to disable the data burst.

 The driver handle ``crc_hdl`` is an opaque pointer that you use for all subsequent operations.

@@ -327,6 +327,7 @@ The ``dma_burst_size`` affects DMA transfer efficiency:

 - Larger burst sizes can improve throughput
 - Typical values: 16, 32, 64 bytes
+- Set to ``0`` to use the driver default (16 bytes), or to ``1`` to disable the data burst

 The optimal value depends on your chip's DMA controller capabilities.

@@ -92,7 +92,11 @@ Select a DMA backend explicitly when installing the driver. The AHB GDMA backend
    :SOC_LP_AHB_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_lp_ahb`
    :SOC_DW_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_dw_gdma`

-For a single blocking copy, set :cpp:member:`async_memcpy_config_t::backlog` to 1. Increase it when multiple copies can be pending. :cpp:member:`async_memcpy_config_t::dma_burst_size` controls the burst size in bytes; start with 16 and tune it only after measuring your workload. Set :cpp:member:`async_memcpy_config_t::weight` to 0 unless weighted arbitration is supported and your application needs to adjust its average bus bandwidth.
+For a single blocking copy, set :cpp:member:`async_memcpy_config_t::backlog` to 1. Increase it when multiple copies can be pending.
+
+:cpp:member:`async_memcpy_config_t::dma_burst_size` controls the burst size in bytes; start with 16 and tune it only after measuring your workload. Set it to ``0`` to use the driver default (16 bytes), or to ``1`` to disable the data burst.
+
+Set :cpp:member:`async_memcpy_config_t::weight` to 0 unless weighted arbitration is supported and your application needs to adjust its average bus bandwidth.

 Scenario 2: Continue Working While DMA Copies
 ==============================================
@@ -7,5 +7,6 @@ Migration from 6.1 to 6.2
    :maxdepth: 1

    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
+    peripherals
    security
    system
@@ -0,0 +1,27 @@
+Peripherals
+===========
+
+:link_to_translation:`zh_CN:[中文]`
+
+DMA
+---
+
+Unified ``dma_burst_size`` Default
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:cpp:member:`uhci_controller_config_t::dma_burst_size`, :cpp:member:`async_memcpy_config_t::dma_burst_size`, and :cpp:member:`async_crc_config_t::dma_burst_size` now treat ``0`` as unset and fall back to that driver's own recommended default. This matches I2S, SPI, and LCD, and closes a hole where a zero-initialized config struct could only disable the burst — there was no way to ask for the driver default.
+
+``1`` is newly defined as "disable the data burst". A single-beat burst has no benefit over non-burst mode.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - ``dma_burst_size``
+     - Meaning
+   * - ``0``
+     - Fall back to the driver's recommended default
+   * - ``1``
+     - Disable data burst
+   * - ``N`` (``N > 1``, power of 2)
+     - User-specified burst size
@@ -101,7 +101,7 @@

 - **backlog**：可排队等待的最大 CRC 请求数。较高的值使用更多内存，但在突发工作负载下提供更好的吞吐量。
 - **intr_priority**：DMA 中断优先级。设置为 ``0`` 时使用默认的低/中优先级；设置为非零值时请求指定的中断优先级。
- **dma_burst_size**：DMA 传输突发大小（字节）。
+- **dma_burst_size**：DMA 传输突发大小（字节）。设为 ``0`` 表示使用驱动默认值（16 字节），设为 ``1`` 表示关闭数据突发传输。

 驱动程序句柄 ``crc_hdl`` 是一个不透明指针，用于所有后续操作。

@@ -327,6 +327,7 @@ DMA 突发大小

 - 较大的突发大小可以提高吞吐量
 - 典型值：16、32、64 字节
+- 设为 ``0`` 表示使用驱动默认值（16 字节），设为 ``1`` 表示关闭数据突发传输

 最佳值取决于芯片的 DMA 控制器功能。

@@ -92,7 +92,11 @@ DMA 必须能访问源和目标 buffer。目标 buffer 应分配在 DMA 可访
    :SOC_LP_AHB_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_lp_ahb`
    :SOC_DW_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_dw_gdma`

-对于一次阻塞复制，将 :cpp:member:`async_memcpy_config_t::backlog` 设为 1 即可；若可能同时等待多个复制请求，应增大该值。:cpp:member:`async_memcpy_config_t::dma_burst_size` 设置 DMA 突发大小，单位为字节；可从 16 开始，仅在性能测试后再调整。除非目标芯片支持加权仲裁且应用需要调节平均总线带宽，否则将 :cpp:member:`async_memcpy_config_t::weight` 设为 0。
+对于一次阻塞复制，将 :cpp:member:`async_memcpy_config_t::backlog` 设为 1 即可；若可能同时等待多个复制请求，应增大该值。
+
+:cpp:member:`async_memcpy_config_t::dma_burst_size` 设置 DMA 突发大小，单位为字节；可从 16 开始，仅在性能测试后再调整。设为 ``0`` 表示使用驱动默认值（16 字节），设为 ``1`` 表示关闭数据突发传输。
+
+除非目标芯片支持加权仲裁且应用需要调节平均总线带宽，否则将 :cpp:member:`async_memcpy_config_t::weight` 设为 0。

 场景 2：在 DMA 复制期间继续工作
 =================================
@@ -7,5 +7,6 @@
    :maxdepth: 1

    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
+    peripherals
    security
    system
@@ -0,0 +1,27 @@
+外设驱动
+========
+
+:link_to_translation:`en:[English]`
+
+DMA
+---
+
+统一 ``dma_burst_size`` 的默认值语义
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:cpp:member:`uhci_controller_config_t::dma_burst_size`、:cpp:member:`async_memcpy_config_t::dma_burst_size` 和 :cpp:member:`async_crc_config_t::dma_burst_size` 现在把 ``0`` 视为未设置，并回落到该驱动自己推荐的默认值。这与 I2S、SPI、LCD 的约定一致，也补上了原先的漏洞：配置结构体零初始化时只能关掉 burst，无法表达“使用驱动默认值”。
+
+``1`` 是新引入的含义，表示显式关闭数据突发传输。单 beat 突发相对于非突发没有收益。
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - ``dma_burst_size``
+     - 含义
+   * - ``0``
+     - 回落到该驱动推荐的默认值
+   * - ``1``
+     - 关闭数据突发传输
+   * - ``N`` （``N > 1``，且为 2 的幂）
+     - 用户指定的突发大小