GPDMA and hate about documentation

[Eiffel]

Hi guys, 

first of all, after many hours of study of this peripheral i have "few" points. I will try to be as nice and calm as actually possible.

1: Does anyone in ST review documentation and code you are generating? RM0456 17.4.2 paragraph 2:

"After enabling/starting a GPDMA channel transfer by writing 1 in GPDMA_CxCR.EN, a
GPDMA channel interrupt on a complete transfer notifies the software that the GPDMA
channel is back in idle state (EN is then deasserted by hardware) and that the channel is
ready to be reconfigured then enabled again."

What does it mean? Do i have to start GPDMA channel and then configure it? (Nonsens) Shall be channel configured before it? (obviously) Transfer Complete interrupt is triggered right after enabling/starting channel? Do i have to somehow filter it? LEARN HOW TO WRITE DOCUMENTATION!

2: How the hell shall be ports used? You recommend to use Port1 for memory access and Port0 for peripheral acces (in case the periph-memory transfer is used), but when you generate something from CubeMX, the linked list port use Port0! LEARN HOW TO WRITE DOCUMENTATION!

3: What the hell is block and burst requests. What is difference between linked item and block? What is difference between block, repetitive block, linked list and single/burst transfers? Is repetitive block 2D?  LEARN HOW TO WRITE DOCUMENTATION!

4: What is "low-significant bits"??? You meant Least-significant bits?! Who have you hired? Who let you write documentation? Who did a review of it?

I will update this thread with those nonsenses.

[Jaroslav BECKA]

Hi Eiffel,

Thanks for your detailed feedback and observations regarding the GPDMA peripheral and its documentation.
We appreciate the time and effort you have invested in studying the material and providing your feedback.

To help clarify some of the points about the GPDMA, I would like to share an application note that covers the GPDMA in depth and may answer some of your questions:

AN5593: How to use the GPDMA for STM32 MCUs.

The description from the RM0456 17.4.2 paragraph 2 can be rephrased as follows for better understanding:

A GPDMA channel transfer starts when the EN bit in the GPDMA_CxCR register is set to 1.
Once the transfer is complete, a transfer complete interrupt is generated to notify the software that the transfer has finished. The channel returns to the idle state, ready to be configured and started again.
The EN bit is cleared automatically by hardware.

If you encounter any issues or have concerns about the technical documentation, I suggest using the OLS system to report them. 

https://ols.st.com/s/

We are continuously working on improving our documentation and your feedback will be taken into account.

Best regards

Jaroslav Becka

[Eiffel]

Hi Jaroslav,

I went through an5593 also, but it still does not explain primitive functionality of GPDMA. There is still a lot of questions. For example, what is TRIGM in register TR2? Lets go step bys tep, ok?

Value 00: A GPDMA transfer is conditioned by at least one trigger hit at block level: the first burst read of each block transfer is conditioned by one hit trigger
(channel x (x = 12 to 15), for each block if a 2D/repeated block is configured with
GPDMA_CxBR1.BRC[10:0] ≠ 0).

- Does at leat a guy that wrote this understands it? What does it mean? will it trigger the transfer of whole length configured in BR1.BNDT at once? And in 2D transfers will it trigger only one BRC and next trigger will start another BRC? 

Value 01: A GPDMA transfer is conditioned by at least one trigger hit channel x (x = 0 to 11), same as 00; channel x (x = 12 to 15), at 2D/repeated block level. The first burst read of a 2D/repeated block transfer is conditioned by one hit trigger.

- Does this mean that this will trigger whole count of BRC and BNDT?

Value 10: A GPDMA transfer is conditioned by at least one trigger hit at link level: a LLI link transfer is conditioned by one hit trigger. The LLI data transfer (if any) is not conditioned.

- What does this mean? I have no idea.

Value 11: A GPDMA transfer is conditioned by at least one trigger hit at programmed burst level: If SWREQ = 1, each programmed burst read is conditioned by one hit trigger. If SWREQ = 0, each programmed burst that is requested by the selected peripheral, is conditioned by one hit trigger.

- Does this mean that every trigger will trigger only one transfer from peripheral register to memory (or vice versa)? 

And what about the rest of the text? Is it part of value 11? Or is it some additional info? Where is indentation? 

The whole document is terrible. How could you release something like that?

Edit:

RM0456 17.4.12 : 

The triggered transfer, as defined by the trigger mode in GPDMA_CxTR2.TRIGM[1:0], can
be at LLI data transfer level, to condition the first burst read of a block, the first burst read of
a 2D/repeated block for channel x (x = 12 to 15), or each programmed single read. The
trigger mode can also be programmed to condition the LLI link transfer (see TRIGM[1:0] in
GPDMA_CxTR2 for more details).

Question: What is "first burst read"? Will it trigger just first transfer? What with other transfers defined by BNDT? Why is there only 3 cases when configuration options are 4? Do you see why this document is trash?

[Eiffel · Accepted solution]

Ok, i have finally understood what TRIGGER is. Btw, nice job with hiding this. It is really "easy" to udnerstand it.

To make it easier for others i will try to explain it.

There are two "starting" signals for data transfer (ignoring difference between memory-to-memory, memory-to-peripheral or peripheral-to-memory). In standard DMA are only requests. The requests in GPDMA are the same. BUT, you can add hardware condition, when those requests are really executed. And those conditions are TRIGGERS. 

Lets say you need to transfer data from ADC only if the analog watchdog detected the threshold value. In this case you use trigger from this analog watchdog and request from ADC. If threshold on analog watchdog is not detected, requests for transfers are ignored. Otherwise are transfered. And here comes the trigger mode (TRGM) and values:

00: At block level: The whole block will be transferred after single trigger. 

01:At block level on 2D: The whole block BUT in 2D. That means, all rows and all collumns will be transfered after single trigger.

10: At link level: Linked list will be updated after trigger signal.

11: At burst level: Every transfer (every transfer of data) needs trigger signal. Something like secondary request for transfer. Both trigger and request must be active.