Merge #35

35: Prepare v1.0.0 r=jonas-schievink a=adamgreig

I'm opening this PR so we can move discussions forward around v1; I am very happy to have some changes or more feedback before we go ahead with this.

Essentially, this crate is now just `CriticalSection` and `Mutex`, which are widely used and probably won't change without becoming something totally new (e.g. the new mutex-trait crate). There are some known issues (especially CSs don't disable NMI or HardFault) which perhaps could be documented and understood better, but I think are all platform-specific (cortex-m).

In this PR:

* Remove `StaticResource`: it's not been released in any published version so hasn't been proven yet; we could re-add it in a later release or separate crate
* Remove `deny(warnings)` and instead deny them in CI
* Update version to 1.0.0

We'll still want to close off #26. Otherwise I think everything from #22 is covered.

Co-authored-by: Adam Greig <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -5,9 +5,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-### Added
-
-- Added the `StaticResource` trait.
+## [v1.0.0] - 2020-06-23
 
 ### Breaking Changes
 
@@ -77,7 +75,8 @@ YANKED due to a soundness issue: see v0.2.1 for details
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/bare-metal/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/japaric/bare-metal/compare/v1.0.0...HEAD
+[v1.0.0]: https://github.com/japaric/bare-metal/compare/v0.2.5...v1.0.0
 [v0.2.5]: https://github.com/japaric/bare-metal/compare/v0.2.4...v0.2.5
 [v0.2.4]: https://github.com/japaric/bare-metal/compare/v0.2.3...v0.2.4
 [v0.2.3]: https://github.com/japaric/bare-metal/compare/v0.2.2...v0.2.3

Cargo.toml

@@ -7,4 +7,5 @@ keywords = ["bare-metal", "register", "peripheral", "interrupt"]
 license = "MIT OR Apache-2.0"
 name = "bare-metal"
 repository = "https://github.com/rust-embedded/bare-metal"
-version = "0.2.5"
+version = "1.0.0"
+readme = "README.md"

ci/script.sh

@@ -1,5 +1,7 @@
 set -euxo pipefail
 
+export RUSTFLAGS="-D warnings"
+
 main() {
     cargo check --target $TARGET
 

src/lib.rs

@@ -1,8 +1,8 @@
 //! Abstractions common to bare metal systems.
 
 #![deny(missing_docs)]
-#![deny(warnings)]
 #![no_std]
+#![doc(html_root_url="https://docs.rs/bare-metal/1.0")]
 
 use core::cell::UnsafeCell;
 use core::marker::PhantomData;
@@ -12,7 +12,7 @@ use core::marker::PhantomData;
 /// An instance of this type indicates that the current core is executing code within a critical
 /// section. This means that no interrupts must be enabled that could preempt the currently running
 /// code.
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Debug)]
 pub struct CriticalSection<'cs> {
     _0: PhantomData<&'cs ()>,
 }
@@ -47,6 +47,7 @@ impl<'cs> CriticalSection<'cs> {
 /// **This Mutex is only safe on single-core systems.**
 ///
 /// On multi-core systems, a `CriticalSection` **is not sufficient** to ensure exclusive access.
+#[derive(Debug)]
 pub struct Mutex<T> {
     inner: UnsafeCell<T>,
 }
@@ -92,52 +93,5 @@ unsafe impl<T> Sync for Mutex<T> where T: Send {}
 /// }
 /// ```
 #[allow(dead_code)]
+#[doc(hidden)]
 const GH_6: () = ();
-
-/// Trait for static (singleton) resources with managed ownership.
-///
-/// This trait allows application code and libraries to take ownership of resources that exist once
-/// on every core, or once on the entire system.
-///
-/// # Safety
-///
-/// In order to safely implement this trait, the implementor must ensure that:
-/// - A call to `take()` or `steal()` atomically ensures that no further call to `take()` will
-///   succeed. This is commonly accomplished by using a static `AtomicBool` variable and a
-///   compare-and-swap operation or a critical section.
-/// - It is impossible to link multiple crates containing the synchronization state together. This
-///   is usually accomplished by defining a well-known [`links = "..."`][links] key in the
-///   `Cargo.toml`.
-///
-/// [links]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key
-pub unsafe 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.
-    ///
-    /// This function is intended to be used when it is statically known that the resource is still
-    /// available (for example, in generated code that runs immediately after reset). It generally
-    /// has lower cost than `take().unwrap()`.
-    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.
-    ///
-    /// Contrary to `steal()`, `conjure()` will *not* make future calls to `take()` return `None`.
-    ///
-    /// This function can be used to perform operations on a resource, ignoring any current
-    /// ownership of the resource. The safety of this depends on the specific resource, and on the
-    /// operations performed.
-    unsafe fn conjure() -> Self;
-}