someboot 0.4.1

Sparreal OS kernel
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

use core::{
    marker::PhantomData,
    sync::atomic::{AtomicU8, AtomicUsize, Ordering},
};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(u8)]
enum OwnershipState {
    Early        = 0,
    Preparing    = 1,
    Runtime      = 2,
    FailedClosed = 3,
}

impl OwnershipState {
    fn from_raw(raw: u8) -> Self {
        match raw {
            0 => Self::Early,
            1 => Self::Preparing,
            2 => Self::Runtime,
            3 => Self::FailedClosed,
            _ => unreachable!("invalid console ownership state"),
        }
    }
}

/// Error returned by an invalid early/runtime console ownership transition.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum ConsoleHandoffError {
    /// The requested transition is not valid from the current ownership state.
    #[error("invalid console ownership transition")]
    InvalidState,
}

static OWNERSHIP: AtomicU8 = AtomicU8::new(OwnershipState::Early as u8);
static EARLY_ACCESS_IN_FLIGHT: AtomicUsize = AtomicUsize::new(0);

pub(super) struct EarlyAccessGuard {
    counted: bool,
    _not_send: PhantomData<*mut ()>,
}

impl Drop for EarlyAccessGuard {
    fn drop(&mut self) {
        if self.counted {
            EARLY_ACCESS_IN_FLIGHT.fetch_sub(1, Ordering::Release);
        }
    }
}

#[cfg(not(test))]
fn synchronization_available() -> bool {
    // AArch64 exclusive atomics are not reliable before MMU enablement. The
    // transition itself is a post-MMU runtime operation, while the pre-MMU
    // console remains single-core and bypasses these atomic words entirely.
    crate::mem::mmu::is_mmu_enabled()
}

#[cfg(test)]
const fn synchronization_available() -> bool {
    true
}

pub(super) fn try_enter_early() -> Option<EarlyAccessGuard> {
    if !synchronization_available() {
        return Some(EarlyAccessGuard {
            counted: false,
            _not_send: PhantomData,
        });
    }

    if OwnershipState::from_raw(OWNERSHIP.load(Ordering::Acquire)) != OwnershipState::Early {
        return None;
    }
    EARLY_ACCESS_IN_FLIGHT.fetch_add(1, Ordering::AcqRel);
    if OwnershipState::from_raw(OWNERSHIP.load(Ordering::Acquire)) == OwnershipState::Early {
        Some(EarlyAccessGuard {
            counted: true,
            _not_send: PhantomData,
        })
    } else {
        EARLY_ACCESS_IN_FLIGHT.fetch_sub(1, Ordering::Release);
        None
    }
}

/// Stops new early-console accesses and waits for in-flight accesses to leave.
pub fn begin() -> Result<(), ConsoleHandoffError> {
    if !synchronization_available() {
        return Err(ConsoleHandoffError::InvalidState);
    }
    OWNERSHIP
        .compare_exchange(
            OwnershipState::Early as u8,
            OwnershipState::Preparing as u8,
            Ordering::AcqRel,
            Ordering::Acquire,
        )
        .map_err(|_| ConsoleHandoffError::InvalidState)?;

    while EARLY_ACCESS_IN_FLIGHT.load(Ordering::Acquire) != 0 {
        core::hint::spin_loop();
    }
    Ok(())
}

/// Publishes successful runtime ownership after configuration and routing.
pub fn commit() -> Result<(), ConsoleHandoffError> {
    OWNERSHIP
        .compare_exchange(
            OwnershipState::Preparing as u8,
            OwnershipState::Runtime as u8,
            Ordering::AcqRel,
            Ordering::Acquire,
        )
        .map(|_| ())
        .map_err(|_| ConsoleHandoffError::InvalidState)
}

/// Restores early ownership after a failure known to have restored hardware.
pub fn rollback() -> Result<(), ConsoleHandoffError> {
    OWNERSHIP
        .compare_exchange(
            OwnershipState::Preparing as u8,
            OwnershipState::Early as u8,
            Ordering::AcqRel,
            Ordering::Acquire,
        )
        .map(|_| ())
        .map_err(|_| ConsoleHandoffError::InvalidState)
}

/// Permanently prevents low-level register access after an uncertain failure.
pub fn fail_closed() {
    OWNERSHIP.store(OwnershipState::FailedClosed as u8, Ordering::Release);
    while EARLY_ACCESS_IN_FLIGHT.load(Ordering::Acquire) != 0 {
        core::hint::spin_loop();
    }
}

#[cfg(test)]
pub(super) fn reset() {
    EARLY_ACCESS_IN_FLIGHT.store(0, Ordering::Release);
    OWNERSHIP.store(OwnershipState::Early as u8, Ordering::Release);
}

#[cfg(test)]
pub(super) fn state() -> u8 {
    OWNERSHIP.load(Ordering::Acquire)
}

#[cfg(test)]
pub(super) const EARLY: u8 = OwnershipState::Early as u8;
#[cfg(test)]
pub(super) const PREPARING: u8 = OwnershipState::Preparing as u8;
#[cfg(test)]
pub(super) const RUNTIME: u8 = OwnershipState::Runtime as u8;
#[cfg(test)]
pub(super) const FAILED_CLOSED: u8 = OwnershipState::FailedClosed as u8;