[DMA 8/8] Burst configuration

[bugadani]

Thank you for your contribution!

We appreciate the time and effort you've put into this pull request.
To help us review it efficiently, please ensure you've gone through the following checklist:

Submission Checklist 📝

• I have updated existing examples or added new ones (if applicable).
• I have used cargo xtask fmt-packages command to ensure that all changed code is formatted correctly.
• My changes were added to the CHANGELOG.md in the proper section.
• I have added necessary changes to user code to the Migration Guide.
• My changes are in accordance to the esp-rs API guidelines

Extra:

• I have read the CONTRIBUTING.md guide and followed its instructions.

Pull Request Details 📖

Description

This PR adds burst mode configuration to the DMA buffers. This is somewhat out of their scope, but I believe they may be a slight overcomplication anyway. The PR also describes burst mode constraints for both internal and PSRAM accesses, where applicable.

[Dominaezzz]

• we can probably enable external memory support in DmaRxBuf

Easier said than done.

Before this can happen, the work to remove DmaRxBuffer::length (and less importantly DmaTxBuffer as well) has to be done (which mostly means the SPI DMA driver has to take the length explicitly, rather than infer from the DmaRxBuffer).

Why? Enabling extmem support in DmaRxBuf means conforming to the 16,32,64 byte alignment in size. The means DmaRxBuffer::length() would always be a multiple of 16 (at least).
What happens when someone wants to receive 120 bytes of data into extmem? 120 bytes can't be aligned to 16, 32 or 64. The solution here is a DmaRxBuf of size 128 bytes and an SPI transaction length of 120.

Another nice thing about length() going away is the SPI DMA can be used with all buffer types, not just the linear/basic DmaRxBuf/DmaTxBuf.

[bugadani]

What happens when someone wants to receive 120 bytes of data into extmem?

Note that length is always unconstrained, alignment requirements are for address and size only. For reads, the DMA will pad the received data to 128 bytes, using zeroes. Then the DMA sets the length to the actually received amount. For writes, Size, length and buffer address pointer in transmit descriptors are not necessarily aligned with block size

[Dominaezzz]

What happens when someone wants to receive 120 bytes of data into extmem?

Note that length is always unconstrained, alignment requirements are for address and size only. For reads, the DMA will pad the received data to 128 bytes, using zeroes. Then the DMA sets the length to the actually received amount. For writes, Size, length and buffer address pointer in transmit descriptors are not necessarily aligned with block size

Yes but how do you tell the SPI to only read 120 bytes, instead of the 128 that DmaRxBuf has been set to for alignment reasons?

[bugadani]

Ah okay I understand your issue, it's not a hardware-related one. Yeah this is a consequence of the design right now 🤷‍♂️

I'm guessing we could add a read_length (in spirit, not necessarily in name) field to DmaRxBuf, that we'd use to set up the peripherals. That value wouldn't affect the descriptors, but users could use it to set an upper limit to how much data they want to read.

[Dominaezzz]

Yeah this is a consequence of the design right now 🤷‍♂️

Indeed

I'm guessing we could add a read_length (in spirit, not necessarily in name) field to DmaRxBuf, that we'd use to set up the peripherals. That value wouldn't affect the descriptors, but users could use it to set an upper limit to how much data they want to read.

Yeah that would work but supporting that on other infinite-length descriptors would be awkward.

[bugadani]

Yeah that would work but supporting that on other infinite-length descriptors would be awkward.

Please explain this a bit

[Dominaezzz]

Yeah that would work but supporting that on other infinite-length descriptors would be awkward.

Please explain this a bit

Oops typo. I meant buffers not descriptors. (I need to read my comments more)

DmaRxStreamBuf doesn't really have a length, you can use it to receive data forever so there's no such thing as a "max" length.

[Dominaezzz]

Do you expect that to work with peripherals where the peripheral dictates how much it reads? Especially if there is no TxBuf pair associated to the transfers. I can see slave mode SPI using indeterminate length RX buffers by themselves.

Yes! I'm proposing that the peripheral takes the length. I.e. spi_dma.read(120, dma_rx_buf).

The use case I'm thinking of is the user wants to send (or read) 30000 bytes to an spi device but doesn't want to allocate a 30,000 byte buffer. They could make do with 4000 bytes only and stream the data with a stream buf.

SPI and parl io have special interrupts to let the user know when they were too slow.

[bugadani]

Alright, that sounds to me like a problem for later. For now, if someone is fine with block aligned reads, they are free to allocate the RX buffer in PSRAM.

[bugadani]

Moved this PR back a spot, as this is probably the bigger and more complex change.

[Dominaezzz]

Now that DmaRxBuf has become more configurable, SpiDmaBus will need some changes to accommodate this, otherwise it'll panic when it sets the length to something misaligned.
At construction time, SpiDmaBus needs to turn off bursting (and also reject PSRAM buffers) on the DmaRxBuf it gets.
(Turning off bursting might not exactly be an option on the base ESP32 I suppose)

(Or we can do the thing with the separate lengths 🙂)

[bugadani]

What a mess. Since this check is used by set_length indirectly, restoring 4 would mean we reject all transfer lengths that are not multiples of 4. But the hardware seems to contradict the TRM in that it works just fine...

[Dominaezzz]

What behavior would you expect to see if the TRM wasn't being contradicted?

[MabezDev]

Nit: should we make this a const?

[bugadani]

What do you have in mind? The value depends on the device and burst settings

[MabezDev]

I meant the 4096, it's used inline in a few places

[bugadani]

yeah why not

[bugadani]

I've chosen to keep the literal in code, but deduplicate the calculation. Since 4096 by itself is max chunk size + 1, naming that would be either verbose, or inaccurate.