Re: [PATCH 1/4] docs: arm: stm32: introduce STM32 DMA-MDMA chaining feature

From: Amelie Delaunay
Date: Tue Jul 12 2022 - 09:38:09 EST

On 7/11/22 17:11, Jonathan Corbet wrote:
Amelie Delaunay <amelie.delaunay@xxxxxxxxxxx> writes:

STM32 DMA-MDMA chaining feature is available on STM32 SoCs which embed
STM32 DMAMUX, DMA and MDMA controllers. It is the case on STM32MP1 SoCs but
also on STM32H7 SoCs. But focus is on STM32MP1 SoCs, using DDR.
This documentation aims to explain how to use STM32 DMA-MDMA chaining
feature in drivers of STM32 peripheral having request lines on STM32 DMA.

Signed-off-by: Amelie Delaunay <amelie.delaunay@xxxxxxxxxxx>
.../arm/stm32/stm32-dma-mdma-chaining.rst | 365 ++++++++++++++++++
1 file changed, 365 insertions(+)
create mode 100644 Documentation/arm/stm32/stm32-dma-mdma-chaining.rst

When you add a new RST file you also need to add it to index.rst
somewhere so that it becomes part of the docs build.

Thanks for you review.

I'll add it to index.rst, with other stm32 documentations.

diff --git a/Documentation/arm/stm32/stm32-dma-mdma-chaining.rst b/Documentation/arm/stm32/stm32-dma-mdma-chaining.rst
new file mode 100644
index 000000000000..bfbbadc45aa7
--- /dev/null
+++ b/Documentation/arm/stm32/stm32-dma-mdma-chaining.rst
@@ -0,0 +1,365 @@
+.. SPDX-License-Identifier: GPL-2.0
+STM32 DMA-MDMA chaining
+ This document describes the STM32 DMA-MDMA chaining feature. But before going further, let's
+ introduce the peripherals involved.

Please keep to the 80-column limit for documentation, it makes it easier
to read.

OK, I prepare a v2 with a 80-column limit for the documentation patch.

+ To offload data transfers from the CPU, STM32 microprocessors (MPUs) embed direct memory access
+ controllers (DMA).
+ STM32MP1 SoCs embed both STM32 DMA and STM32 MDMA controllers. STM32 DMA request routing
+ capabilities are enhanced by a DMA request multiplexer (STM32 DMAMUX).
+ **STM32 DMAMUX**
+ STM32 DMAMUX routes any DMA request from a given peripheral to any STM32 DMA controller (STM32MP1
+ counts two STM32 DMA controllers) channels.
+ **STM32 DMA**
+ STM32 DMA is mainly used to implement central data buffer storage (usually in the system SRAM) for
+ different peripheral. It can access external RAMs but without the ability to generate convenient
+ burst transfer ensuring the best load of the AXI.
+ **STM32 MDMA**
+ STM32 MDMA (Master DMA) is mainly used to manage direct data transfers between RAM data buffers
+ without CPU intervention. It can also be used in a hierarchical structure that uses STM32 DMA as
+ first level data buffer interfaces for AHB peripherals, while the STM32 MDMA acts as a second
+ level DMA with better performance. As a AXI/AHB master, STM32 MDMA can take control of the AXI/AHB
+ bus.
+ STM32 DMA-MDMA chaining feature relies on the strengths of STM32 DMA and STM32 MDMA controllers.
+ STM32 DMA has a circular Double Buffer Mode (DBM). At each end of transaction (when DMA data
+ counter - DMA_SxNDTR - reaches 0), the memory pointers (configured with DMA_SxSM0AR and
+ DMA_SxM1AR) are swapped and the DMA data counter is automatically reloaded. This allows the SW or
+ the STM32 MDMA to process one memory area while the second memory area is being filled/used by the
+ STM32 DMA transfer.
+ With STM32 MDMA linked-list mode, a single request initiates the data array (collection of nodes)
+ to be transferred until the linked-list pointer for the channel is null. The channel transfer
+ complete of the last node is the end of transfer, unless first and last nodes are linked to each
+ other, in such a case, the linked-list loops on to create a circular MDMA transfer.
+ STM32 MDMA has direct connections with STM32 DMA. This enables autonomous communication and
+ synchronization between peripherals, thus saving CPU resources and bus congestion. Transfer
+ Complete signal of STM32 DMA channel can triggers STM32 MDMA transfer. STM32 MDMA can clear the
+ request generated by the STM32 DMA by writing to its Interrupt Clear register (whose address is
+ stored in MDMA_CxMAR, and bit mask in MDMA_CxMDR).
+ .. csv-table:: STM32 MDMA interconnect table with STM32 DMA
+ :header: "STM32 DMAMUX channels", "STM32 DMA controllers channels",
+ "STM32 DMA Transfer Complete signal", "STM32 MDMA request"

If at all possible, please use simple tables; that makes the plain text
documentation much easier to read.

It is possible, with some extra lines. I'll update it in v2 coming soon.