[RFC] [breaking-change] Turn entry!, exception! into attributes

[japaric]

What the title says. I believe attributes would be more ergonomic and less redundant. Compare this:

entry!(main);

fn main() -> ! {
    // .. user code ..
}

exception!(HardFault, handler);

fn handler() -> ! {
    // .. user code ..
}

to this:

#[entry]
fn main() -> ! {
    // .. user code ..
}

#[exception(HardFault)]
fn handler() -> ! {
    // .. user code ..
}

As a bonus point we get rid of the indirection that the entry! macro requires.

entry! expands into this for type safety:

#[export_name = "main"]
fn __impl_main() -> ! {
    // check the signature of `main`
    let f: fn() -> ! = main;
    f()
}

The function call doesn't always get inlined (unless you marked main as #[inline(always)], which
looks a bit odd).

On the other hand, #[entry] expands into this:

#[export_name = "main"]
pub fn main() -> ! {
    // .. user code ..
}

so there's no function call even when compiling without optimizations. (The type check is done
syntactically during the macro expansion)

Unresolved questions

• Choose a syntax for adding state to #[exception]s.

---

#[proc_macro_attribute], which is required to write these macros, has already been stabilized in
nightly. #![feature(use_extern_macros)], which is required to use these macros, has not been
stabilized yet, but it's planned for the 2018 edition (1.31).

[japaric]

@rust-embedded/cortex-m this RFC needs a decision.

[korken89]

From a usability perspective, this is a lot better in my opinion as it follows the way Rust is generally approached and is concise.
The nice part with the current macros was that the usability was a bit more explicit, but I guess the embedonomicon will be extended to explain how it works?

[therealprof]

@japaric I love it but how would you bring it up with the relevant parts still unstable?

[adamgreig]

+1 on swapping to the attributes instead of the current macros.

• What do we do for DefaultHandler? #[exception(*)] as currently, or a different attribute name?
• Does svd2rust swap to using #[interrupt(...)]?
• Syntax for the optional state does seem like it might be a bit messy. #[exception(SysTick, state: u32 = 0)] is a bit unusual, but I don't see a way around needing to specify the initial value. Having it be an Option means you have to check it every interrupt, having it uninitialised is obviously not viable.

[japaric]

@therealprof last part of the RFC

#[proc_macro_attribute], which is required to write these macros, has already been stabilized in
nightly. #![feature(use_extern_macros)], which is required to use these macros, has not been
stabilized yet, but it's planned for the 2018 edition (1.31).

This won't be implemented until the required features are at least in beta.

---

@adamgreig

What do we do for DefaultHandler? #[exception(*)] as currently, or a different attribute name?

I believe #[exception(*)] will be rejected by the rustc parser. #[exception(Default)] or #[exception(DefaultHandler)] are other options.

Does svd2rust swap to using #[interrupt(...)]?

Good question. It's not possible to inline the definition of the attribute in the device crate like we do with macro_rules!. I think our only option would be to put the interrupt attribute in a separate crate. If we do that the attribute will have to include the name of the device crate, e.g. #[interrupt(stm32f103xx, EXTI0)]; this is required because the expansion needs to check that the interrupt exists (i.e. that stm32f103xx::Interrupt::EXTI0 exists).

#[exception(SysTick, state: u32 = 0)] is a bit unusual

I believe that won't parse.

but I don't see a way around needing to specify the initial value

The state must have an initial value.

Syntax for the optional state does seem like it might be a bit messy.

I was going to propose doing the initialization using a constructor, e.g. State::default, then the user only needs to specify the state type in the attribute, e.g. #[exception(SysTick, State)], but that would require the unstable const_fn feature.

(We could add something like .ctors to work around const_fn being unstable; it would basically amount to doing runtime initialization that's guaranteed to complete before main but would involve memory overhead because the statics need to be Option<UserType>. Such feature deserves a separate RFC though.)

[adamgreig]

I believe #[exception(*)] will be rejected by the rustc parser. #[exception(Default)] or #[exception(DefaultHandler)] are other options.

Sure, I feared * might not be valid syntax. #[exception(DefaultHandler)] or even #[default_handler] would be my preference.

Shame about the svd2rust bit. Having to put the crate name in the attribute is a bit noisy. Why can't it be inlined in the crate in the same way it presumably would be for cortex-m?

We could add something like .ctors to work around const_fn being unstable

Perhaps this convenient state functionality could be unstable-only until const_fn is stable, since in the meantime the user can always do it themselves with unsafe? Maybe we could even continue using a by-example macro to provide the safe wrapper to the mutable state, while moving to the proc macro for declaring the actual handler?

#[exception(SysTick)]
with_state!(u32 = 0, |count| {
    *count += 1
});

[japaric]

I have put up a PoC implementation in PR #90.

[japaric]

This was done in PR #90.