bare_metal/
lib.rs

1//! Abstractions common to bare metal systems.
2
3#![deny(missing_docs)]
4#![no_std]
5#![doc(html_root_url="https://docs.rs/bare-metal/1.0")]
6
7use core::cell::UnsafeCell;
8use core::marker::PhantomData;
9
10/// Critical section token.
11///
12/// An instance of this type indicates that the current core is executing code within a critical
13/// section. This means that no interrupts must be enabled that could preempt the currently running
14/// code.
15#[derive(Clone, Copy, Debug)]
16pub struct CriticalSection<'cs> {
17    _0: PhantomData<&'cs ()>,
18}
19
20impl<'cs> CriticalSection<'cs> {
21    /// Creates a critical section token.
22    ///
23    /// This method is meant to be used to create safe abstractions rather than being directly used
24    /// in applications.
25    ///
26    /// # Safety
27    ///
28    /// This must only be called when the current core is in a critical section. The caller must
29    /// ensure that the returned instance will not live beyond the end of the critical section.
30    /// Moreover, the caller must use adequate fences to prevent the compiler from moving the
31    /// instructions inside the critical section to the outside of it. Sequentially consistent fences are
32    /// suggested immediately after entry and immediately before exit from the critical section.
33    ///
34    /// Note that the lifetime `'cs` of the returned instance is unconstrained. User code must not
35    /// be able to influence the lifetime picked for this type, since that might cause it to be
36    /// inferred to `'static`.
37    #[inline(always)]
38    pub unsafe fn new() -> Self {
39        CriticalSection { _0: PhantomData }
40    }
41}
42
43/// A "mutex" based on critical sections.
44///
45/// # Safety
46///
47/// **This Mutex is only safe on single-core systems.**
48///
49/// On multi-core systems, a `CriticalSection` **is not sufficient** to ensure exclusive access.
50#[derive(Debug)]
51pub struct Mutex<T> {
52    inner: UnsafeCell<T>,
53}
54
55impl<T> Mutex<T> {
56    /// Creates a new mutex.
57    pub const fn new(value: T) -> Self {
58        Mutex {
59            inner: UnsafeCell::new(value),
60        }
61    }
62
63    /// Gets a mutable reference to the contained value when the mutex is already uniquely borrowed.
64    ///
65    /// This does not require locking or a critical section since it takes `&mut self`, which
66    /// guarantees unique ownership already. Care must be taken when using this method to
67    /// **unsafely** access `static mut` variables, appropriate fences must be used to prevent
68    /// unwanted optimizations.
69    pub fn get_mut(&mut self) -> &mut T {
70        unsafe { &mut *self.inner.get() }
71    }
72
73    /// Unwraps the contained value, consuming the mutex.
74    pub fn into_inner(self) -> T {
75        self.inner.into_inner()
76    }
77
78    /// Borrows the data for the duration of the critical section.
79    pub fn borrow<'cs>(&'cs self, _cs: CriticalSection<'cs>) -> &'cs T {
80        unsafe { &*self.inner.get() }
81    }
82}
83
84// NOTE A `Mutex` can be used as a channel so the protected data must be `Send`
85// to prevent sending non-Sendable stuff (e.g. access tokens) across different
86// execution contexts (e.g. interrupts)
87unsafe impl<T> Sync for Mutex<T> where T: Send {}
88
89/// ``` compile_fail
90/// fn bad(cs: bare_metal::CriticalSection) -> &u32 {
91///     let x = bare_metal::Mutex::new(42u32);
92///     x.borrow(cs)
93/// }
94/// ```
95#[allow(dead_code)]
96#[doc(hidden)]
97const GH_6: () = ();
bare_metal/lib.rs

bare_metal/
lib.rs
