How can we share a bus between multiple drivers?

[therealprof]

It is quite typical to have multiple I2C or SPI devices hanging on the same bus, but with the current scheme and move semantics the driver is taking possession of the handle, blocking the use of multiple chips at the same bus which is totally legal and (at least) for the blocking APIs should also be safe.

@japaric Should those bus types be made Copy?

[japaric]

How can we share a bus between multiple drivers?

There are a few ways:

• You destruct the driver to get back the I2C handle and pass that to the other driver

let mut driver_a = DriverA::new(i2c);
driver_a.stuff();
let i2c = driver_a.release();

let mut driver_b = DriverB::new(i2c);
driver_b.other_stuff();

• You use a RefCell

// these blanket implementations should be in embedded-hal
impl<'a, I> blocking::i2c::Write for &'a RefCell<I> where I: blocking::i2c::Write { .. }
// repeat for all the other traits

let shared_i2c = RefCell::new(i2c);

let mut driver_a = DriverA::new(&shared_i2c);
let mut driver_b = DriverB::new(&shared_i2c);

driver_a.stuff();
driver_b.other_stuff();

• You tweak the driver API to not own the I2C bus (I think this may be the best approach)

let mut driver_a = DriverA::new(&mut i2c);
let mut driver_b = DriverB::new(&mut i2c);

driver_a.stuff(&mut i2c);
driver_b.other_stuff(&mut i2c);

for the blocking APIs should also be safe

Should those bus types be made Copy?

I'm not sure if it being Copy-able would be memory safe in every single scenario but it would certainly be error prone in the presence of preemption:

app! {
    resources: {
        statci A: DriverA;
        statci B: DriverB;
    },

    tasks: {
        EXTI0: {
            path: exti0,
            priority: 1,
            resources: [A],
        },

        EXTI1: {
            path: exti1,
            priority: 2,
            resources: [B],
        },
    },
}

fn init(p: init::Peripherals) -> init::LateResources {
    // ..
    let i2c_alias: I2c = i2c; // due to `Copy`-ness

    init::LateResources { A: DriverA::new(i2c), B: DriverB::new(i2c_alias) }
}

fn exti0(r: &mut EXTI0::Resources) {
    r.A.stuff();
}

fn exti1(r: &mut EXTI0::Resources) {
    // can preempt `exti0` midway some operation on the I2C bus
    r.B.other_stuff();
}

[therealprof]

You destruct the driver to get back the I2C handle and pass that to the other driver

Sure, but that's quite useless.

You use a RefCell

That is interesting. I should have a play with that.

You tweak the driver API to not own the I2C bus (I think this may be the best approach)

I tried but couldn't get it to compile without nasty tricks. This is not easy to implement on chips that have freely selectable pins, at least that's my experience. I also haven't quite figured out how to implement the non-blocking trains; maybe you should try non-STM32 MCUs some time to get a feeling for the different peripheral implementations out there. 😉

I'm not sure if it being Copy-able would be memory safe in every single scenario but it would certainly be error prone in the presence of preemption:

Yes, I agree. Copy-able traits in the presence of preemption are probably a bad idea. You really don't want an interrupt handler to take over the bus in a middle of a transfer.

[ilya-epifanov]

You use a RefCell

You tweak the driver API to not own the I2C bus (I think this may be the best approach)

How will this work with RTFM?

fn init(mut p: init::Peripherals, _r: init::Resources) -> init::LateResources {
    ...

    let mut i2c = I2c::i2c1(
        p.device.I2C1,
        (scl, sda),
        &mut afio.mapr,
        i2c::Mode::Fast { frequency: 400000, duty_cycle: i2c::DutyCycle::Ratio16to9 },
        clocks,
        &mut rcc.apb1,
    );

    let si5351 = SI5351::new(&mut i2c, false, 25_000_000).unwrap();

    let _ = ssd1306::init(&mut i2c);
    let _ = ssd1306::pos(&mut i2c, 0, 0);
    let _ = ssd1306::print_bytes(&mut i2c, b"Send ASCII over serial for some action");'

    init::LateResources {
        SI5351: si5351,
        I2C: i2c
    }
}

Since the value i2c is move'd when constructing init::LateResources, all the references to it will break. Same for the RefCell solution.

[therealprof]

@japaric I tried the RefCell approach and it works great (at least in my limited testing). I'll submit a PR for review later.

[wose]

@therealprof awesome. I had this on my TODO list as well. My 2 cents why I think this will be the most flexible approach:

You destruct the driver to get back the I2C handle and pass that to the other driver

This is fine as long as the driver doesn't hold any state. For example: if you need the currently set measurement resolution to correctly interpret the sensor readings. You could probably design the driver to be able to attach/detach to a bus and manage the driver state independently. But this results in extra work for the driver implementer and the user.

You tweak the driver API to not own the I2C bus (I think this may be the best approach)

I first favored this method but then realized this would probably make hardware interface (I2C, SPI, ...) agnostic sensor traits impossible (I might have overseen sth. here, because of my not so extensive Rust knowledge). The trait methods would also need to pass the bus around and something like this would not work.

pub trait Thermometer {
    type Error;

    fn temp(&mut self) -> Result<f32, Self::Error>;
}

The RefCell approach would allow for minimal hardware interface management on the driver side and also allow bus independent trait implementation. I'm really looking forward to your PR and testing it.

[therealprof]

And also let's not forget that it's quite common to need additional resources instead of just the bus itself. For I2C (and to a lesser extend) SPI there're often separate interrupt pin(s) and for SPI one often needs to worry about a chip select pin as well. The complexity of the solution to such an approach could explode rather quickly.

[japaric]

I left a comment in #55 (comment) about the shortcomings of the "put the resource protection (e.g. RefCell) in the driver" approach.

You could probably design the driver to be able to attach/detach to a bus and manage the driver
state independently.

I think this might be the way to go. You design your driver as having two type states: one where it
owns the I2C bus and one where it doesn't. Something like this:

/* embedded-hal */

// imagine this is one of the blocking I2C traits
trait I2c {
    /* .. */
}

/* sensor1 */

// Only the sensor state
// The type parameter `I` is mainly to forbid the following scenario: you
// initialize the sensor using I2C1, then you perform some op on it using I2C2
// and then another op using I2C3.
pub struct State<I>
where
    I: hal::I2c,
{
    // ..
    i2c: PhantomData<I>,
}

pub fn init<I>(i2c: &mut I) -> State<I>
where
    I: hal::I2c,
{
    // ..
}

impl State<I> {
    pub fn take<I>(self, i2c: I) -> Owned<I>
    where
        I: I2c,
    {
        // ..
    }

    pub fn borrow<I>(&mut self, i2c: &mut I) -> RefMut<I>
    where
        I: I2c,
    {
        // ..
    }
}

struct Owned<I>
where
    I: hal::I2c,
{
    i2c: I,
    state: State,
}

impl Owned<I> {
    pub fn release<I>(self) -> (State, I)
    where
        I: I2c,
    {
        // ..
    }

    pub fn accel(&mut self) -> u16 {
        // defer to RefMut
        self.as_ref_mut(|s| s.accel())
    }

    fn as_ref_mut<R, F>(&mut self, f: F)
    where
        F: FnOnce(&mut RefMut<I>) -> R,
    {
        f(&mut RefMut {
            i2c: &mut self.i2c,
            state: &mut self.state,
        })
    }
}

pub struct RefMut<'a, I>
where
    I: hal::I2c,
{
    i2c: &'a mut I,
    state: &'a mut State,
}

impl RefMut<'a, I> {
    pub fn accel(&mut self) -> u16 {
        // ..
    }
}

/* app */
fn main() {
    let mut i2c: I2c1 = ..;

    // neither operation takes ownership of `i2c`
    let sensor1: sensor1::State<I2c1> = sensor1::init(&mut i2c);
    let sensor2 = sensor2::init(&mut i2c);

    // takes ownership of `i2c`
    let mut sensor1: sensor1::Owned<I2c1> = sensor1.take(i2c);
    let g = sensor1.accel();
    let (sensor1, mut i2c) = sensor1.release();

    // doesn't take ownership of `i2c`
    let m = sensor2.borrow(&mut i2c).mag();
    let ar = sensor2.borrow(&mut i2c).gyro();
}

The Owned variant is required to support async operations that involve Futures and/or
Generators: async code doesn't like (mutable) references (*) (unless they have 'static
lifetime) -- everything needs to be passed by value. RefMut is mostly a convenience to avoid
having to take - release on every I2C operation / handover. If you are going to deal with only
one I2C slave you can use the Owned variant and your code will look pretty much the same as it
looks today.

(*) Actually that's another reason why storing a reference to a RefCell / Mutex in the driver
is not as flexible as this approach.

---

@ilya-epifanov

How will this work with RTFM?

If you are going to do blocking operations in your tasks store I2c and State as resources and
use RefMut / borrow:

fn task1(r: EXTI0::Resources) {
    let g = r.SENSOR1.borrow(r.I2C1).accel();
}

fn task1(r: EXTI1::Resources) {
    let ar = r.SENSOR2.borrow(r.I2C1).gyro();
}

If you are going to use the DMA store Option<I2c> and Option<State> as resources and use
Owned / take:

fn task1(r: EXTI0::Resources) {
    let sensor1: sensor1::State<_> = r.SENSOR1.take().unwrap();
    let i2c = r.I2C.take().unwrap();

    let pending_transfer = sensor1.take(i2c).mag_dma();

    // send `pending_transfer` to some other task, etc.
}

---

@therealprof

And also let's not forget that it's quite common to need additional resources instead of just the
bus itself. For I2C (and to a lesser extend) SPI there're often separate interrupt pin(s) and for
SPI one often needs to worry about a chip select pin as well.

The NSS / NCS / interrupt pin can be permanently stored in the State struct; no need to move them
out -- it's not like you are going to share any of those pins between different sensors.

[therealprof]

@japaric I'll give your idea a spin.

The NSS / NCS / interrupt pin can be permanently stored in the State struct; no need to move them
out -- it's not like you are going to share any of those pins between different sensors.

I would not necessarily say that this is always the case. Pinsharing is not quite as uncommon as it seems and used for all kinds of stuff like measurements triggering, resets and sometimes they're also muxed (though in that case you'd probably need an alternative PIN driver anyway).

[therealprof]

@japaric This puts quite a few additional requirements on each individual driver without explicitly defining what they are. I would rather prefer a solution that requires the driver HAL implementation to make sure shared use is safe (by disabling interrupts if necessary) or the user to use a safe mechanism for sharing the bus, same as we already do when sharing resources internally.