compile on stable

[japaric]

with these changes this crate compiles on stable

[japaric]

It also appears to fix all the LLD issues reported in #53. cc @jcsoo

[adamgreig]

This should probably be MemManage?

[jcsoo]

Tried it out and it works for me.

[japaric]

Changes from cortex-m-rt v0.4.x and stable-embedded-rust that warrant some discussion:

• The user must define both DefaultHandler and HardFault.

• The HardFault handler is now a diverging function (fn(..) -> !). The rationale is that
  returning from the hard fault handler can be (is usually?) UB. A diverging function prevents that
  scenario.

• Now, only the HardFault handler has access to the previous stack frame. In cortex-m-rt
DefaultHandler had access to the previous stack frame.

• DefaultHandler now takes a u8 argument. This integer is the exception number and can be used
  to identify which exception / interrupt is being serviced.

• interrupts! can be used to bind all the potential interrupt handlers (240) to DefaultHandler.
  This can be used to write device agnostic programs. In cortex-m-rt one had to explicitly declare
  a static variable and place it in the .vector_table.interrupts section; interrupts! is (less
  error prone) sugar for that.

Unresolved questions:

• Do we want to apply the divergent function trick to the other fault handlers; that is to
  UsageFault, BusFault and MemManage (MPU fault?)? Is it safe (not UB) to return from those
  fault handlers? An idea here could be to make it safe to use a divergent function but unsafe to
  use a non divergent function. See below:

// You can pick
exception!(BusFault, bf);

fn bf() -> ! {
    // ..
}

// OR this
exception!(unsafe BusFault, bf);

fn bf()  {
    // ..
    return;
}

• Do we want one default handler for Cortex-M exceptions and a different default handler for
  interrupts? That is DefaultExceptionHandler and DefaultInterruptHandler. (I don't see much
  gain from such split)

Bikeshedding:

• should main! be renamed to entry!? The macro defines the user program entry point, which doesn't need to be named main.

TODO:

• Add back exception / interrupt local data (locals in the old exception! macro)

• Document the overridable symbols (_foo) and the private symbols (__foo). The later will
  be documented for inspection / diagnostic purposes (objdump, nm, etc.).

• Document that exception! and interrupts! must be called in the root of the crate, and if possible add (reachability) checks for that.

cc @thejpster

[japaric]

Bikeshedding: should main! be renamed to entry!? The macro defines the user program entry point, which doesn't need to be named main.

[japaric]

Future improvements:

Macros 1.2 is planned for the 1.28 release and will allow custom attributes (i.e. #[foo]; today we only allow custom derive on stable: #[derive(Foo)]), so we could in the future replace the exception! macro for an #[exception] attribute which would slightly reduce boilerplate / look more natural:

// Today
#[macro_use(exception)]
extern crate cortex_m_rt;

exception!(SysTick, sys_tick);

fn sys_tick() { .. }

// Macros 1.2
extern crate cortex_m_rt;

use cortex_m_rt::exception;

#[exception(SysTick)]
fn sys_tick() { .. }

// or even
#[exception]
fn SysTick() { .. }

We could do the same with main! macro; we could replace it with an #[entry] attribute.

[jcsoo]

Do we want one default handler for Cortex-M exceptions and a different default handler for
interrupts? That is DefaultExceptionHandler and DefaultInterruptHandler. (I don't see much
gain from such split)

In my use case, I want all interrupts to optionally go to a shared handler, but I'd prefer to have individual exception handlers as well as a DefaultHandler for everything else.

Is it possible to have the interrupts! macro bind to a specific handler rather than DefaultHandler?

[japaric]

Is it possible to have the interrupts! macro bind to a specific handler rather than DefaultHandler?

It could but most applications are not going to use the interrupts! macro; they are going to use the __INTERRUPTS variable provided by a device crate (generated using svd2rust) or an equivalent to it.

So, I guess my question actually is: should svd2rust bind the device specific interrupts to DefaultHandler or to some other handler (DefaultInterruptHandler)? Though if we go down that route we'll probably want to add EXTERN(DefaultInterruptHandler) to link.x to prevent the linker from dropping the symbol.

If you are using something other than svd2rust you can do whatever you want; you don't need to use interrupts! (svd2rust doesn't use interrupts! either)

[japaric]

bors try

[bors]

try

Build succeeded

• continuous-integration/travis-ci/push

[japaric]

bors r+

[bors]

Build succeeded

• continuous-integration/travis-ci/push