Skip to main content

kh_runtime/
stack.rs

1//! Minimal Darwin-ish process stack bootstrap (argc / argv / env / terminator).
2
3use thiserror::Error;
4
5/// Errors while building a guest stack.
6#[derive(Debug, Error, Clone, PartialEq, Eq)]
7pub enum StackError {
8    /// Stack region is too small for the requested argv/env.
9    #[error("guest stack too small: need {need} bytes, have {have}")]
10    TooSmall {
11        /// Required size in bytes.
12        need: usize,
13        /// Available size in bytes.
14        have: usize,
15    },
16
17    /// Argument or environment string is not representable.
18    #[error("invalid stack string")]
19    InvalidString,
20}
21
22/// Builds a minimal C-like stack image at the high end of `stack_mem`.
23///
24/// Layout (low → high addresses toward `sp` growing down):
25/// ```text
26///   [strings: argv bytes, env bytes]
27///   [padding to 16-byte align]
28///   argc
29///   argv[0..n]
30///   NULL
31///   envp[0..m]
32///   NULL
33///   NULL   // empty Apple/aux terminator
34/// ```
35///
36/// Returns the guest stack pointer (16-byte aligned) that should be loaded into
37/// `sp` before jumping to the entry point.
38pub fn bootstrap_stack(
39    stack_mem: &mut [u8],
40    stack_guest_base: u64,
41    argv: &[&str],
42    envp: &[&str],
43) -> Result<u64, StackError> {
44    if stack_mem.is_empty() {
45        return Err(StackError::TooSmall { need: 1, have: 0 });
46    }
47
48    // Place strings at the high end, pointers below them.
49    let mut cursor = stack_mem.len();
50    let mut argv_addrs = Vec::with_capacity(argv.len());
51    let mut env_addrs = Vec::with_capacity(envp.len());
52
53    for s in argv.iter().rev() {
54        let addr = push_cstr(stack_mem, stack_guest_base, &mut cursor, s)?;
55        argv_addrs.push(addr);
56    }
57    argv_addrs.reverse();
58
59    for s in envp.iter().rev() {
60        let addr = push_cstr(stack_mem, stack_guest_base, &mut cursor, s)?;
61        env_addrs.push(addr);
62    }
63    env_addrs.reverse();
64
65    // Align cursor down to 16 bytes for the pointer block.
66    cursor &= !0xF;
67
68    // Pointer block size: argc + argv* + NULL + env* + NULL + apple NULL
69    let n_ptrs = argv_addrs
70        .len()
71        .saturating_add(env_addrs.len())
72        .saturating_add(4); // argc + argv NULL + env NULL + apple NULL
73    let ptr_bytes = n_ptrs.saturating_mul(8);
74    let need = ptr_bytes;
75    if cursor < need {
76        return Err(StackError::TooSmall {
77            need: need.saturating_add(stack_mem.len().saturating_sub(cursor)),
78            have: stack_mem.len(),
79        });
80    }
81    cursor = cursor.saturating_sub(need);
82    // Re-align after subtract.
83    cursor &= !0xF;
84    // Recompute if alignment ate space — rebuild pointer block at final cursor.
85    let ptr_start = cursor;
86    let mut off = ptr_start;
87
88    write_u64(stack_mem, off, u64::try_from(argv.len()).unwrap_or(0))?;
89    off = off.saturating_add(8);
90
91    for &a in &argv_addrs {
92        write_u64(stack_mem, off, a)?;
93        off = off.saturating_add(8);
94    }
95    write_u64(stack_mem, off, 0)?;
96    off = off.saturating_add(8);
97
98    for &a in &env_addrs {
99        write_u64(stack_mem, off, a)?;
100        off = off.saturating_add(8);
101    }
102    write_u64(stack_mem, off, 0)?;
103    off = off.saturating_add(8);
104
105    // Empty Apple vector terminator.
106    write_u64(stack_mem, off, 0)?;
107
108    let sp_offset = u64::try_from(ptr_start).map_err(|_| StackError::InvalidString)?;
109    Ok(stack_guest_base.saturating_add(sp_offset))
110}
111
112fn push_cstr(
113    mem: &mut [u8],
114    guest_base: u64,
115    cursor: &mut usize,
116    s: &str,
117) -> Result<u64, StackError> {
118    let bytes = s.as_bytes();
119    let need = bytes.len().saturating_add(1);
120    if *cursor < need {
121        return Err(StackError::TooSmall {
122            need,
123            have: *cursor,
124        });
125    }
126    *cursor = cursor.saturating_sub(need);
127    let start = *cursor;
128    let Some(dst) = mem.get_mut(start..start.saturating_add(need)) else {
129        return Err(StackError::InvalidString);
130    };
131    let Some((last, data)) = dst.split_last_mut() else {
132        return Err(StackError::InvalidString);
133    };
134    if data.len() != bytes.len() {
135        return Err(StackError::InvalidString);
136    }
137    data.copy_from_slice(bytes);
138    *last = 0;
139    let off = u64::try_from(start).map_err(|_| StackError::InvalidString)?;
140    Ok(guest_base.saturating_add(off))
141}
142
143fn write_u64(mem: &mut [u8], off: usize, value: u64) -> Result<(), StackError> {
144    let end = off.saturating_add(8);
145    let Some(slot) = mem.get_mut(off..end) else {
146        return Err(StackError::TooSmall {
147            need: end,
148            have: mem.len(),
149        });
150    };
151    slot.copy_from_slice(&value.to_le_bytes());
152    Ok(())
153}
154
155#[cfg(test)]
156#[allow(clippy::expect_used, clippy::unwrap_used)]
157mod tests {
158    use super::*;
159
160    #[test]
161    fn stack_has_argc_and_argv0() {
162        let mut mem = vec![0_u8; 4096];
163        let base = 0x0000_7FF0_0000_0000_u64;
164        let sp = bootstrap_stack(&mut mem, base, &["prog", "a"], &[]).expect("stack");
165        assert!(sp.is_multiple_of(16));
166        assert!(sp >= base);
167        assert!(sp < base + 4096);
168
169        let off = usize::try_from(sp - base).unwrap();
170        let argc = u64::from_le_bytes(mem.get(off..off + 8).unwrap().try_into().unwrap());
171        assert_eq!(argc, 2);
172        let argv0_ptr = u64::from_le_bytes(mem.get(off + 8..off + 16).unwrap().try_into().unwrap());
173        assert!(argv0_ptr >= base);
174        let s_off = usize::try_from(argv0_ptr - base).unwrap();
175        assert_eq!(mem.get(s_off..s_off + 4).unwrap(), b"prog");
176    }
177}