Clarify / Document / Redesign the Peripherals::{take, steal} API

[jonas-schievink]

In #169, I wanted to add a function SCB::steal that unsafely obtains an instance of the SCB peripheral. While this API isn't really necessary since Peripherals::steal().SCB does the same, it is slightly more convenient.

One issue that came up was that Peripherals::steal() is not documented to have any relationship with Peripherals::take(). In reality, calling steal() will cause take() to return None, and this is relied on by RTFM for soundness! We definitely need to document this, but it might also be useful to have an unsafe steal()-like API that does not affect the "taken flag" at all (this is what my SCB::steal() would've been, for example).

Another possible improvement on this API would be to move it to a trait, which could help with https://github.com/rust-embedded/cortex-m-rt/issues/180. If we had that, we could have cortex-m-rt steal and pass arbitrary implementors of that trait to the #[entry] point of the app, moving one nice pattern enabled by RTFM to the non-RTFM embedded world.

[jonas-schievink]

Strawman proposal:

trait StaticResource: Sized {
    /// Obtains ownership of this resource singleton and makes it unavailable to
    /// future callers of `take()`.
    ///
    /// If `take()` or `steal()` have been called before, this returns `None`.
    fn take() -> Option<Self>;
    
    /// Obtains an instance of this resource and makes all future calls to
    /// `take()` return `None`.
    ///
    /// This will not check if `take()` or `steal()` have already been called
    /// before. It is the caller's responsibility to use the returned instance
    /// in a safe way that does not conflict with other instances.
    unsafe fn steal() -> Self;
    
    /// Unsafely obtains an instance of this resource.
    ///
    /// This will not check if `take()` or `steal()` have already been called
    /// before. It is the caller's responsibility to use the returned instance
    /// in a safe way that does not conflict with other instances.
    unsafe fn conjure() -> Self;
}

[jonas-schievink]

We could also make it an unsafe trait, and require implementors to ensure that the crate containing the "taken flag" uses a well-known links = "..." value in its manifest. This would make it impossible to link multiple crates (or crate versions) together that provide the same static resource (which would allow unsoundly acquiring multiple instances of the same hardware resource).

[jonas-schievink]

Added the trait to bare-metal in rust-embedded/bare-metal#27

[jonas-schievink]

rust-embedded/bare-metal#27 has been reverted

[agausmann]

I was just passing by, but I had a realization that might be helpful - The current definition of steal(), which affects future calls to take(), can be implemented as take().unwrap_or_else(|| conjure()).

Impacts:

Peripherals::steal() is not documented to have any relationship with Peripherals::take() ... this is relied on by RTFM for soundness

If conjure() was provided instead of steal(), there would be no relationship to document; if you wanted to affect future calls to take(), you can do so explicitly with the expression I gave above. Especially when soundness is a concern, why rely on documentation when the code can describe itself?

[agausmann]

Either way it's probably good to state in the docs how it affects take(), whether or not it does.

[pwnorbitals]

https://app.bountysource.com/issues/86724107-clarify-document-redesign-the-peripherals-take-steal-api