DMA based API proposal

[japaric]

In this issue I'm going to present the DMA API I have implemented for the blue-pill and that I have used in my recent robotic application with the goal of using it to start a discussion about DMA based API.

Pre-requisites

You should understand how RefCell works and how it achieves dynamic borrowing.

Detailed design

Core idea

The DMA peripheral behaves like an "external mutator". I like to think of it as an independent processor / core / thread that can mutate / access data in parallel to the main processor. From that POV a DMA transfer looks like a fork-join operation like the ones you can do in std-land with threads.

With that mindset: in a DMA transfer you want to hand out "ownership" of the data / buffer from the processor to the DMA for the span of the transfer and then claim it back when the transfer finishes. Except that "ownership" in the full sense ("the owner is in charge of calling the destructor when the value is no longer needed") is not applicable here because the DMA can't destroy the buffer is using for the transfer. So instead of ownership what the proposed API will transfer is temporary read or write access to the data.

Read or write access sounds like &- and &mut- references but the proposed API won't use those. Instead it will use buffers with RefCell-style dynamic borrowing.

Buffer

The main component of the proposed API is the Buffer abstraction:

struct Buffer<B, CHANNEL> {
    _marker: PhantomData<CHANNEL>,
    data: B,
    flag: Cell<BorrowFlag>, // exactly like `RefCell`'s
    status: Cell<Status>, // "Lock status"
}

enum Status {
    Unlocked,
    Locked,
    MutLocked,
}

The data and flag fields effectively form a RefCell<B>. Although not explicitly bounded B can only be an array of bytes ([u8; N]). The CHANNEL type parameter indicates which DMA channel this buffer can work with; possible values are phantom types like Dma1Channel1, Dma1Channel2, etc. Finally the status field indicates if the DMA is currently in possession of the buffer.

impl<B, CHANNEL> Buffer<B, CHANNEL> {
    pub fn borrow(&self) -> Ref<'a, B> { .. }
    pub fn borrow_mut(&self) -> RefMut<'a, B> { .. }

    fn lock(&self) -> &B { .. }
    fn lock_mut(&self) -> &mut B { .. }
    unsafe unlock(&self) { .. }
    unsafe unlock_mut(&self) { .. }
}

Buffer exposes public borrow and borrow_mut methods that behave exactly like the ones RefCell has. Buffer also exposes private locks and unlocks methods that are meant to be used only to implement DMA based APIs.

The lock and unlock pair behaves like a split borrow operation. A borrow call will check that no mutable references exist and then hand out a shared reference to data wrapped in a Ref type while increasing the Buffer shared reference counter by one. When that Ref value goes out of scope (it's destroyed) the Buffer shared reference counter goes down by one. A lock call does the first part: it checks for mutable references, increases the counter and hands out a shared reference to the data. However the return type is a plain shared reference &T so when that value goes out of scope the shared reference counter won't be decremented. To decrement that counter unlock must be called. Likewise the lock_mut and unlock_mut pair behaves like a split borrow_mut operation.

You can see why it's called lock and unlock: once locked the Buffer can't no longer hand out mutable references (borrow_mut) to its inner data until it gets unlocked. Similarly once a Buffer has been lock_muted it can't hand out any reference to its inner data until it gets unlock_muted.

DMA based API

Now let's see how to build a DMA based API using the Buffer abstraction. As an example we'll build a Serial.write_all method that asynchronously serializes a buffer using a DMA transfer.

impl Serial {
    pub fn write_all<'a>(
        &self,
        buffer: Ref<'a, Buffer<B, Dma1Channel4>>,
    ) -> Result<(), Error>
    where
        B: AsRef<[u8]>,
    {
        let usart1 = self.0;
        let dma1 = self.1;

        // There's a transfer in progress
        if dma1.ccr4.read().en().bit_is_set() {
            return Err(Error::InUse)
        }

        let buffer: &[u8] = buffer.lock().as_ref();

        // number of bytes to write
        dma1.cndtr4.write(|w| w.ndt().bits(buffer.len() as u16));
        // from address
        dma1.cmar4.write(|w| w.bits(buffer.as_ptr() as u32));
        // to address
        dma1.cpar4.write(|w| w.bits(&usart1.dr as *const _ as u32));

        // start transfer
        dma1.ccr4.modify(|_, w| w.en().set());

        Ok(())
    }
}

Aside from the Ref in the function signature, which is not a cell::Ref (it's a static_ref::Ref), this should look fairly straightforward. For now read Ref<'a, T> as &'a T; they are semantically equivalent. I'll cover what the Ref newtype is for in the next section.

Let's see how to use this method:

static BUFFER: Mutex<Buffer<[u8; 14], Dma1Channel4>> =
    Mutex::new(Buffer::new([0; 14]));

let buffer = BUFFER.lock();

// mutable access
buffer.borrow_mut().copy_from_slice("Hello, world!\n");

serial.write_all(buffer).unwrap();

// immutable access
let n = buffer.borrow().len(); // OK

// mutable access
// let would_panic = &mut buffer.borrow_mut()[0];

At this point the transfer is ongoing and we can't mutably access the buffer while the transfer is in progress. How do we get the buffer back from the DMA?

impl<B> Buffer<B, Dma1Channel4> {
    /// Waits until the DMA transfer finishes and releases the buffer
    pub fn release(&self) -> nb::Result<(), Error> {
        let status = self.status.get();

        // buffer already unlocked: no-op
        if status == Status::Unlocked {
            return Ok(());
        }

        if dma1.isr.read().teif4().is_set() {
            return Err(nb::Error::Other(Error::Transfer))
        } else if dma1.isr.read().tcif4().is_set() {
            if status == Status::Locked {
                unsafe { self.unlock() }
            } else if status == Status::MutLocked {
                unsafe { self.unlock_mut() }
            }

            // clear flag
            dma1.ifcr.write(|w| w.ctcif5().set());
        } else {
            // transfer not over
            Err(nb::Error::WouldBlock)
        }
    }
}

The Buffer.release is a potentially blocking operation that checks if the DMA transfer is over and unlocks the Buffer if it is. Note that the above implementation is specifically for CHANNEL == Dma1Channel4. Other similar implementations can cover the other DMA channels.

Continuing the example:

serial.write_all(buffer).unwrap();

// immutable access
let n = buffer.borrow().len(); // OK

// .. do stuff ..

// wait for the transfer to finish
block!(buffer.release()).unwrap();

// can mutably access the buffer again
buffer.borrow_mut()[12] = b'?';

serial.write_all(buffer).unwrap();

Alternatively, using callbacks / tasks:

fn tx() {
    // ..

    SERIAL.write_all(BUFFER.lock()).unwrap();

    // ..
}

// DMA1_CHANNEL4 callback
fn transfer_done() {
    BUFFER.lock().release().unwrap();
}

static_ref::Ref

The Ref<'a, T> abstraction is a newtype over &'a T that encodes the invariant that the T to which the Ref is pointing to is actually stored in a static variable and thus can't never be deallocated.

The reason Ref is used instead of just &- in the write_all method is to prevent using stack allocated Buffers with that method. Stack allocated Buffers are rather dangerous as there's no mechanism to prevent them from being deallocated. See below what can happen if a Serial.read_exact method used &- instead of Ref:

fn main() {
    foo();
    bar();
}

#[inline(never)]
fn foo() {
    let buffer = Buffer::new([0; 256]);

    SERIAL.read_exact(&buffer);

    // returns, DMA transfer may not have finished, `buffer` is
    // destroyed / deallocated
}

#[inline(never)]
fn bar() {
    // DMA transfer ongoing; these *immutable* values allocated on the stack
    // will get written to by the DMA
    let x = 0u32;
    let y = 0u32;

    // ..
}

Unresolved questions

• Is there an equally flexible (note that with this approach the DMA transfer start and finish operations can live in different tasks / interrupts / contexts) alternative that involves no runtime checks?

• Should we extend this to also work with Buffers allocated on the stack? My first idea to allow that was to add a "drop bomb" to Buffer. As in the destructor will panic if there's an outstanding lock. See below. (But this probably a bad idea since panicking destructor is equal to abort (?))

{
    let buffer = Buffer::new(..);
    buffer.lock();
    // panic!s
}

{
    let buffer = Buffer::new(..);
    buffer.lock();
    unsafe { buffer.lock() }
    // OK
}

{
    let buffer = Buffer::new(..);
    let x = buffer.borrow();
    // OK
}

Do note that an unsafe Ref::new exists so you can create a Buffer on the stack and wrap a reference to it in a Ref value. This will be like asserting that the buffer will never get deallocated. Of course it's up to you to ensure that's actually the case.

• In the blue-pill implementation Buffer is defined in the blue-pill crate itself but to turn DMA based APIs into traits we would have to move that Buffer abstraction into the embedded-hal crate. That complicates things because (a) lock et al. would have to become public and (b) e.g. Dma1Channel1 wants to be defined in the stm32f103xx-hal-impl crate but that means one can't write impl Buffer<B, Dma1Channel1> due to coherence. I have no idea how to sort out these implementation details.

• This API doesn't support using a single Buffer with more than one DMA channel (neither serially or concurrently). Is that something we want to support?

• Since we have the chance: should we reduce the size of the flag field? The core implementation uses flag: usize but 4294967295 simultaneous cell::Ref sounds like a very unlikely scenario in a microcontroller.

[japaric]

cc @whitequark @adamgreig @vitiral @Kixunil

[japaric]

Read or write access sounds like &- and &mut- references but the proposed API
won't use those.

To elaborate why it doesn't: I think plain references are not enough for memory
safety. Let me reimplement Serial.write_all using references and #[async]
(you can translate this to futures by writing more boilerplate)

impl Serial {
    // this is a mixture of the original Serial.write_all and Buffer.release
    #[async]
    fn write_all(&self, buffer: &[u8]) -> Result<(), Error> {
        let usart1 = self.0;
        let dma1 = self.1;

        // There's a transfer in progress
        if dma1.ccr4.read().en().bit_is_set() {
            return Err(Error::InUse)
        }

        let buffer: &[u8] = buffer.lock().as_ref();

        // number of bytes to write
        dma1.cndtr4.write(|w| w.ndt().bits(buffer.len() as u16));
        // from address
        dma1.cmar4.write(|w| w.bits(buffer.as_ptr() as u32));
        // to address
        dma1.cpar4.write(|w| w.bits(&usart1.dr as *const _ as u32));

        // start transfer
        dma1.ccr4.modify(|_, w| w.en().set());

        loop {
            if dma1.isr.read().teif4().is_set() {
                return Err(Error::Transfer)
            } else if dma1.isr.read().tcif4().is_set() {
                if status == Status::Locked {
                    unsafe { self.unlock() }
                } else if status == Status::MutLocked {
                    unsafe { self.unlock_mut() }
                }

                // clear flag
                dma1.ifcr.write(|w| w.ctcif5().set());

                return Ok(())
            } else {
                // transfer not over
                yield
            }
        }
    }
}

Here's an example of using the above API to cause memory unsafety without using
the unsafe keyword.

fn main() {
    foo();
    bar();
}

fn foo() {
    let mut buffer = [0; 256];

    let gen =  SERIAL.read_exact(&mut buffer);

    // the right thing to do is: drive the transfer to completion
    // loop { gen.resume() }

    // but nothing forces me to do that so I can return here
    // deallocating `buffer` while the DMA transfer is ongoing
}

fn bar() {
    // the DMA transfer continues and corrupts this stack frame
    let x = 0u32;
    let y = 0u32;
}

[vitiral]

I might be missing something, but what is the point of the lock* methods? They seem like a really unsafe API (if you forget to unlock you have deadlock!).

Conversely, the Buffer -> Ref api looks pretty much exactly like a Mutex -> MutexGuard to me except that you can have multiple Refs. Can you explain the differences? I'm wondering if having multiple Refs is really valuable for us.

[adamgreig]

Overall this seems really nice though I'd strongly prefer just &/&mut if we can find a way to make it work. It would be easier to use and very flexible. Opportunity for accidental memory unsafety seems very high.

Although not explicitly bounded B can only be an array of bytes ([u8; N]).

Why? A lot of the time (SPI, ADC, DAC, etc) the DMA transfers u16 or u32, and ndtr refers to the number of items to transfer rather than the number of bytes.

Should we extend this to also work with Buffers allocated on the stack?

I think this is less common than static buffers but not entirely uncommon; you might well want to allocate something on the stack because you're only going to need it inside this scope, but then still want to use it with DMA before you're done with this function. I think this is much more true of multithreading where you have a stack for each thread/coroutine and so the buffer would live in that thread's stack. On a separate note, what about heap allocated Buffers for systems using dynamic allocation?

I think plain references are not enough for memory safety.

I'm aware "you can't rely on Drop happening" but I wonder if we could have the DMA stop the stream on drop, and then you could perhaps allow &/&mut directly?

This API doesn't support using a single Buffer with more than one DMA channel (neither serially or concurrently).

I've never needed to, but consider most DMA peripherals treat TX and RX as separate streams: you might well want to DMA from a UART, modify the data somehow, then DMA it back out. Or DMA from an ADC, modify the buffer in-place, then replay it out the DAC. That would all require using the Buffer in different channels serially. Streaming the same data out of two independent DACs would require concurrent access (though on the STM32 specifically this isn't an issue as you can use the DACs together by writing a single register). It would be a shame for this use case to be totally impossible...

In the blue-pill implementation Buffer is defined in the blue-pill crate itself but to turn DMA based APIs into traits we would have to move that Buffer abstraction into the embedded-hal crate.

Can we have a DMAChannel trait in embedded-hal and then devices implement this against their specific DMA peripherals, for each channel?

[japaric]

@vitiral

I might be missing something, but what is the point of the lock* methods?

They are implementation details (non user facing APIs) used to implement the safe user facing API (Serial.write_all / Buffer.release)

if you forget to unlock you have deadlock!

You can't deadlock at least not in the Mutex sense. If you try to access a Buffer that has not been released then you get a panic!. If you forget to do Buffer.release when the transfer finished you would also run in this situtation; it's not inherent to the lock / unlock API.

Conversely, the Buffer -> Ref api looks pretty much exactly like a Mutex -> MutexGuard to me except that you can have multiple Refs.

Actually it's modelled exactly the same as a RefCell's Ref. But if you want to use the Mutex analogy then it would be equivalent to a RwLock.

Can you explain the differences? I'm wondering if having multiple Refs is really valuable for us.

You can read the buffer while it's also being read by the DMA in parallel. Not that I can give you an example about why that's useful off the top of my head. But it's a memory safe possibility and I don't see a reason to not allow it; someone may find it useful.

If the overhead of the reference count worries you we can add a Buffer variant that only hands out a single RefMut (&mut-) and uses a bool, instead of an usize, to keep track of the count.

@adamgreig

Although not explicitly bounded B can only be an array of bytes ([u8; N]).

Why?

I actually meant to type "array of bytes (e.g. [u8; N])" meaning that B should have type [T; N] but you can't bound the type like that in today's Rust. At the end it's up to the DMA based API to pick what B will be: [u8; N], [u16; N], etc.

I think this is much more true of multithreading where you have a stack for each thread/coroutine and so the buffer would live in that thread's stack.

You mean never-ending threads? I have mentioned before that stuff allocated in never-ending functions (fn() -> !) should have a different lifetime to indicate that they can't be deallocated. That would be useful here but that feature doesn't exist.

On a separate note, what about heap allocated Buffers for systems using dynamic allocation?

At first glance it seems that it would have the same problem at stack allocated arrays as in "there's no way to enforce that the boxed slice won't be deallocated midway the DMA transfer". I suppose the API could be tweaked to hand over the ownership of the buffer to the DMA (?) during the transfer and then have some DMA.release method to get the buffer (Box<[T]>) back. That raises the question where the Box<[T]> is stored during the transfer ...

I wonder if we could have the DMA stop the stream on drop, and then you could perhaps allow &/&mut directly?

You can't rely on drop happening :-). You can safely mem::forget the droppable thing that would have stopped the DMA and have Bad Stuff happen without using the unsafe keyword.

A proper solution to this "you can't rely on drop" stuff is adding linear types (I think that's what they are called) to Rust. A linear type means "this value MUST be dropped / consumed in this scope (unless you return it from the scope)". Rust has affine types: "this value should be dropped / consumed in this scope but it's fine if it's not (mem::forget)".

I've never needed to, but consider ...

OK but if we add this kind of feature we would have to lose some static typing. We would probably have to store in the buffer (i.e. at runtime) which channel is it being used with. Which means an enum of DMA channels rather encoding the channel as a phantom type. Seems doable but needs prototyping.

Can we have a DMAChannel trait in embedded-hal and then devices implement this against their specific DMA peripherals, for each channel?

Possibly. It will probably involve some ad-hoc traits that are implementation details and that are not supposed to be used by the end user.

[whitequark]

Although not explicitly bounded B can only be an array of bytes ([u8; N]).

You can use an AsMut<[u8]> bound here I think.

But this probably a bad idea since panicking destructor is equal to abort (?)

It is possible to have unwinding on larger microcontrollers (I know someone who did it on the less modestly sized STM32s) but it seems like an idea bad enough that I'm not sure if we ever want to support it...

A linear type means "this value MUST be dropped / consumed in this scope (unless you return it from the scope)". Rust has affine types: "this value should be dropped / consumed in this scope but it's fine if it's not (mem::forget)".

This doesn't work. An Rc loop is constructible safely and is functionally equivalent to mem::forget. This has been discussed to death back when mem::forget was stabilized; the signature of mem::forget is exactly identical to any other function that consumes a value and the function itself is equivalent to "put the object somewhere inaccessible to the rest of the code".

[japaric]

You can use an AsMut<[u8]> bound here I think.

Yeah that would work but it's limited to [T; 32]. This really wants to be struct Buffer<const N: usize, T, CHANNEL> { data: [T; N], .. } though. Hopefully that's not too far off in the future.

But this probably a bad idea since panicking destructor is equal to abort (?)

I was actually thinking of double / nested panics when unwinding would call a destructor that panics (IDK if, today, that situation causes an abort in std-land). But ... since ARM micros default to panic = abort that situation can't occur because the first panic will cause an abort.

This doesn't work.

Right. So, @adamgreig, we can't rely on destructors to preserve memory safety due to mem::forget.

[Kixunil]

How bad would it be to use closures to ensure "destructor" is run? (Like in case of scoped threads.)

[whitequark]

It's pretty bad, but I guess you can always fall back to an unsafe or poisoning API.

[japaric]

@Kixunil that would be too limiting. With a closures based API you can't split the start / finish operations in two tasks / interrupts, or create a futures based API to select two or more pending DMA transfers. It could be an alternative API if there's a need for it.

[vitiral]

Ok, I've gotten more of a chance to look this over. First of all, I believe that standardized shared buffers are probably one of the most critical requirements for building a microcontroller ecosystem -- so thankyou for putting in the effort of crafting an API around it

Simplicity of Data Sharing

I have written the library defrag-rs with the goal of allowing sharing and defragmentation of memory. I strongly advise the API presented there where memory pools give out Mutexes to their data which track when the data is locked, when it has a reference to it (may be used in the future) and when it is no longer in use. We could then have ALL microcontroller memory managers use this API.

The basic idea is that you might have an ecosystem of memory "pool" libraries that keeps track of a whole bunch of different data buffers. You would call Pool.get() to get a typed Mutex (or RwLock) which you could then pass on to any function (or you can get a reference and pass it on).

A few key points:

• I don't think the type should be a Buffer. We can use mem::size_of::<T>() to make sure that type T fits inside of whatever underlying "buffer" exists. Buffers aren't special -- we may want to pass around arrays of other types than u8 or large structs (note that I'm guilty of this too with defrag::Slice). For instance, I think functions could just accept Mutex<HeaplessVec<T, A>> where A is a generic array and HeaplessVec is similar to (or is) heapless::Vec
• I don't think the proposed static_ref::Ref gives us anything. Buffer (or Mutex) must already be guaranteed to not get freed when the function returns (although, you would have to return the Buffer in order for the data to stay reserved... which you have to do anyway to return the result!) (Edit: no you wouldn't... the function could store the Buffer in a static struct to execute asyncronously). We should think of all of these objects more like "heap allocated" data than anything else.

Comments on RwLock

I think RwLock is dangerous because you might have too many functions holding read-only references and it would be hard to ever get access to writing. In most cases, you should be able to lock the data and then pass out references if you want multiple readers. In other cases, lock should be sufficient.

Also, defrag manages to implement the lock using a single bit -- other memory management libraries can probably do the same. Doing this with RwLock would be completely impossible -- at minimum you would want to use at least one byte (for count of readers) and really you should use a usize. This kind of bit stuffing can make these libraries truly universal.

[whitequark]

The basic idea is that you might have an ecosystem of memory "pool" libraries that keeps track of a whole bunch of different data buffers.

I'm not particularly happy about this design. It seems to lock me into dynamic memory management of sorts.

[vitiral]

@whitequark the application specific "pools" could be statically allocated buffers where you know all the (typed) indexes at compile time (and they would be checked at compile time) -- or they could be semi-dynamic where there is a set number of known-size buffers, or they could be from a library like defrag where the memory allocation is truly dynamic.

We would have to make sure that ALL of these are supported -- but I think they can be 😄

[japaric]

I agree with @whitequark in that I wouldn't want the API here to be locked into
some dynamic memory management strategy. I do would like this API to also work
with dynamically allocated memory, but right now I can't see how to implement
such thing safely: it all boils down to solving the "you must not destroy this
buffer while the DMA is using it" problem which I have solved here with
static_ref::Ref which effectively means "the buffer can't never be destroyed".
The only other solution that I can think of are panicking destructors which are
rather bad.

Code-wise Buffer can be extended to support fixed size arrays, boxed arrays
and slices by turning it into a DST: struct Buffer<.., B> { .., data: B }
where B can be [T; N] or [T] allowing Box<Buffer<.., [T]>>, but the
destructor problem I mentioned above remains.

Comments on RwLock

Like I said above we can have two variants: the current "RefCell" style one
and a "RefMutCell" one that tracks the current borrow using a bool and can
only hand out a single &mut- reference at a time. I don't see a reason to not
provide the flexibility of allowing both.