@Maffels Thanks for approving this. Does this mean that #7641 and #7650 might get approved soon? Updating the documentation is of little use without incorporating the code changes being documented! 😀

My apologies, @nickovs , I tagged "approve" by accident and am unaware of any way of rectifying this mistake.
As far as contributing to this project: I'm afraid I'm enthusiastic about this (together with #7641 and #7650) being added to the next micropython release but not related to any of this in any other way. The "approved" status I accidentally gave it is thus worthless.
Feel free to remove this comment and perhaps if possible the "approved" status.

I have pushed an update to reflect the changes to the configuration model that @dpgeorge requested for #7641.

The documentation says "# The count is in transfers, which default to four-byte words, so divide length by 4".

After testing the Pico and double checking the documentation it appears to default to 0, which would be bytes.

@nickovs A picky note: you might do a global search/substitute of 'crtl' to 'ctrl'. In quite a few places, the letters are swapped.

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS

@NewWheelTech The code as merged defaults to word transfers, so the docs are correct for what we've got. I guess there might be an argument for changing the code to match the C SDK.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.40%. Comparing base (1c6012b) to head (aadbbb9).

❗ Current head aadbbb9 differs from pull request most recent head 77f08b7. Consider uploading reports for the commit 77f08b7 to get more accurate results

@@            Coverage Diff             @@
##           master    #7670      +/-   ##
==========================================
+ Coverage   98.39%   98.40%   +0.01%     
==========================================
  Files         161      159       -2     
  Lines       21156    21088      -68     
==========================================
- Hits        20816    20752      -64     
+ Misses        340      336       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

I guess there might be an argument for changing the code to match the C SDK.

It's not the SDK that defaults to byte transfers, but rather the register is reset to 0 and that means byte transfer size.

I think it's sensible for the default CTRL value (DEFAULT_DMA_CONFIG) to default to word-sized transfers, because that's the most common use (I guess, eg for peripheral access). Then maybe the count parameter to .config() could always be measured in bytes to make it easier for the user... although that would be harder to implement because if the user sets the CTRL register after specifying count then the count value needs to change based on the new data size set by CTRL.

I would recommend not making the count parameter be bytes. That would make the hardware documentation invalid, and I suspect most of us learn about the DMA functionality from that. Also, other DMA devices I have worked with (e.g. on dsPIC33 processors) count transfers, not bytes.

The problem with making count be in bytes is that it's neoither what the hardware uses nor what the C SDK uses. While we can fix this for the .config method and for reading and writing the count attribute, we can't fix this for direct access to the register bank, so if people are doing any sort of scatter/gather operation then it will be inconsistent. Also, if people are reading examples in the the RP2040 datasheet then they will have to make semantic modifications rather than just transliterate. As a result I really think that it should stay as transfers rather than bytes.

As a result I really think that it should stay as transfers rather than bytes.

Yes, agreed.

@nickovs let me know if/when this is ready for final review and merge.

With #7650 merged I think that this now accurately reflects the code, so please go ahead with a review and merge.

Thanks for your efforts @nickovs, much appreciated!

However, is it possible to come up with a more tangible example? It'd be great to be able to point folks at, say, a Wokwi-hosted example that provided a concise, clear and compelling use case - the examples in the docs either execute practically immediately or are quite low-level and difficult to appreciate. Maybe something like a PIO/DMA solution to control a WS2812B...

@pi-mst If there is interest, I have exactly the the sample code requested: WS2812B run from DMA and PIO, which is running my Christmas light display. @nickovs If you want a block of the code to paste into your docs as an example, I can attach a simplified skeleton. It will take a little while to provide (few weeks before I get around to it), since right now my display is running off an older DMA interface

I guess the question is how much code do we want to include in the docs themselves? Most of the reference pages do not include a great deal of example code.

I've tried to keep the three examples here short enough that you can see what they are doing, without having a ton of code that is doing something other than the DMA functionality. As it stands there are more examples in here than in the page for rp2.PIO, which is rather more complex.

Most more complex examples will end up more being an example of, say, programming the PIO, rather than using DMA. I'd argue now that DMA is merged, it might be better to start using DMA in the examples elsewhere, rather than having examples for use of PIO, SPI and other devices in the DMA docs.

@nickovs The question about how much code is entirely valid. The other possibility, given the unusual nature of the PIO and DMA devices on the RP2, is to create a special examples section for the rp2 port. Maybe each port should have an examples section that show off specific features of that port. That way, the examples are maintained as good code, and the documentation would link to the appropriate examples section.

The other possibility, given the unusual nature of the PIO and DMA devices on the RP2, is to create a special examples section for the rp2 port

There is already an examples examples/rp2 directory with some examples for the rp2 port (using PIO), so I agree putting something there and referencing it from the docs would be the best outcome.

I think it would be OK to merge this now and add a more detailed DMA example later, though (maybe at the same time can remove the longer example from the .rst) - depending on Nick's schedule.

EDIT: Especially as I just noted this PR is approaching its third birthday later this year! 🙀

Now merged. Thanks @nickovs for writing this up, it's always hard doing the docs.