Skip to main content

esp_hal/interrupt/ipc/
request.rs

1//! The part of the IPC that every esp-hal copy shares.
2//!
3//! This file uses `core` and `portable_atomic` only, because the host tests include it.
4// esp-hal copies without `rt` read requests that the copy with `rt` writes. The layout of
5// `IpcRequest`, the encodings below and `seq_reached` must stay stable.
6
7use core::ptr;
8
9use portable_atomic::{AtomicPtr, AtomicU32, Ordering};
10
11/// The position of the sequence number in `status` and in the result of a post.
12pub(crate) const SEQ_SHIFT: u32 = 5;
13
14/// The outcome bits of `status`.
15pub(crate) const OUTCOME_MASK: u32 = 0b11;
16/// The run ended. Each other outcome means that the target CPU stopped before the run.
17pub(crate) const DONE: u32 = 0;
18
19/// The post queued a run, or joined a pending run.
20pub(crate) const POST_OK: u32 = 0;
21/// The target CPU does not take IPC interrupts. Each other result means that the request is busy.
22pub(crate) const POST_OFFLINE: u32 = 1;
23/// The result bits of the return value of a post.
24pub(crate) const POST_RESULT_MASK: u32 = (1 << SEQ_SHIFT) - 1;
25
26/// A function that [`Ipc::post`][super::Ipc::post] runs on a CPU, and the state of its runs.
27///
28/// The IPC interrupt of the target CPU calls `func` at
29/// [`Priority::min`][crate::interrupt::Priority::min]. A request must be `'static`, because the IPC
30/// can read and write it at any time after the first post. A request has at most one pending run.
31/// Two concurrent runs need two requests.
32///
33/// `func` must:
34///
35/// - return,
36/// - not use the floating-point registers,
37/// - not enable interrupts, and not lower the run level,
38/// - not wait for a run on its own CPU.
39///
40/// A caller can stop its wait before the run starts, so `func` can run late. `func` must then find
41/// its protocol state stale, and do nothing.
42#[repr(C)]
43#[derive(Debug)]
44pub struct IpcRequest {
45    pub(super) next: AtomicPtr<IpcRequest>,
46    /// The state of the pending and the running run. Only the copy with `rt` reads the bits. A
47    /// request that no post took holds 0.
48    pub(super) word: AtomicU32,
49    pub(super) status: AtomicU32,
50    pub(super) func: extern "C" fn(),
51}
52
53impl IpcRequest {
54    /// Creates a request that runs `func`.
55    pub const fn new(func: extern "C" fn()) -> Self {
56        Self {
57            next: AtomicPtr::new(ptr::null_mut()),
58            word: AtomicU32::new(0),
59            status: AtomicU32::new(0),
60            func,
61        }
62    }
63}
64
65/// Returns `true` if the sequence number in the `seq` bits of `current` reached the one of
66/// `target`.
67///
68/// Sequence numbers have 27 bits and wrap. The bits of `target` below the `seq` bits are 0.
69#[inline(always)]
70pub(crate) fn seq_reached(current: u32, target: u32) -> bool {
71    current.wrapping_sub(target) as i32 >= 0
72}
73
74/// Returns the outcome of the run of `request` with the `seq` bits `seq`, or `None` if the run
75/// did not end.
76pub(crate) fn poll(request: &IpcRequest, seq: u32) -> Option<u32> {
77    let status = request.status.load(Ordering::Acquire);
78    seq_reached(status, seq).then_some(status & OUTCOME_MASK)
79}