DMA API Proposal for TinyGo

[soypat]

Background

TinyGo has long had non-standard DMA APIs for interacting with peripherals on MCUs. One example which has received attention recently is the implementation on the PIO library here:

• Implementation: piolib DMA
• Community asking for public DMA API: Suggestion about DMA interface pio#16
• Community designing amazing things with their own DMA API and completely flabbergasting me with what is possible with TinyGo: go-wspr

Due to these current events I have begun researching DMA APIs by asking my coworkers about DMA (many thanks to @ydnatag) and finding out interesting things about Linux's DMA API which is documented here:

• DMA engine Provider API documentation: https://github.com/torvalds/linux/blob/master/Documentation/driver-api/dmaengine/provider.rst
• DMA engine Client API documentation: https://github.com/torvalds/linux/blob/master/Documentation/driver-api/dmaengine/client.rst
• DMA engine implementation: https://github.com/torvalds/linux/blob/7f2ff7b6261742ed52aa973ccdf99151b7cc3a50/drivers/dma/dmaengine.c
• DMA driver implementation for STM32: https://github.com/torvalds/linux/blob/7f2ff7b6261742ed52aa973ccdf99151b7cc3a50/drivers/dma/stm32/stm32-dma.c

Proposal details

While having a DMA engine like Linux's would be useful I believe it is too early to work our way into something of the sort. I'd argue we can eventually get there (if we really want that) by building a common low level DMA channel API that is shared in part by Linux's DMA Engine. A couple things about the API:

• I believe DMAChannel start-transaction call should be asynchronous. After all we are abstracting the hardware, which is fundamentally and undeniably async. As much as I try to avoid async APIs I believe it is beneficial in this case to do go this way as that is the way the hardware works. Try to sidestep that and you'll eventually run into issues with whatever novel way you chose to represent something that is async as non-async.
• We should have a central structure which holds data on DMA channels in use to facilitate users not stepping on drivers, much like how linux does it with dma_request_channel. This is how piolib also does it and it seems to have worked for our users. Below is an API for a lightweight DMAArbiter implementation much like the one in piolib.
• Scatter-gather operations are very useful but might be too much to concentrate into the same API as a single buffer DMA transaction, which is why I've excluded it from this API for now. I'd imagine they probably might end up having their own DMAScatterGatherConfig type and corresponding function call
• I've chosen not to do DMA transaction in two steps: Configuration+Start. Not married to the current proposal below but I do like the simplicity of a single call which sort of implies consistent behaviour between calls since we are always configuring the transaction.

Proposed DMA Channel API

type DMATxConfig struct {
        // Allow DMA to be chained to another transaction in a different channel
	ChainTo          int
        // Size of data to be moved by transaction in bytes.
	TxSize           int
        // Pointer to start of source of data.
	Src              unsafe.Pointer
        // Pointer to start of the destination of data where data will be moved to.
	Dst              unsafe.Pointer
        // Width of data to be moved from source in bytes. If increment is enabled this will be the value added to the source address on every unit of data moved on the bus.
	SrcAddrWidth     uint8
        // Width of data at destination. If increment is enabled this value is added to the destination address on every unit of data moved on the bus.
	DstAddrWidth     uint8
       // Enable increment of source address. If false the data will be pulled from a single address which is useful for peripheral register interaction.
	SrcAddrIncrement bool
       // Enable increment of destination address. If both Src and Dst are incremented then DMA is effectively a memcopy.
	DstAddrIncrement bool
}

// StartTx begins a DMA transaction over the bus and returns immediately (non-blocking). 
// Use [DMAChannel.IsBusy] to know if the transaction terminated.
func (ch *DMAChannel) StartTx(cfg *DMATxConfig) error {
	return nil
}

// IsBusy returns true if the channel is currently performing a transaction over the bus.
func (ch *DMAChannel) IsBusy() bool {
	return false
}

// Abort terminates the DMA transaction early. 
// It should be called after a transaction finishes to disable the channel to save power.
func (ch *DMAChannel) Abort() {
}

// ChannelIndex returns the identifying index of this DMA channel.
func (ch *DMAChannel) ChannelIndex() int {
	return 0
}

Proposed DMA channel Arbiter API

type DMAArbiter struct {
	used   uint64 // bitmask of used DMA channels.
	nchans int
}

type DMAChannel struct {
	nchan int
}

var mdma = DMAArbiter{}

func (arb *DMAArbiter) RequestChannel() (*DMAChannel, error) {
	for i := 0; i < arb.nchans; i++ {
		bit := uint64(1 << i)
		if arb.used&bit == 0 {
			arb.used |= bit
			return &DMAChannel{}, nil
		}
	}
	return nil, errors.New("no free channels")
}

func (arb *DMAArbiter) ReleaseChannel(ch *DMAChannel) error {
	if ch.nchan >= arb.nchans {
		return errors.New("invalid channel number")
	}
	bit := uint64(1 << ch.nchan)
	if arb.used&bit == 0 {
		return errors.New("channel not claimed")
	}
	arb.used &^= bit
	return nil
}

@tdunning @aykevl @deadprogram

[eliasnaur]

Thanks for working on this. A central registry for reserving DMA channels is a good idea to allow disparate drivers to work together. However, I worry that a useful DMA abstraction isn't worth the complexity. For example, your proposed API doesn't cover

• Peripheral pacing (DREQ)
• Interrupts for DMA completion, halfway completed etc.
• Chaining by control blocks (perhaps a rp2-specific feature?)
• Quirks (read data must equal write data size on rp2, address decrement, increment 2 etc.)

In particular, your go-wspr example doesn't seem to fit your API because it uses control block chaining of DMA channels. Even if the API was sufficient, go-wspr is already platform-specific (because of pio) so won't gain much from a generic DMA API.

I propose adding just the central channel registry and add efficient bulk transfer API to each device (I2C, UART etc.) and driver, backed by the platform's DMA. That's a smaller API, and can serve as inspiration for a generic DMA abstraction later on.

I believe DMAChannel start-transaction call should be asynchronous. After all we are abstracting the hardware, which is fundamentally and undeniably async. As much as I try to avoid async APIs I believe it is beneficial in this case to do go this way as that is the way the hardware works. Try to sidestep that and you'll eventually run into issues with whatever novel way you chose to represent something that is async as non-async.

I'm not convinced by this argument. Goroutines are supposed to be lightweight enough that APIs can block and let the caller decide whether to introduce concurrency through extra goroutines and channel. With an async API you need a way to expose interrupt-based waiting, otherwise the IsBusy+Gosched loop probably (much of) eats the efficiency gains of using DMA in the first place.
Another key advantage to a synchronous bulk transfer API is that the ownership of the passed in buffers is clear: for the duration of the call, writing to the buffers is a race.
Finally, just as Big Go, I also don't like API that assumes a non-moving GC, and a synchronous bulk transfer API can use runtime.Pinner to tell a (hypthetical) moving GC not to move buffers during DMA. We're even more likely to eventually want a compacting/moving GC than Big Go, because fragmentation is a much bigger problem in memory constrained environments.

[eliasnaur]

I thought a bit more about our difference in opinion, and realized that I do agree with you that the DMA abstraction (if any) should probably be async. I still think the user-facing API should be sync[0], but drivers that interact directly with DMA probably don't want to waste efficiency on additional goroutines, channels etc.

In other words, I had the perspective of user code, whereas you probably had the perspective of a driver.

[0] In the form of bulk transfer API on devices, and perhaps a DMA-aware memory-to-memory implementation of copy and other bulk memory transfers.

[tdunning]

It sounds like @eliasnaur is saying that primitives like copy(mem, mem) should be sync. That's probably true whether or not they are supported by DMA. I think that is what he means by "user-level"

I strongly agree, however, with the idea that when it comes to manipulating the DNA for serious low-level work, you have to be able to start the transaction and then immediately work on something else.

[aykevl]

Goroutines are supposed to be lightweight enough that APIs can block and let the caller decide whether to introduce concurrency through extra goroutines and channel.

On desktop systems, sure. But not on embedded systems. Goroutines have a quite significant overhead, and are difficult to optimize further.

We're even more likely to eventually want a compacting/moving GC than Big Go, because fragmentation is a much bigger problem in memory constrained environments.

As I argued in #4909, we're unlikely to ever have a moving GC. I won't repeat the arguments here, but in short: it's not feasible without a radical redesign of TinyGo.

I mostly want a public DMA API so users can tinker with the DMA API to make peripheral transactions better (SPI/UART/I2C) before it is properly implemented in TinyGo.

Wait - but the eventual goal would be to make the usual SPI/UART/I2C peripherals support DMA internally, right? We could make an abstract API now, but if it's only going to be used for platform-specific code (custom implementations of SPI etc), then I don't see why we aren't designing good DMA APIs for these serial peripherals directly?

[soypat]

I'd argue yeah, we prefer SPI/UART/I2C to support DMA internally i.e the way the piolib library works where every driver has a "EnableDMA" method that easily activates DMA function if the user so wishes. Worth noting these APIs would still be synchronous but yield during the DMA transaction. Users still expect the SPI API to be synchronous, with or without DMA

[aykevl]

Worth noting these APIs would still be synchronous but yield during the DMA transaction.

Do you mean they block and let other goroutines run? Then, I wonder, why isn't DMA the default if it conceptually does the same thing?
(Also, can you point me to the docs/code so I can better understand how this library works?)

[tdunning]

It may be that it is out of scope to have three levels of control block chaining as in go-wspr, but it does seem worthwhile exposing enough power to implement a ping-pong buffering scheme.

The pacing is also pretty important. Not sure how easy that is to abstract.

In the meantime, even go-wspr would have benefited from an arbiter. The structures returned could well have supported some simple copy operations, but I would still want a pointer to the underlying registers in that structure somehow. The arbiter I used was copied pretty much verbatim from the PIO library.

So should that be the first step?

[tdunning]

Regarding a more advanced API, I can definitely see the difficulty in generalizing the special purpose capabilities of platforms like the Pico but aside from fast memory to memory copies, I don't see much way to make use of DMA without at least pacing and progress indicators and probably some kind of completion indicator. The completion indicator is pretty easy to made idiomatic if we just provide a channel that closes when the operation completes or a callback, but I don't see any way to handle the more advanced capabilities since they so often depend on using DMA to transfer control blocks.

[aykevl]

How do you fit the nRF52xxx etc DMA API in this proposal? They do not have a central DMA peripheral, instead every peripheral has some registers where you can set the buffer start, buffer size, etc. I don't see how the proposed API could work for those chips.

[tdunning]

It isn't quite clear which parts of the proposed API you are addressing. Let's fork the discussion a bit into two parts, one for the DMA device allocator functionality and one for the fancy sugar on top of the control of DMA devices themselves.

Fork 1 - DMA arbiter

I don't think that it makes sense to have an allocator for DMA devices if you don't have DMA devices. For sure. Where you do have multiple general-ish purpose DMA devices, however, it makes total sense to allocate them even if the user never quite realizes that DMA is in use because it's use is hidden in a driver.

But isn't that true of other aspects of the runtime code? If you don't have the hardware, you can't really support it.

The converse is also true. For systems where DMA is built into each device, it really does make sense that the use of DMA is built into the drive implementation itself. Whether this is done using async I/O or a go-routine sort of system doesn't change that basic point.

Fork 2 - DMA API on top of DMA devices

For my own idiosyncratic use, the presence of specialized DMA devices is an opportunity to do interesting things beyond just transferring data from a peripheral. In past work, I extended the ability to get time-stamped counts from an arbitrary (aka 48 or 64 bits) counter controlled by an external signal with jitter of only a few clock cycles. In current work, I am working on getting time-stamped buffers of ADC samples. Both of these are different from what an integrated DMA capability would be good for. Both are very different from the async APIs for devices that @aykevl has proposed. The core difference is the use of DMA to transfer from multiple sources in a single virtual operation. In one case, those sources were the hardware system clock registers and various PWM counters. In the second case, those sources are the hardware clock and the ADC converter. In other cases, it might be a system clock, some external pins, and the ADC combined.

The thread here is that these oddball applications are only useful on a system with fairly general DMA hardware. If you don't have that, then you are solving a different problem. In any case, the only general capability that is helpful for these hybrid situations is the DMA device allocator.

Synthesis

None of these considerations really bear on the question of whether particular device drivers should support DMA like autonomous transfers or whether a slightly generalized DMA API for independent DMA devices. The only place of intersection seems to me to be at the level of the allocator and it seems that there is good potential for consensus here.

That potential consensus would be that for systems with independent DMA devices, having a system-wide allocator for these devices is a good idea. For support of this, in the universe with a general-ish purpose DMA API, an allocator is very important. For the world where device drivers perform DMA operations for users, if this is done with general DMA devices, an allocator is crucial to hide the use of DMA from callers. In my universe where stupid pet tricks with DMA are the goal, having an allocator lets me co-exist with these other universes without surprises.

[soypat]

Sounds like the nrf DMA is per-peripheral. This API aims at a more general DMA hardware like the rp2040 DMA and bigger CPU DMAs (linux style). It seems to me it would be enough to add EnableDMA methods to the nrf hardwares to enable DMA usage, much like the piolib implementations do.

[aykevl]

For nrf the hardware actually maps really nicely to the StartTx and Wait methods, which make SPI etc async. Most peripherals don't even support non-DMA usage so "enabling DMA" doesn't make sense - it's always used. The only thing is that Tx will just block until the transfer is finished - so splitting it into StartTx and Wait to make it async is very natural.

[aykevl]

Here is a different API, that I've implemented for two different chips and have made to work with a driver (st7789) and shown to actually work in the real world. (The code is old now, I'd need to rebase it quite a bit to make work again): #3985

Why do we need such a complex API when a simple StartTx and Wait should be good enough for most cases? Also, the API I have proposed above actually works, I've tested it on the Gopher Badge and saw a significant increase in performance (very close to the maximum possible performance). Also, bonus: it can work on nRF52xxx chips which this proposal does not.

[aykevl]

Ok, so, after some thought, if PIO is going to stay outside the machine package and it needs to allocate DMA channels, it does make sense to create a dedicated API for that. I would still like to see some examples of how it's going to be used and see that it's the most minimal API that covers all uses and is generic enough that it works for multiple chips.

[tdunning]

The point that some chips don't have general purpose DMA channels is an argument that those chips can't support an uniform and symmetric allocator of DMA channels. This observation obviously applies to chips that have completely dedicated DMA channels. It applies with less certainty to chips that have sort of generic DMA channels but do not allow them to function symmetrically. It may be that there could be a filter argument that could be used to define a kinda-sorta-symmetric allocator, but it is certainly easier to say that concept of a symmetric allocator of generic devices doesn't apply in those situations.

So I agree with the basis of your argument. It comes down to the idea that not all concepts apply to all chips. The same thing is true of ADCs (not all chips have them) or PWMs (not all chips have them) or PIOs (some have them, many do not) and many other capabilities. Not all chips have all functions.

So I don't agree that the capabilities of the basic libraries must apply equally on all platforms. We have to deal with non-uniformity as well as possible. Weird stuff will still crop up such as the fact that on the RP2040 and the RP2350, each PWM controller controls two pins that can differ in duty cycle but not frequency.

We have two boundary cases already (can't do generic DMA versus all DMA devices are equipotent). We have middle ground cases as well as you have pointed out which are a bit difficult to define. So we can already define a library which works with the symmetric chips and fails (with a nice error message explaining that you can't ask for a miraculous DMA device that doesn't exist).

I think that my own experience says that having a DMA allocator is a useful thing because more than one library will need DMA devices.

Your arguments don't negate that. All they do is provide nuance and details to the accepted fact that not all chips will be able to support this. That nuance and detail is great, but it doesn't undercut the need for the allocator; it just helps define where it can work and where and how it might fail.

[soypat]

I'm not a fan of splitting up the interfaces we all know and love in TinyGo i.e: having SPI and SPIAsync. I'd much rather follow the path of piolib and simply havea "EnableDMA" method that turns DMA on or off for an interface. I feel this is the simplest solution for users and driver developers. Ideally we'd want to have one way of developing drivers that use SPI, UART etc. No need to define interfaces for every hardware enabled acceleration we add, Tx by itself gets the job done and can leverage DMA just fine.

[aykevl]

It may be that there could be a filter argument that could be used to define a kinda-sorta-symmetric allocator, but it is certainly easier to say that concept of a symmetric allocator of generic devices doesn't apply in those situations.

Yeah I was thinking of filtering in some way. There are multiple ways to implement that. One could be by passing the instance (machihne.UART0, machine.SPI1, etc) as a parameter to RequestChannel. But, yeah, not sure it's worth the hassle and we should just define static DMA channels for stm32 chips.

Weird stuff will still crop up such as the fact that on the RP2040 and the RP2350, each PWM controller controls two pins that can differ in duty cycle but not frequency.

(Off topic, but: this is true for all PWMs I've looked at. There is one timer, and that one timer controls multiple pins with different duty cycles. Usually it's 2 or 4 pins. I think it's mostly the Arduino environment that's to blame for the idea that pins can have individually controllable PWMs because even those AVRs don't have one pin per PWM/timer instance. Also see: https://tinygo.org/tour/pwm/multiple/).

[aykevl]

@soypat

No need to define interfaces for every hardware enabled acceleration we add, Tx by itself gets the job done and can leverage DMA just fine.

As I've argued at length in #3985 (comment), making Tx use DMA (which it already does in many cases today!) does not solve the problem I had with rendering graphics efficiently. The driver would start a short transaction, which blocks, causes a context switch to the rendering goroutine, but the rendering goroutine won't yield to the driver goroutine again to start the bulk transfer which causes the SPI peripheral to sit idle while a buffer is rendered. For efficient graphics, both the rendering and the SPI transfer need to happen at the same time as much as possible.

I realized now I write this, if Tx itself becomes a blocking operation (with context switch) my StartTx/Wait proposal also falls apart since the setWindow call in the ST7789 driver will also cause such a context switch. Perhaps we really do need some way to run some code at a higher priority, though implementing that will be challenging.

[soypat]

If we do end up going the StartTx / Wait way- what do people think about adding a machine.SPIDMA type with these methods that is returned on machine.SPI.UseDMA() *machine.SPIDMA method signature. This will help :

• API ergonomics: prevents user error on passing a machine.SPI that has not been configured with DMA to a driver that expects DMA semantics
• Binary Size: Completely segment DMA logic from typical machine.SPI implementation, thus reducing binary size
• Implementation readability: segmenting logic also aids developers read the code.
• Avoid API bloat: avoid storing conflicting in-band information in machine.SPIConfig by having machine.SPIDMAConfig