Skip to main content

kh_runtime/cpu/
host_slot.rs

1//! Per-host-thread state reachable without host `TPIDR_EL0` / Rust TLS.
2//!
3//! Guest code may point `TPIDR_EL0` at freestanding Darwin TSD. While that is
4//! live, `thread_local!` and glibc TLS are unusable. Everything needed on the
5//! guest→host boundary is stored here, keyed by the OS thread id (`gettid` on
6//! Linux, `pthread_self` elsewhere).
7//!
8//! **Hot path under guest TPIDR** must not allocate (glibc malloc may touch TLS).
9//! Insert/claim slots only while host TPIDR is live (prepare paths).
10//!
11//! ## A2 (enter + alt merge)
12//!
13//! Hypercall entry uses [`prepare_enter_under_guest`]: one `gettid` + one map
14//! lock updates TLS and returns the pre-mapped alt-stack top so asm need not
15//! call `kh_host_alt_sp` (second gettid). Leave still uses `gettid` (guest-safe).
16//! No host `thread_local!` on this path — probing TLS under guest TPIDR SEGV's
17//! even when the cell is empty (invariant 10).
18#![allow(unsafe_code)]
19
20use std::collections::HashMap;
21use std::sync::{Mutex, OnceLock};
22
23/// Host glibc / guest TSD snapshots for one OS thread.
24#[derive(Clone, Copy, Debug, Default)]
25pub struct TlsSlot {
26    /// Host `TPIDR_EL0` captured before any guest `msr`.
27    pub host_tpidr: u64,
28    /// Last guest `TPIDR_EL0` (refreshed via `mrs` on host entry).
29    pub guest_tpidr: u64,
30    /// True after prepare.
31    pub active: bool,
32}
33
34/// Hypercall alt stack (host private map).
35#[derive(Clone, Copy, Debug)]
36pub struct AltStackSlot {
37    pub base: *mut u8,
38    pub len: usize,
39    pub top: u64,
40}
41
42// SAFETY: each slot is only mutated from its owning OS thread; the map lock
43// serializes insert/remove. Pointers are private anonymous maps.
44unsafe impl Send for AltStackSlot {}
45
46/// Worker exit trampoline + guest pthread identity.
47#[derive(Clone, Copy, Debug, Default)]
48pub struct WorkerSlot {
49    pub exit_pc: u64,
50    pub exit_sp: u64,
51    pub has_exit: bool,
52    pub guest_pthread: u64,
53    pub guest_tid: u64,
54}
55
56#[derive(Default)]
57struct ThreadSlot {
58    tls: TlsSlot,
59    alt: Option<AltStackSlot>,
60    worker: WorkerSlot,
61}
62
63fn slots() -> &'static Mutex<HashMap<u64, ThreadSlot>> {
64    static SLOTS: OnceLock<Mutex<HashMap<u64, ThreadSlot>>> = OnceLock::new();
65    SLOTS.get_or_init(|| Mutex::new(HashMap::new()))
66}
67
68/// Stable key for the current OS thread (does not touch `TPIDR_EL0`).
69///
70/// Safe under guest TPIDR (raw syscall / `pthread_self` cookie).
71#[must_use]
72pub fn os_tid() -> u64 {
73    #[cfg(target_os = "linux")]
74    {
75        // SAFETY: `gettid` returns a scalar; no TLS required.
76        let raw = unsafe { libc::syscall(libc::SYS_gettid) };
77        u64::try_from(raw).unwrap_or(0)
78    }
79    #[cfg(not(target_os = "linux"))]
80    {
81        // SAFETY: pthread_self is a thread cookie for map keying.
82        let p = unsafe { libc::pthread_self() };
83        #[allow(clippy::as_conversions)]
84        {
85            p as u64
86        }
87    }
88}
89
90/// Guest-safe hypercall enter prep: one `gettid` + one lock.
91#[derive(Clone, Copy, Debug)]
92pub struct EnterPrep {
93    pub host_tpidr: u64,
94    pub tid: u64,
95    /// Pre-mapped hypercall alt stack top, or 0 if missing.
96    pub alt_top: u64,
97}
98
99/// Under **guest** TPIDR: `gettid` + map lock; update TLS; read alt top if any.
100///
101/// Does **not** touch `thread_local!`.
102pub fn prepare_enter_under_guest(cur_tpidr: u64) -> Option<EnterPrep> {
103    let tid = os_tid();
104    let mut guard = slots()
105        .lock()
106        .unwrap_or_else(std::sync::PoisonError::into_inner);
107    let slot = guard.get_mut(&tid)?;
108    let m = &mut slot.tls;
109    if !m.active {
110        m.host_tpidr = cur_tpidr;
111        m.active = true;
112    } else if cur_tpidr != m.host_tpidr {
113        m.guest_tpidr = cur_tpidr;
114    }
115    let alt_top = slot.alt.map_or(0, |s| s.top);
116    Some(EnterPrep {
117        host_tpidr: m.host_tpidr,
118        tid,
119        alt_top,
120    })
121}
122
123/// Insert/update while **host** TPIDR is live (may allocate).
124fn with_slot_init<R>(f: impl FnOnce(&mut ThreadSlot) -> R) -> R {
125    let tid = os_tid();
126    let mut guard = slots()
127        .lock()
128        .unwrap_or_else(std::sync::PoisonError::into_inner);
129    let slot = guard.entry(tid).or_default();
130    f(slot)
131}
132
133/// Mutate an existing slot only (no HashMap insert — safe under guest TPIDR).
134fn with_slot_existing_mut<R>(f: impl FnOnce(&mut ThreadSlot) -> R) -> Option<R> {
135    let tid = os_tid();
136    let mut guard = slots()
137        .lock()
138        .unwrap_or_else(std::sync::PoisonError::into_inner);
139    let slot = guard.get_mut(&tid)?;
140    Some(f(slot))
141}
142
143/// Read snapshot without insert.
144fn with_slot_existing<R>(f: impl FnOnce(&ThreadSlot) -> R) -> Option<R> {
145    let tid = os_tid();
146    let guard = slots()
147        .lock()
148        .unwrap_or_else(std::sync::PoisonError::into_inner);
149    guard.get(&tid).map(f)
150}
151
152/// Prepare/update TLS fields (host TPIDR live — may create slot).
153pub fn with_tls_init<R>(f: impl FnOnce(&mut TlsSlot) -> R) -> R {
154    with_slot_init(|s| f(&mut s.tls))
155}
156
157/// Mutate TLS on an existing slot only.
158pub fn with_tls_existing_mut<R>(f: impl FnOnce(&mut TlsSlot) -> R) -> Option<R> {
159    with_slot_existing_mut(|s| f(&mut s.tls))
160}
161
162/// Alias for call sites that want an explicit guest-safe name (same as mut).
163#[inline]
164pub fn with_tls_existing_mut_guest_safe<R>(f: impl FnOnce(&mut TlsSlot) -> R) -> Option<R> {
165    with_tls_existing_mut(f)
166}
167
168#[must_use]
169pub fn tls_get() -> TlsSlot {
170    with_slot_existing(|s| s.tls).unwrap_or_default()
171}
172
173/// Alt stack accessor. Uses existing slot when present (guest-TPIDR safe).
174pub fn with_alt_mut<R>(f: impl FnOnce(&mut Option<AltStackSlot>) -> R) -> R {
175    let tid = os_tid();
176    let mut guard = slots()
177        .lock()
178        .unwrap_or_else(std::sync::PoisonError::into_inner);
179    if let Some(slot) = guard.get_mut(&tid) {
180        return f(&mut slot.alt);
181    }
182    // First touch without prepare — allocate under whatever TLS is current.
183    // Prefer prepare_host_meta first in production paths.
184    let slot = guard.entry(tid).or_default();
185    f(&mut slot.alt)
186}
187
188/// Worker slot accessor.
189pub fn with_worker_mut<R>(f: impl FnOnce(&mut WorkerSlot) -> R) -> R {
190    let tid = os_tid();
191    let mut guard = slots()
192        .lock()
193        .unwrap_or_else(std::sync::PoisonError::into_inner);
194    if let Some(slot) = guard.get_mut(&tid) {
195        return f(&mut slot.worker);
196    }
197    let slot = guard.entry(tid).or_default();
198    f(&mut slot.worker)
199}
200
201#[must_use]
202pub fn worker_get() -> WorkerSlot {
203    with_slot_existing(|s| s.worker).unwrap_or_default()
204}
205
206/// Drop this OS thread's slot (worker exit). Caller unmaps alt stack first.
207pub fn clear_current() {
208    let tid = os_tid();
209    let mut guard = slots()
210        .lock()
211        .unwrap_or_else(std::sync::PoisonError::into_inner);
212    let _removed = guard.remove(&tid);
213}
214
215#[cfg(test)]
216mod tests {
217    use super::*;
218
219    #[test]
220    #[allow(clippy::expect_used)]
221    fn prepare_enter_updates_guest_snapshot() {
222        with_tls_init(|m| {
223            m.active = true;
224            m.host_tpidr = 0xabcd;
225            m.guest_tpidr = 0;
226        });
227        let prep = prepare_enter_under_guest(0xdead).expect("slot");
228        assert_eq!(prep.host_tpidr, 0xabcd);
229        assert_ne!(prep.tid, 0);
230        let snap = tls_get();
231        assert_eq!(snap.guest_tpidr, 0xdead);
232        clear_current();
233    }
234
235    #[test]
236    #[allow(clippy::expect_used)]
237    fn prepare_enter_returns_alt_top() {
238        with_tls_init(|m| {
239            m.active = true;
240            m.host_tpidr = 0x1;
241        });
242        with_alt_mut(|cell| {
243            *cell = Some(AltStackSlot {
244                base: core::ptr::null_mut(),
245                len: 0,
246                top: 0x_dead_beef,
247            });
248        });
249        let prep = prepare_enter_under_guest(0x1).expect("slot");
250        assert_eq!(prep.alt_top, 0x_dead_beef);
251        clear_current();
252    }
253}