drop #[exception] and #[interrupt] syntax in favor of #[task(binds = ..)]

[japaric]

Current behavior

Two attributes are used to declare hardware tasks: #[exception] and
#[interrupt]. The difference between the two is subtle: #[exception] is for
declaring hardware tasks bound to one of the ARM Cortex-M exceptions (e.g.
SVCall, SysTick), whereas #[interrupt] is for declaring hardware tasks
bound to device specific interrupts.

This distinction has been inherited from cortex-m-rt-land where two attributes
are required to implement the "does this interrupt exist?" check -- the issue
there is that the enumeration of valid exceptions / interrupts are defined in
different crates (cortex-m and PAC, respectively) and the #[exception] and
#[interrupt] attributes can be used in any context (application or library) --
handlers can even be defined in multiple crates.

Proposal

Drop the #[exception] and #[interrupt] attributes from the syntax and use
the #[task] attribute to declare both software and hardware tasks.

Rationale

In RTFM applications hardware tasks are defined within the contents of the
#[rtfm::app] macro so there's no real need for the user to distinguish between
hardware tasks bound to Cortex-M exceptions and hardware tasks bounds to
device-specific interrupts -- the framework can tell these apart without user
input (the set of Cortex-M exceptions is known at macro expansion time).

Apart from the #[init]-ialization function and the background #[idle]
context RTFM only has tasks: these may be software tasks issued on demand by the
software or hardware tasks started by some hardware event (interrupt signal).
It seems appropriate to use the #[task] attribute for both kind of tasks
rather than to use two additional attributes to refer to one particular kind
of task.

Lastly, this shrinks the syntax of the RTFM meta-language which simplifies the
parser and shrinks the test suite -- there would be no need to test so many
combinations of attributes and arguments.

Detailed design

Reject uses of the the #[exception] and #[interrupt] attributes within a
#[rtfm::app] specification. To declare a hardware task the programmer will use
the existing #[task] attribute but include the binds argument.

#[rtfm::app(device = ..)]
const APP: () = {
    // this is a hardware task
    #[task(binds = EXTI0)]
    fn on_button_pressed(_: on_button_pressed::Context) {
        // ..
    }

    // this is a software task
    #[task]
    fn process_packet(_: process_packet::Context, packet: Packet) {
        // ..
    }
};

Additionally, the framework will reject #[task]s where both the binds and
capacity arguments have been specified -- a hardware task has no associated
message queue and thus no capacity.

#[rtfm::app(device = ..)]
const APP: () = {
    #[task(binds = EXTI0, capacity = 2)]
    fn on_button_pressed(_: on_button_pressed::Context) {
    // ~~~~~~~~~~~~~~~~~ error: hardware tasks can't be assigned a capacity
        // ..
    }
};

Drawbacks

The #[exception] and #[interrupt] attributes are well established in the
wider Cortex-M ecosystem so newcomers to RTFM may find them familiar; that
familiarity would be lost with this proposal. However, I'm not sure this
familiarity is that useful because the attributes used within #[rtfm::app]
don't have the same syntax as the cortex_m_rt::{exception,interrupt}
attributes.

Alternatives

If it seems useful to visualize tell apart hardware tasks from software tasks we
could use a single attribute for them. For example, we could use
#[interrupt] for all of them (instead of a mixture of #[exception] and
#[interrupt]).

[placrosse]

Well-reasoned.

[little-arhat]

Is it possible to add some attributes to help with https://github.com/japaric/cortex-m-rtfm/issues/197 ?

[korken89]

This is indeed a good step forward and a simplification that helps readability.
STGM!

[japaric]

This seems uncontroversial let's give a 1 week-ish FCP with disposition to merge.

• @japaric
• @korken89
• @TeXitoi

[TeXitoi]

A great simplification.

OK for me

[jordens]

How would the irqn argument and the HardFaultTrampoline be handled/passed?
Is the never type return ok for (non-idle) tasks already or would that be an addition?

fn DefaultHandler(irqn: i16);
fn HardFault(ef: &cortex_m_rt::ExceptionFrame) -> !;

[japaric]

@jordens neither of those two handlers can be managed by RTFM; they are rejected by the DSL if you try to bind a task to them. Only interrupts / exceptions with configurable priorities can be used as tasks.

(Accessing a resource (lock API) from any of those two handlers would be unsound. Many instances of DefaultHandler can run concurrently that could produce multiple mutable references to resource data, and the HardFault handler can't be masked)

[japaric]

🎉 This RFC 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