[WIP] add entry2 attribute

[japaric]

this adds an entry2 attribute in the vein of cortex_m_rt::entry. This attribute
lets you safely use static mut variables -- they get transformed into
&'static mut references. Example:

  #[entry2]
fn main() -> ! {
    static mut COUNT: u32 = 0;

    // user code
    let count: &'static mut = COUNT;
}

I did something different in this version: instead of using random identifiers I
wrapped the user entry point into a const item to make it impossible to invoke
it from software (if that were allowed using the static mut would result in
UB).

Just for reference the above code expands into this:

const main: () = {
    #[no_mangle]
    fn main() -> ! {
        let COUNT: &'static mut u32 = {
            static COUNT: u32 = 0;

            &mut COUNT
        };

        // user code
        let count: &'static mut = COUNT;
    }
};

Not using random identifiers means that we avoid a (host) dependency on the rand
crate.

This change is a breaking change because it bumps the Minimum Supported Rust
Version (MSRV) to 1.31.0 -- this crate current MSRV is 1.30.0. The MSRV needs to
be bumped because #[no_mangle] / #[link_section] items inside private
items (like the const item above) only get the right symbol visibility in Rust
1.31.0 (the visibility rules around #[no_mangle] / #[link_section] got
changed in that version).

Instead of naming this attribute: entry2, we could replace the existing
entry! macro but that would be another breaking change.

I didn't add the interrupt / exception attributes because I couldn't find an
example that makes use of interrupts / exceptions

[Disasm]

It's up, but the address is risc-v@

[japaric]

Nice! I'll send a PR to add it the /wg README.

[Disasm]

Thanks!
I hope we can just replace entry! with #[entry] without creating another attribute.
Interrupts are not supported yet: I need to think on how to do this properly in order to handle both standard interrupts and picorv32 IRQs.
Everything else LGTM.

[japaric]

I did something different in this version: instead of using random identifiers I
wrapped the user entry point into a const item to make it impossible to invoke
it from software

Argh, I just realized that you can recursively call yourself and that still results in UB (see example below) so we'll need to switch back to random identifiers.

 #[entry2]
fn main() -> ! {
    static mut COUNT: u32 = 0;

    // user code
    let count: &'static mut = COUNT;

    // unsound: creates another mutable reference to COUNT
    main();
}

[Disasm]

@japaric What's wrong with your example? Infinite recursion is UB anyway, you can do it even without #[entry2].
Also I'm thinking about re-entrant main for multi-core CPU embedded applications. Shouldn't it "just work" in Rust?

[japaric]

What's wrong with your example?

It creates two (or more) mutable references to the COUNT variable; one in the current stack frame and one in the previous stack frame.

Infinite recursion is UB

Sure, but infinite recursion is not needed to break Rust aliasing rules in this case. Here's a more obvious example that has no infinite recursion:

use core::sync::atomic::{AtomicBool, Ordering};

use spin::Mutex;

static CHANNEL: Mutex<Option<&'static mut u32>> = Mutex::new(None);
static ONCE: AtomicBool = AtomicBool::new(true);

#[entry]
fn main() -> ! {
    static mut X: u32 = 0;

    if ONCE.load(Ordering::Relaxed) {
        // first invocation
        ONCE.store(false, Ordering::Relaxed);

        *CHANNEL.lock() = Some(X);

        main()
    } else {
        // second invocation
        let x: &'static mut u32 = X;
        let y: &'static mut u32 = CHANNEL.lock().take().unwrap();

        // `x` and `y` point to the same memory location; this is UB

        // ..
    }

    loop {}
}

Also I'm thinking about re-entrant main for multi-core CPU embedded applications. Shouldn't it "just work" in Rust?

It depends on the exact semantics. If you allow the static mut transform like entry does then you are allowing UB (due to mutable aliasing) in safe Rust.

---

Since this is mainly waiting on a decision from the RISCV team on landing this as it is or replacing the existing entry! macro I'm going to close this PR. When the team has made a decision they can pick up this PR; changing the impl to use random identifiers should be straight forward as it mainly involves copy-pasting the cortex-m-rt implementation.

[Disasm]

Oh, sorry, I'm not attentive enough. I assumed unsafe { &mut COUNT } everywhere.
As for me, hiding this unsafety is not good for two reasons:

• foot-shooting
• potential problems with reentrancy (multi-core applications)

However I still can't understand why not using random names is bad: forbidding main() invocation inside main is useless since you have an entry point with fixed name.

[japaric]

@Disasm maybe you are not familiar with the cortex-m-rt API? Because we use
random identifiers this program doesn't compile:

#[entry]
fn main() -> ! {
    // main(); // ~ERROR: cannot find function `main` in this scope

    loop {}
}

#[exception]
fn SysTick() {
    // main(); // ~ERROR: cannot find function `main` in this scope
}

As the function can't be (safely) called from software it being non-reentrant (due
to the static mut variables) is not an issue.

potential problems with reentrancy (multi-core applications)

I can't see why being reentrant-safe would be hard requirement for multi-core
applications. I have written bare metal, multi-core applications (2x
Cortex-R5) using a similar API and the safe static mut variables and
non-reentrancy were not an issue.

Ultimately, making static mut variables safe is an API design decision that
the RISCV team has to make.

[Disasm]

maybe you are not familiar with the cortex-m-rt API?

I'm not familiar with Cortex-M so it looks strange for me in general. For example, if exception handlers are reentrant, you will have the same problem... But I don't know if they can be. Yet I understand that random identifiers is some sort of protection for the entry point and handlers.

I can't see why being reentrant-safe would be hard requirement for multi-core
applications. I have written bare metal, multi-core applications (2x Cortex-R5) using a similar API and the safe static mut variables and non-reentrancy were not an issue.

It's not a hard requirement, but it's an easy way to implement it. At the moment I have no idea how to use non-reentrant code for this. Could you point to some examples of multi-core applications?

[japaric]

As the function can't be (safely) called from software it being non-reentrant (due
to the static mut variables) is not an issue

(here I meant to say "not being reentrant safe")

For example, if exception handlers are reentrant, you will have the same problem

I thought we were only talking about the entry point (reset handler), which only gets called once by the hardware during the lifetime of the program.

Making local static mut variables safe to use in exception handlers will either work out of the box (e.g. Cortex-M) or require extra work (e.g. Cortex-R); it depends on how the exception mechanism works. I suspect that RISCV model is closer to the Cortex-R model where all interrupts get dispatched by the same handler and the software has to read the interrupt id from some register to figure out what to do next. But if you want interrupt nesting / interrupt prioritization you'll likely end up implementing the Cortex-M exception model where once an interrupt handler starts it's never called again by the hardware until the current instance ends -- in that model (local) static mut variables can be safe.

Could you point to some examples of multi-core applications?

Undocumented code / examples in https://github.com/japaric/ultrascale-plus ; firmware/zup-quickstart/examples/{amp,*-mc-*} are multi-core examples.

[Disasm]

@japaric Thanks! Now it's clear.

But if you want interrupt nesting / interrupt prioritization you'll likely end up implementing the Cortex-M exception model where once an interrupt handler starts it's never called again by the hardware until the current instance ends -- in that model (local) static mut variables can be safe.

This reminds me one misaligned read exception caused by 2-byte (also misaligned) instruction on the RISC-V. There was an exception handler for this, which should hide this "misaligned access is forbidden" nature, calculating proper values for such accesses. Handler starts processing the instruction, which caused the exception, reads it and we get one more misaligned read exception (now in exception handler code), which is processed in the same way. So yes, if you can process an exception while processing the same exception, using static mut local variables is doubtful.

I will try to understand the examples. Thanks again!