[rfc] proposed: new DMA interface

LeafLabs Garden » Support » Maple Hardware Support

[rfc] proposed: new DMA interface

(9 posts) (4 voices)

Started 3 years ago by mbolivar
Latest reply from rogerclark

mbolivar
LeafLabs

Update June 21 2012: This initial interface revamp was later changed -- see below

Hey all,

The DMA peripherals on STM32F2/F4 are incompatible with STM32F1. I came up with a new API that should roughly work with both, and I'd love some feedback on it before I take it any further, as it's a fairly radical departure from the past (don't worry, the old functions are still there on F1, so old code will continue to work on existing boards).

The patches are currently here, rebased on top of the current LeafLabs libmaple dev branch:

https://github.com/mbolivar/libmaple/tree/series-of-tubes/

The main commit which introduces the new API is here. What's new is (hopefully) thoroughly explained in the commit message and in comments that are part of the patch:

https://github.com/mbolivar/libmaple/commit/fba31701d9b16a15f0e7dde01622ef487db31a55

There are still some things that just aren't portable between F1 and F2/F4, but they're carefully segregated into what a dma_tube is, and the data structure (struct dma_tube_config) that's passed to a new DMA transfer setup function, dma_tube_cfg(). That way, you can keep parallel dma_tube_configs around, one for each series you need to support, so the same code will work with both kinds of DMA controller. (If you're lucky or are doing something simple, a single struct dma_tube_config will often suffice on both series.) dma_tube_cfg() is intended to replace dma_setup_xfer().

The portable, common interface is in libmaple/include/libmaple/dma.h (so it'll be included as <libmaple/dma.h>; this is part of a larger change we're introducing -- again, don't worry, you can still #include "dma.h" for now). It should feel very familiar to you; the only real difference is the configuration procedure described above. The nonportable bits live under libmaple/stm32f1 and libmaple/stm32f2. So F1 routines live in libmaple/stm32f1/dma.c, and the F1 series DMA header <series/dma.h> lives in libmaple/stm32f1/include/series/dma.h (the series headers are included by <libmaple/dma.h> to fill in the blanks on what the MCU series supports). Similarly for F2.

Please let me know what you think about the new API. I'd really, especially love feedback if you've got experience with STM32 series outside of F1, F2, F4. I really want to get this one right, so we don't have to keep changing the interface every time we want to add a new family of MCUs.

edit: fixed some typos in the commit message and force-pushed, updated link to relevant commit
edits 2/3: added some more information

Posted 3 years ago #
mbolivar
LeafLabs
Some more details (with edits):

The idea for how you write code that works on F1 and F2/F4 is basically like this (with SPI RX chosen as the basis for an example, though this isn't working code):

1. Pick a dma_dev* dma, along with dma_channel dma_ch to use on F1, and dma_stream dma_st on F2/F4.
2. Pick the dma_request_src that corresponds to the DMA request source you want (so e.g. DMA_REQ_SRC_SPI1_RX). (Most of the portability magic is in the bit encodings used for dma_request_src enumerator values).
3. Initialize a struct dma_tube_config like so:
```
dma_tube_config my_tube_cfg = {
    .tube_per_addr = &SPI1_BASE->DR,
    .tube_per_size = DMA_SIZE_8BITS,
    .tube_mem_addr = address_of_your_buffer,
    .tube_mem_size = DMA_SIZE_8BITS,
    .tube_nr_xfers = sizeof(your_buffer),
    .tube_mode = DMA_MINC_MODE | DMA_TRNS_ERR | DMA_TRNS_CMPLT | etc.,
    .tube_req_src = DMA_REQ_SRC_SPI1_RX,
    .series_data = 0,
};
```
4. Use conditional compilation, extern, etc. so that dma_tube tube is dma_ch on F1 targets, and dma_st on F2/F4 targets.

5. Call dma_tube_cfg(dma, tube, &my_tube_cfg), perform any other desired configuration as usual, then call dma_enable(dev, tube) to start things off. (You of course also have to configure SPI1 to enable DMA RX requests, etc.)
Posted 3 years ago #
mbolivar
LeafLabs

In hopes that working code will drive some feedback, I've pushed some updates/fixes to the aforementioned branch to get things working on Maple. I've also updated examples/test-usart-dma.cpp to use the new API. Here's the patch; as you can see, the changes are pretty straightforward:

https://github.com/mbolivar/libmaple/commit/25863c25761690631bfe30ffc0b6cd65f69378ad

I've left line comments for that commit on GitHub which explain the rationale behind the changes in detail; click the above link to read them.

Posted 3 years ago #
mbolivar
LeafLabs

Another update to test-usart-dma.cpp (he said to himself):

https://github.com/mbolivar/libmaple/commit/6a719a860d69a8ee24c491a21232db10fcc42d8e

This illustrates another improvement that dma_tube_cfg() has over dma_setup_xfer(): dma_tube_cfg() detects when the configuration you specify is impossible to satisfy, and returns an error code (or just DMA_TUBE_CFG_SUCCESS (=0) if everything worked).

This lets you check that you did things correctly. There have been a few threads on this forum that went something like this:

"This DMA code doesn't work!"
"You didn't pick the right channel."
"Oh, thanks."

The new function tries harder to explain what went wrong. Existing error codes:

- DMA_TUBE_CFG_ECOMPAT: tube is incompatible with configuration (covers the "wrong channel" error)
- DMA_TUBE_CFG_ENDATA: memory and peripheral sizes are incompatible with number of data to transfer (the new DMA controllers have stricter alignment requirements, so detecting this error is going to help you port from F1 in some cases)

Posted 3 years ago #
robodude666
Member

*cough* Using a struct to hold config data? I think that was proposed before. *cough*

Liking the changes I'm seeing so far. dma_tube_config makes it really easy to pass different configurations so you can repurpose a DMA controller between SPI/ADC/USART, etc. functions in your program.

Asserts are always enabled, or is there a way to disable them? I don't remember entirely, but do asserts on Maple cause the LED to blink or do they output a msg to a debug usart... or both?

-robodude666

Posted 3 years ago #
ThomasB
Member

@mbolivar
Looks like good work :)
Can't say more at the moment, because I've no time to test/work with it.
So this post is only intended to say: You're not speaking with yourself ;)
(and.. there are people out there who appreciate what you're doing)

Posted 3 years ago #
mbolivar
LeafLabs

robodude666, ThomasB: Thanks for the feedback :). It does make me feel better to see that I'm not plunging ahead into the future without checking in with you all first.

Since last post, I re-did things into a much simpler interface. You no longer have to specify the memory and peripheral addresses in a struct dma_tube_config. Just specify the source and destination addresses, and the library figures out which registers everything should live in. This also means you no longer need to think about MEM2MEM or FROM_MEM type flags; those get figured out for you.

Here are some relevant commits, which have been pushed into the LeafLabs libmaple development branch. This is definitely not final yet, so any comments welcome.

This introduces the new API:
https://github.com/leaflabs/libmaple/commit/2026ef2c36b83521786da6ff711150fb8289d673

Here's the working version of struct dma_tube_config and dma_tube_cfg():
https://github.com/leaflabs/libmaple/blob/2026ef2c36b83521786da6ff711150fb8289d673/libmaple/include/libmaple/dma.h#L121

Notice the additional error codes. There are a TON of gotchas when porting DMA code from STM32F1 to F2 and F4 targets (notably: only DMA2 does mem-to-mem, you must configure the new FIFO feature when PSIZE!=MSIZE). I tried to catch as many of them as I could, so you get a sensible error value instead of things just crashing.

This commit ports the USART example to use the new API:
https://github.com/leaflabs/libmaple/commit/8c718082124d7b7b95ffe4591a3b58f3f4601c85

This is the function used to set up the struct dma_tube_config:
https://github.com/leaflabs/libmaple/blob/8c718082124d7b7b95ffe4591a3b58f3f4601c85/examples/test-usart-dma.cpp#L80

(It uses a new HardwareSerial feature that gets the underlying usart_dev).

I think the result is a pretty nice interface. It could use a lot more testing, though, so if anyone wants to try it out, I'd be grateful.

robodude666:

*cough* Using a struct to hold config data? I think that was proposed before. *cough*

Yes, I smiled and thought of you when I decided to go that route. Hopefully you'll agree that the latest incarnation of the configuration struct does manage to be a little nicer than the ST libraries' take on the situation.

Liking the changes I'm seeing so far. dma_tube_config makes it really easy to pass different configurations so you can repurpose a DMA controller between SPI/ADC/USART, etc. functions in your program.

Cool, glad it seems useful.

Asserts are always enabled, or is there a way to disable them? I don't remember entirely, but do asserts on Maple cause the LED to blink or do they output a msg to a debug usart... or both?

See http://leaflabs.com/docs/lang/api/assert.html

If you want to disable asserts globally, you can add -DDEBUG_LEVEL=DEBUG_NONE to your CFLAGS. Command-line only, of course. I've been thinking about a clean way to mix Make into the IDE for a while now (where by "clean", I mean "invisible unless you specifically look for it", so as not to confuse beginners), but haven't come up with anything convincing yet.

Posted 3 years ago #
mbolivar
LeafLabs

By the way, the USART example does work on STM32F2. These were the only changes required:

https://github.com/leaflabs/libmaple/commit/e0a2e9a5ce60e348cbff88069c5063a2e34f79e6

With that patch, the same program works on F1 and F2 :).

Posted 3 years ago #
rogerclark
Member

Does anyone have any examples of how to use the new Tube based dma to write to a peripheral ?

Its unclear whether the older dma stuff still works, i.e the stuff listed as __deprecated

Posted 10 months ago #

RSS feed for this topic

Reply

You must log in to post.