esp-hal 1.1.0

Bare-metal HAL for Espressif devices
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Under construction: This is public only for tests, please avoid using it
//! directly.

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

#[cfg(riscv)]
use esp_sync::raw::SingleCoreInterruptLock;
use esp_sync::{GenericRawMutex, RestoreState, raw::RawLock};

use crate::interrupt::{ElevatedRunLevel, Priority, RunLevel};

/// A lock that disables interrupts below a certain priority.
pub struct PriorityLock(pub RunLevel);

impl PriorityLock {
    fn current_priority() -> RunLevel {
        RunLevel::current()
    }

    /// Prevents interrupts above `level` from firing and returns the
    /// current run level.
    unsafe fn change_current_level(level: RunLevel) -> RunLevel {
        unsafe { RunLevel::change(level) }
    }
}

impl RawLock for PriorityLock {
    unsafe fn enter(&self) -> RestoreState {
        #[cfg(riscv)]
        if self.0 == Priority::max() {
            return unsafe { SingleCoreInterruptLock.enter() };
        }

        let prev_level = unsafe { Self::change_current_level(self.0) };
        assert!(prev_level <= self.0);

        // Ensure no subsequent memory accesses are reordered to before interrupts are
        // disabled.
        compiler_fence(Ordering::SeqCst);

        unsafe { RestoreState::new(u32::from(prev_level)) }
    }

    unsafe fn exit(&self, token: RestoreState) {
        #[cfg(riscv)]
        if self.0 == Priority::max() {
            return unsafe { SingleCoreInterruptLock.exit(token) };
        }
        assert!(Self::current_priority() <= self.0);
        // Ensure no preceeding memory accesses are reordered to after interrupts are
        // enabled.
        compiler_fence(Ordering::SeqCst);

        let level = unwrap!(RunLevel::try_from_u32(token.inner()));
        unsafe { Self::change_current_level(level) };
    }
}

/// A mutual exclusion primitive that only disables a limited range of
/// interrupts.
///
/// Trying to acquire or release the lock at a higher priority level will panic.
pub struct RawPriorityLimitedMutex {
    inner: GenericRawMutex<PriorityLock>,
}

impl RawPriorityLimitedMutex {
    /// Create a new lock that is accessible at or below the given `priority`.
    pub const fn new(priority: Priority) -> Self {
        Self {
            inner: GenericRawMutex::new(PriorityLock(RunLevel::Interrupt(
                ElevatedRunLevel::from_priority(priority),
            ))),
        }
    }

    /// Runs the callback with this lock locked.
    pub fn lock<R>(&self, f: impl FnOnce() -> R) -> R {
        self.inner.lock(f)
    }
}

unsafe impl embassy_sync::blocking_mutex::raw::RawMutex for RawPriorityLimitedMutex {
    #[allow(clippy::declare_interior_mutable_const)]
    const INIT: Self = Self::new(Priority::max());

    fn lock<R>(&self, f: impl FnOnce() -> R) -> R {
        self.inner.lock(f)
    }
}

#[cfg(impl_critical_section)]
#[cfg(feature = "rt")]
mod critical_section {
    struct CriticalSection;

    critical_section::set_impl!(CriticalSection);

    static CRITICAL_SECTION: esp_sync::RawMutex = esp_sync::RawMutex::new();

    unsafe impl critical_section::Impl for CriticalSection {
        unsafe fn acquire() -> critical_section::RawRestoreState {
            unsafe { CRITICAL_SECTION.acquire().inner() }
        }

        unsafe fn release(token: critical_section::RawRestoreState) {
            unsafe {
                CRITICAL_SECTION.release(esp_sync::RestoreState::new(token));
            }
        }
    }
}