Project idea: better embedded driver support

[thejpster]

How about working on some embedded dev boards and building up some driver support crates? UARTs, SPI, PWM, that sort of thing. I'm thinking things along the line of japaric's F3, or my Launchpad/LM4F120. Looking at a variety of hardware platforms might help #rust-embedded work towards a common API for common peripherals.

If you get the right boards, they're relatively cheap. I just picked up some Kinetis Cortex-M0+ boards (with 5V I/O!!) for about £10. TI Launchpads are about the same. Raspberry Pi Zeros even. You might get a sponsor to cover the cost, and developers can take the boards away at the end to carry on working.

@japaric has created an Etherpad for elaborating on some of the ideas here. Check it out.

[skade]

That sounds like a cool idea and there's still some time for people to buy boards. Would you like to be personally involved? (Maybe even on site in Cambridge or London, maybe. In London, we are still specifically searching for people, we might have a room at Mozilla London) 😉

[thejpster]

I would like to be involved but I need to check availability for that weekend. Cambridge would be better than London (I started #5 for that).

[skade]

I edited the title to better express what the idea is. I hope thats a good one, feel free to change if you come up with a better one.

[japaric]

Thanks to Rust Belt Rust (shameless plug) we got around 15 rustaceans with the right hardware (STM32F3DISCOVERY boards). I've informed all of them about this. I don't know how many of them are in Europe or can be in Europe for the date of novemb.rs but perhaps some of them can join remotely.

I'm not in Europe but would love to participate remotely during the hours that are not crazy for me (I'm on UTC -5)

[skade]

@japaric they are readily available at German resellers. I'm pretty sure DHL can make us tremble in fear, though. The problem is more of a budget one, if we want to supply people with them.

[thejpster]

I'd like to make sure we get a spread of different hardware available too. By implementing several UART drivers for several boards, we can hopefully work out what a generic UART trait might look like. There are many boards using Cortex-M4 based microcontrollers available at the £10-£15 price point.

[SimonSapin]

Where C or C++ drivers exist, https://github.com/servo/rust-bindgen could be used to generate Rust bindings for them. I've had success doing this for Teensy hardware: https://github.com/jamesmunns/teensy3-rs

One downside is that FFI functions require unsafe to call, and constants generated from #define may require casting with as.

[japaric]

@SimonSapin I just took a look at the teensy3 crate and it seems it only exposes a blocking API. Do you know if the underlying C/C++ libraries expose an async/non-blocking API or if/how the Teensy API can be used to run concurrent tasks?

The other issue I see there is that the documentation says that e.g. Serial is supposed to be a singleton but it exposes it a struct that the user can create many instances of. This is probably not a problem for the teensy3 crate right now because it doesn't (seem to) expose async IO, interrupts or threads/tasks but once you introduce any of those then you'll realize that you want to enforce peripheral "ownership" in your API or at very least expose peripherals as Mutexed globals.

Those are the three topics I'd like to discuss during this event: async IO, "ownership" of hardware and dealing with interrupts. FWIW, I've begun to experiment with futures-based async IO in my f3 crate in this branch.

I don't have experience with production embedded systems so I don't know how C applications dealt with those (callbacks?) but I hope that someone (@thejpster?) who has the experience shows up at the event because it would be illuminating.

[thejpster]

So, to take the UART as an example, they vary across the embedded systems I've worked on. At the fundamental level they all implement a putc and a getchar (but probably not called that). They then may have a string write routine which calls putc in a loop. Both putc and getchar will block. There may be a 'haschar' function which is non-blocking. The problem with haschar is that the system can't efficiently poll the UART - you often want your system blocked in the wfi instruction (wait for interrupt) to save power, rather than spinning madly. In addition, more advanced systems (most of the ones I've worked on) can't afford the character drops that will ensue as they don't usually have automatic hardware flow control wired up. To fix this they will remove characters under interrupt from the receive buffer into a largish software FIFO. There may also be an outgoing FIFO so that println and friends at least manage to get some of the output buffered and so block for less time. The API is unchanged. The FIFOs implement atomicity by disabling interrupts around critical sections. Main loops can sit in WFI because an interrupt will occur whenever data arrives. The next 'level' if you like is the multitasking system. This is a system where every layer in the protocol stack (I make radios/modems) is a task and they message pass requests, confirmations and indications between them. Here, we'll get the UART low level ISR to trigger a high level ISR, and get the high level ISR to either trigger an event in an OS flag group that another task is pending on (as well as put the received bytes in a buffer) or to put the bytes in a 'data received indication' message sent to the registered handler. This means that, say, the command line interpreter task, or the PPP task, is blocked by the OS waiting for new data and not wasting CPU spinning. In terms of ownership, this is just managed by only including the header if you need access to the UART. For simpler systems, access is through the C library functions because we'd map stdio and stdout (or maybe some other file descriptors) to a UART. There is no 'object' - it's all global data. Where I've written C++ UART drivers, it's easy to get tired of passing the UART object around, and if the object is a global you have the problem of ensuring the constructor runs before anyone that needs the UART. Multiple UARTs in C would be handled by passing the UART number as the first argument to all the functions. So, how do I think UARTs should look in Rust? Well, working out how to fill a receive FIFO under interrupt is high on my list. This will probably involve some sort of interrupt disabling Mutex that you can also grab from interrupt context. Likewise for transmit. Currently I implement a C++ style object approach but I'm not sure how to implement a println! which can be called anywhere. Maybe lazy-static is my friend here.

[SimonSapin]

@japaric For Serial specifically, the underlying library is documented at https://www.pjrc.com/teensy/td_serial.html. It looks like the Serial.available() and Serial.read() pair can do non-blocking reads, but I don’t know about writing. As to concurrency with that API (which is largely that of Arduino) I don’t know if anyone ever tried.

The Rust Serial struct has no field / is zero-sized. It’s effectively a singleton, that struct only exists because I think the foo.bar() method call syntax looks better than Foo::bar().

What is the point of enforcing device ownership or using Mutex when the hardware does not provide paralellism or preemption?

Anyway, my approach to this project was to get something running quickly for a very simple application, all over the span of a few weekends. So any design choice is more likely the first thing that worked rather than a rejection of alternatives. If it turns out there are good reasons to change it nothing in teensy3-rs is frozen, as long as someone wants to spend the time/effort to develop it.

[japaric]

@thejpster Very enlightening! Thank you. I've got a few questions but I'm going to ask them over IRC to avoid going (too) off-topic.

---

@SimonSapin

when the hardware does not provide paralellism or preemption?

Oh, but it does! Interrupts are a preemption mechanism and their "handlers" (the functions that get called when an interrupt occurs) have their own "execution context" (stack frame) so in a sense they are like threads. As soon as your program has to dealt with interrupts, you run into the need of wanting to exchange between your main thread / loop and interrupts and the "obvious" way is to use a static muts which are a can of worms data races.

The issue I was referring to about Serial looks like this:

fn main() -> ! {
    // .. initialization stuff ..

    loop {
        // NOTE blocking!
        Serial.write_all(b"The quick brown fox jumps over the lazy dog.");
    }
}

// This is an interrupt handler. It runs e.g. every 10 milliseconds
// When those 10 milliseconds pass the processor will *stop* executing the `main` function,
// it will then execute this function and then return to `main` when this function is done
fn tim7() {
    // NOTE blocking as well
    Serial.putc(b'X');
}

This without an OS just using hardware features. At best this will print something like this:

ThXe XquXic...

At worst the interrupt handler may kick while write_all was mid through modifying several registers and the interrupt handler will start its execution with registers in a bad/unexpected state.

"But nobody writes code like that" is not a good argument. The question here is whether the compiler can stop you from writing racy code like the above. And I think it can, if you structure your code differently:

fn main() -> ! {
    // .. initialization stuff ..

    // A single instance of Serial
    let mut serial = Serial::init_once();

    loop {
        if done_with_previous_write {
            // NOTE Non-blocking!
            serial.async_write_all(b"The quick brown fox jumps over the lazy dog.");
        }

        // moved the interrupt handler logic into the main loop
        if ten_milliseconds_have_passed {
            serial.putc(b'X');
        }
    }
}

This should error with "trying to mutably borrow serial twice". But if you want to write code like that, code that runs concurrent tasks in the main loop, you can't use a blocking API.

Anyway, my approach to this project was to get something running quickly for a very simple application ...

Totally understandable. I hope we can continue working on top of the teensy3 crate during this event.

---

OK, back to the main topic. It seems to me that if we want to work on designing a non-blocking API we should have some list of applications that have to deal with concurrent tasks / events that we must implement during this event. And implementing those applications will trigger discussion and tease out the API design.

The applications should be implementable without needing (too much) external hardware to keep the cost low. Ideally we should use try to use all the stuff that the development board already have on them.

Possible applications could be:

• My running example of running two concurrent tasks: a LED that blinks, say, every 100 ms and an "echo server" running on top of the serial interface. (echo server means that the microcontroller must send back every byte that the user sends through the serial interface). This requires extra hardware like a Serial <-> USB converter or a Serial <-> Bluetooth module (RFCOMM) to be able to have a person interact with the "server" through a laptop (using minicom, putty or other serial emulator program)
• Two concurrent tasks: Blinking an LED at, say, 100 ms and turning on/off a different LED when the user presses a button. This one may be tricky because of the debouncing logic. But most boards should have two LEDs and an user button on them.
• Reading two sensors / analog signals at different rates, say, 30 Hz and 40 Hz and, if available, report them to a user through a serial interface. Needs extra hardware. Perhaps, instead of reporting though serial, the micro could dim two LEDs, using PWM, based on the analog values.

Once we have of these applications we can merge the tasks in them to build more complex applications.

These applications also force you to actually write the peripheral/sensor drivers.

Thoughts about this last idea? Can think of more "applications" to tackle during novemb.rs?

[japaric]

you often want your system blocked in the wfi instruction (wait for interrupt) to save power, rather than spinning madly. -- @thejpster

To increase the difficulty level, we should strive to make the above applications always sleep when there's nothing to do rather than "busy wait" (spin endlessly).

[japaric]

So I have been thinking about what we could work on during the event and turns
out there's lot of stuff that we could do. I've collected my ideas into
a public etherpad so others can add their ideas as well. The "focus areas"
I've proposed are:

• Onboarding. Getting Rustaceans, both beginners and experienced with embedded
  systems but not with embedded Rust development, up to speed with embedded Rust
  development.
• API design. APIs (traits!) for things like Serial, I2C, PWM, etc. that are
  general enough to be implementable for different microcontrollers / dev
  boards. We can start with a blocking API and then work on an async API.
• Tackling open ended problems. How to safely deal with interrupts, what does a
  Rustic preemptive scheduler looks like, when is it unsafe to read / write a
  register, etc.
• IDE integration. I've configured Eclipse before for embedded C development.
  Perhaps, we can something similar for embedded Rust development.

The etherpad contains way more details about these areas. Let's discuss the
details here.

The etherpad also contains a list of participants which is more like a hardware
/ time zone survey. I encourage you to add yourself to it if you plan to
participate in the code sprint.