[RFC] `digital::IoPin`, pins that can switch between input and output modes at runtime

[japaric]

Some people have expressed interest in a trait like this for writing generic LCD drivers but there are probably other use cases.

We were discussing this on IRC yesterday and I proposed three different APIs:

Proposals

Result based API

/// A pin that can switch between input and output modes at runtime
pub trait IoPin {
    /// Signals that a method was used in the wrong mode
    type Error;

    /// Configures the pin to operate in input mode
    fn as_input(&mut self);
    /// Configures the pin to operate in output mode
    fn as_output(&mut self);

    /// Sets the pin low
    fn set_low(&mut self) -> Result<(), Self::Error>;
    /// Sets the pin high
    fn set_high(&mut self) -> Result<(), Self::Error>;

    /// Checks if the pin is being driven low
    fn is_low(&self) -> Result<bool, Self::Error>;
    /// Checks if the pin is being driven high
    fn is_high(&self) -> Result<bool, Self::Error>;
}

// this function won't panic; LLVM should be able to opt way the panicking branches
fn example(mut io: impl IoPin) {
    io.as_input();
    if io.is_low().unwrap() {
        /* .. */
    }
    if io.is_high().unwrap() {
        /* .. */
    }

    io.as_output();
    io.set_low().unwrap();
    io.set_high().unwrap();
}

Closure based API

/// A pin that can switch between input and output modes at runtime
pub trait IoPin {
    /// Pin configured in input mode
    type Input: InputPin;

    /// Pin configured in output mode
    type Output: OutputPin;

    /// Puts the pin in input mode and performs the operations in the closure `f`
    fn as_input<R, F>(&mut self, f: F) -> R
    where
        F: FnOnce(&Self::Input) -> R;

    /// Puts the pin in output mode and performs the operations in the closure `f`
    fn as_output<R, F>(&mut self, f: F) -> R
    where
        F: FnOnce(&mut Self::Output) -> R;
}

fn example(mut io: impl IoPin) {
    io.as_input(|i| {
        if i.is_low() { /* .. */ }
        if i.is_high() { /* .. */ }
    });

    io.as_output(|o| {
        o.set_low();
        o.set_high();
    });
}

Implicit / Automatic API

/// A pin that can switch between input and output modes at runtime
pub trait IoPin {
    /// Signals that a method was used in the wrong mode
    type Error;

    /// Sets the pin low
    ///
    /// **NOTE** Automatically switches the pin to output mode
    fn set_low(&mut self);
    /// Sets the pin high
    ///
    /// **NOTE** Automatically switches the pin to output mode
    fn set_high(&mut self);

    /// Checks if the pin is being driven low
    ///
    /// **NOTE** Automatically switches the pin to input mode
    /// **NOTE** Takes `&mut self` because needs to modify the configuration register
    fn is_low(&mut self) -> bool;
    /// Checks if the pin is being driven high
    ///
    /// **NOTE** Automatically switches the pin to input mode
    /// **NOTE** Takes `&mut self` because needs to modify the configuration register
    fn is_high(&mut self) -> bool;
}

fn example(mut io: impl IoPin) {
    if io.is_low() {
        /* .. */
    }
    if io.is_high() {
        /* .. */
    }

    io.set_low();
    io.set_high();
}

I have implemented the proposals as branches io-1, io-2, io-3. You can try them out by adding something like this to your Cargo.toml file:

[dependencies]
embedded-hal = "0.1.0"

[replace]
"embedded-hal:0.1.0" = { git = "https://github.com/japaric/embedded-hal", branch = "io-1" }

Implementation concerns

There were some concerns about whether these traits can actually be implemented for all possible scenarios given that switching the mode of any pin on say, GPIOA, usually requires a RMW operation on some control register; thus the pins need exclusive access to the control register when switching modes.

Following the CRL idea of the Brave new IO blog post it seems that implementations would run into this problem:

struct IoPin {
    // pin number
    n: u8,
    crl: CRL,
    // ..
}

let pa0 = IoPin { n: 0, crl, .. };
let pa1 = IoPin { n: 1, crl, .. };
//^ error: use of moved value: `x`

But you can use a RefCell to modify the CRL register in turns:

struct IoPin<'a> {
    // pin number
    n: u8,
    crl: &'a RefCell<CRL>,
    // ..
}

let crl = RefCell::new(crl);
let pa0 = IoPin { n: 0, crl: &crl, .. };
let pa1 = IoPin { n: 1, crl: &crl, .. };

This limits you to a single context of execution though because RefCell is not Sync which means &'_ RefCell is not Send which means IoPin is not Send either.

But you can recover the Send-ness and avoid runtime checks by splitting CRL in independent parts that can be modified using bit banding, if your chip supports that:

let crls = crl.spilt();
let crl0: CRL0 = crls.crl0;
let crl1: CRL1 = crls.crl1;

let pa0 = IoPin0 { crl0, .. };
let pa1 = IoPin0 { crl0, .. };

---

Thoughts on these two proposals? Do they fit your use case? Do you have a different proposal?

cc @kunerd @therealprof

[therealprof]

@japaric I don't think it is quite common to switch a Pin between reading and writing.

However often used is tje ability to "tri-state" a pin i.e. set high, low and floating. Reading is not necessarily the same as setting it floating because often a pull-up or pull-down can be configured and in that case the pin would not be floating but sink or source current, driving the pin useless. Also for the "Implicit / Automatic API" case above I can imagine that the read might not be optimised away, although the result is actually irrelevant, because it is done via volatile read.

For my tri-state uses the "Implicit / Automatic API" is actually very intriguing but instead of providing the ability to read the value I'd add set_floating and is_floating.

[japaric]

@therealprof OK, that sounds like a different use case from what was mentioned on IRC. A different trait for a tri-state pin makes sense.

[kunerd]

One other example that requires switching between in- and output of a pin is when implementing drivers for 1-wire protocols, like the one that the DS1820 temperature sensor uses I think.

[therealprof]

@japaric I agree. However it's a very important one because it's required for multiplexing and especially charlieplexing which is very common. Not sure how often direction change is used in real life -- I'm just very sure I've never encountered a use for that before.

So we're going to have a TriPin then? 😁

[therealprof]

@japaric I just noticed that although #11 talks about having an InputPin, it doesn't exist yet, nor does an issue for its creation. Is the IoPin going to replace both the OutputPin and the InputPin? Or are the planned new traits going to be generic abstractions over more primitive traits?

[idubrov]

I think, closure-base API places significant limitation on when you can change pin direction.

It would be fine for localized direction changes (like in case of LCD, you would change the direction, wait for busy flag and switch it back to output), but I wonder, would it work for longer pin direction changes (walkie-talkie style)?

Implicit API requires exclusive ownership, which is also somewhat limiting (although, I can't think of the realistic scenario)

With result-based API, I wonder, what would be the realistic scenario of checking that error? Wouldn't it be better to simply panic instead of reporting an error?

[japaric]

@therealprof

Is the IoPin going to replace both the OutputPin and the InputPin?

No. All those have different use cases and can be used independently.

@idubrov

Wouldn't it be better to simply panic instead of reporting an error?

Yeah, we could chalk it up as a programmer error and simply panic. I think (hope) the compiler will be able to optimize away the panic branches.

---

Yet another option is to encode the type state change in the trait. I think it would look like this:

pub trait IoPin {
    type Input: InputPin + IoPin<Input = Self::Input, Output = Self::Output>;
    type Output: OutputPin + IoPin<Input = Self::Input, Output = Self::Output>;

    fn into_input(self) -> Self::Input;
    fn into_output(self) -> Self::Output;
}

fn example<IO>(io: IO) -> IO::Output
where
    IO: IoPin,
{
    let input /* : IO::Input */ = io.into_input();

    if input.is_low() {
        // ..
    }

    let mut output = input.into_output();

    output.set_high();

    output
}

It seems to compile at least.

[therealprof]

No. All those have different use cases and can be used independently.

👍

Not quite sure why the OutputPin as it is has is_low and is_high functions in it. There're actually platforms where pins configured as output cannot be read back.

[astro]

I like the ability to encode direction in the type. Automatic switching at run-time requires checking overhead.

The presence of is_low and is_high on OutputPin allows you to accidentally call them when you actually wanted to read from an InputPin. If you keep these function in OutputPin please consider naming them differently in InputPin.

[astro]

Here is a DHT22 driver using proposal io-2: https://github.com/astro/dht22-rs