[RFC] opt-in Peripherals steal

[japaric]

Current behavior

The init::Context struct includes a device field whose type is
#device::Peripherals, a singleton that's a collection of all the device
peripherals.

Proposal

Don't include this device field by default. Add a peripheral argument to the
#[rtfm::app] attribute that lets the user opt into today's behavior.

Rationale

#device::Peripherals is a singleton; in multi-core mode only one core can
take all the peripherals so it's necessary to specify which core will take the
singleton.

Detailed design

The #[rtfm::app] attribute will gain a peripherals argument whose semantics
varies between single-core and multi-core mode.

Single-core mode

In single core mode the argument takes a boolean that indicates whether the
device peripherals will be made available during the init function. When the
peripherals argument is omitted the peripherals will not be made available.

// NOTE omitting `peripherals` also means `peripherals = false`
#[rtfm::app(device = pac, peripherals = false)]
const APP: () = {
    #[init]
    fn init(c: init::Context) {
        // let device: pac::Peripherals  = c.device;
        //~^ error: no field named `device` in this struct
    }
};

#[rtfm::app(device = pac, peripherals = true)]
const APP: () = {
    #[init]
    fn init(c: init::Context) {
        // OK
        let device: pac::Peripherals  = c.device;
    }
};

Multi-core mode

In multi-core mode the peripherals argument takes a integer that indicates
which core will take the device peripherals during init. If the argument is
omitted then the peripherals will not be taken by the framework.

#[rtfm::app(cores = 2, device = pac, peripherals = 1)]
const APP: () = {
    #[init(core = 0)]
    fn init(c: init::Context) {
        // let device: pac::Peripherals  = c.device;
        //~^ error: no field named `device` in this struct
    }

    #[init(core = 1)]
    fn init(c: init::Context) {
        // OK -- this core takes all peripherals
        let device: pac::Peripherals  = c.device;
    }
};

Alternatives

In single-core mode, should the default be to have RTFM take the peripherals?
That is peripherals would default to true matching today's behavior and one
would have to opt-out by writing peripherals = false.

One could design a syntax to split the peripherals between the many init
functions in multi-core mode but this can't be implemented today's without extra
help from svd2rust so this proposal doesn't delve into that question.

cc @hannobraun #163

[hannobraun]

Thanks for the heads-up! This looks sensible to me, and would solve the problem I reported in #163.

[TeXitoi]

Is device = pac needed for other thing that peripherals?

[japaric]

@TeXitoi the framework internally uses ${device}::Interrupt::${binds} as an argument to NVIC::{pend,enable,set_priority} calls and to check that the ${binds} interrupt actually exists on the target device.

[korken89]

I agree with the addition, but not with the default.
I'd argue to keep the old default (peripherals = true) to maximize backwards compatibility and keep it as users expect it.

[japaric]

@korken89 the multi-core default is to not take the peripherals, though, so in a way the two defaults wouldn't match if we go with peripherals = true on single-core. Alternatively, we could default to peripherals = 0 on multi-core and use peripherals = false to not take the peripherals; that would sort of "match" with peripherals = true on single-core.

I do see how peripherals = true is good for backward compatibility (though we are already breaking plenty of things in v0.5) but have no strong opinions on what the defaults should be.

@TeXitoi any thoughts on what the defaults should be?

Modulo the defaults I think we have consensus on the rest of the RFC so I'm going to FCP this with disposition to merge. Let's solve the question about the defaults during the FCP.

• @japaric
• @korken89
• @TeXitoi

[TeXitoi]

I don't like default values to be true. That's much more intuitive to have false when you don't set something. So my preference is to false even if that's the most common choice.

OK for me for the rest.

[japaric]

@TeXitoi True (no pun intended). The Default implementation of bool returns false and you can think of the multi-core peripheral as being an Option<u8> that defaults to None.

[korken89]

Technically I agree, from the old usage patterns I do not agree.
But I do not have any strong opinion here, so LGTM.

[japaric]

🎉 This RFC with the single-core default of false has been formally approved. Implementation is in PR #205 (I'm going to keep this open until the PR lands)

[japaric]

Done in PR #205