Skip to main content

libc_rs/
startup.rs

1//! Process startup state (`argc`, `argv`, `environ`, `auxv`), ELF note, and `_start` entry macro.
2
3use core::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
4
5#[cfg(feature = "alloc")]
6use alloc::vec::Vec;
7
8#[cfg(feature = "alloc")]
9use crate::errno::{EINVAL, Errno, SysResult};
10#[cfg(feature = "alloc")]
11use crate::mem::{c_strlen, memchr};
12#[cfg(feature = "alloc")]
13use crate::sync::FutexMutex;
14
15pub const AT_NULL: u64 = 0;
16pub const AT_PHDR: u64 = 3;
17pub const AT_PHENT: u64 = 4;
18pub const AT_PHNUM: u64 = 5;
19pub const AT_PAGESZ: u64 = 6;
20pub const AT_ENTRY: u64 = 9;
21pub const AT_HWCAP: u64 = 16;
22pub const AT_RANDOM: u64 = 25;
23pub const AT_HWCAP2: u64 = 26;
24pub const AT_EXECFN: u64 = 31;
25
26/// Maximum number of `u64` stack words inspected by [`init_from_stack`].
27pub const MAX_STACK_WORDS: usize = 4096;
28
29/// Default page size when `AT_PAGESZ` is absent or startup state has not been initialized.
30pub const DEFAULT_PAGE_SIZE: usize = 4096;
31
32/// Decoded summary of known auxiliary vector tags.
33#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
34pub struct AuxSummary {
35    pub page_size: usize,
36    pub hwcap: u64,
37    pub hwcap2: u64,
38    pub phdr_addr: u64,
39    pub phent_size: u64,
40    pub phnum: u64,
41    pub entry_addr: u64,
42    pub random_addr: u64,
43    pub execfn_addr: u64,
44}
45
46/// 24-byte ELF note header + 4-byte owner + 4-byte version descriptor.
47#[repr(C, align(4))]
48#[derive(Clone, Copy, Debug, Eq, PartialEq)]
49pub struct ElfNote24 {
50    pub namesz: u32,
51    pub descsz: u32,
52    pub kind: u32,
53    pub name: [u8; 8],
54    pub desc: u32,
55}
56
57const _: () = assert!(core::mem::size_of::<ElfNote24>() == 24);
58
59/// Constructs a 24-byte `ElfNote24` for a 4-byte owner tag.
60#[must_use]
61pub const fn make_elf_note(owner: [u8; 4], kind: u32, version: u32) -> ElfNote24 {
62    ElfNote24 {
63        namesz: 5,
64        descsz: 4,
65        kind,
66        name: [owner[0], owner[1], owner[2], owner[3], 0, 0, 0, 0],
67        desc: version,
68    }
69}
70
71/// Emits a `.note.uk_native` ELF note static.
72#[macro_export]
73macro_rules! declare_native_note {
74    ($static_name:ident, $owner:expr, $kind:expr, $version:expr) => {
75        #[used]
76        #[unsafe(link_section = ".note.uk_native")]
77        static $static_name: $crate::startup::ElfNote24 =
78            $crate::startup::make_elf_note($owner, $kind, $version);
79    };
80}
81
82/// Trait allowing `process_entry!` to accept `()`, `u8`, `i32`, or `Result<(), E>`.
83pub trait EntryOutcome {
84    fn into_exit_code(self) -> i32;
85}
86
87impl EntryOutcome for () {
88    fn into_exit_code(self) -> i32 {
89        0
90    }
91}
92
93impl EntryOutcome for u8 {
94    fn into_exit_code(self) -> i32 {
95        self as i32
96    }
97}
98
99impl EntryOutcome for i32 {
100    fn into_exit_code(self) -> i32 {
101        self
102    }
103}
104
105impl<E> EntryOutcome for core::result::Result<(), E> {
106    fn into_exit_code(self) -> i32 {
107        match self {
108            Ok(()) => 0,
109            Err(_) => 1,
110        }
111    }
112}
113
114unsafe fn parse_stack_words(
115    sp: *const u64,
116    max_words: usize,
117) -> Option<(usize, *const *const u8, *const *const u8, AuxSummary)> {
118    if sp.is_null() || max_words < 4 {
119        return None;
120    }
121
122    let argc = unsafe { *sp } as usize;
123    let mut idx = 1usize;
124
125    let argv_ptr = unsafe { sp.add(idx).cast::<*const u8>() };
126    let mut seen_argv = 0usize;
127    while idx < max_words {
128        let word = unsafe { *sp.add(idx) };
129        idx += 1;
130        if word == 0 {
131            if seen_argv != argc {
132                return None;
133            }
134            break;
135        }
136        seen_argv += 1;
137        if seen_argv > argc {
138            return None;
139        }
140    }
141    if seen_argv != argc || idx >= max_words {
142        return None;
143    }
144
145    let envp_ptr = unsafe { sp.add(idx).cast::<*const u8>() };
146    let mut found_env_end = false;
147    while idx < max_words {
148        let word = unsafe { *sp.add(idx) };
149        idx += 1;
150        if word == 0 {
151            found_env_end = true;
152            break;
153        }
154    }
155    if !found_env_end {
156        return None;
157    }
158
159    let mut summary = AuxSummary::default();
160    while idx + 1 < max_words {
161        let key = unsafe { *sp.add(idx) };
162        let value = unsafe { *sp.add(idx + 1) };
163        idx += 2;
164        if key == AT_NULL {
165            return Some((argc, argv_ptr, envp_ptr, summary));
166        }
167        match key {
168            AT_PHDR => summary.phdr_addr = value,
169            AT_PHENT => summary.phent_size = value,
170            AT_PHNUM => summary.phnum = value,
171            AT_PAGESZ => summary.page_size = value as usize,
172            AT_ENTRY => summary.entry_addr = value,
173            AT_HWCAP => summary.hwcap = value,
174            AT_RANDOM => summary.random_addr = value,
175            AT_HWCAP2 => summary.hwcap2 = value,
176            AT_EXECFN => summary.execfn_addr = value,
177            _ => {}
178        }
179    }
180
181    None
182}
183
184static INITIALIZED: AtomicBool = AtomicBool::new(false);
185static ARGC: AtomicUsize = AtomicUsize::new(0);
186static ARGV_PTR: AtomicUsize = AtomicUsize::new(0);
187static ENVP_PTR: AtomicUsize = AtomicUsize::new(0);
188
189static AUX_PAGE_SIZE: AtomicUsize = AtomicUsize::new(0);
190static AUX_HWCAP: AtomicU64 = AtomicU64::new(0);
191static AUX_HWCAP2: AtomicU64 = AtomicU64::new(0);
192static AUX_PHDR: AtomicU64 = AtomicU64::new(0);
193static AUX_PHENT: AtomicU64 = AtomicU64::new(0);
194static AUX_PHNUM: AtomicU64 = AtomicU64::new(0);
195static AUX_ENTRY: AtomicU64 = AtomicU64::new(0);
196static AUX_RANDOM: AtomicU64 = AtomicU64::new(0);
197static AUX_EXECFN: AtomicU64 = AtomicU64::new(0);
198
199#[cfg(feature = "alloc")]
200type EnvPairs = Vec<(Vec<u8>, Vec<u8>)>;
201
202#[cfg(feature = "alloc")]
203static ENV_TABLE: FutexMutex<Option<EnvPairs>> = FutexMutex::new(None);
204
205/// Parses the initial EL0 process stack at `sp` (`argc`, `argv`, `envp`, `auxv`) and records
206/// process startup state.
207///
208/// # Safety
209///
210/// `sp` must be null or point to a valid EL0 initial stack image readable up to the terminating
211/// `AT_NULL` auxiliary vector entry (bounded by [`MAX_STACK_WORDS`] words), and string pointers
212/// in `argv` / `envp` must remain valid NUL-terminated strings while accessed.
213pub unsafe fn init_from_stack(sp: *const u64) {
214    // SAFETY: Caller guarantees `sp` is null or valid for `parse_stack_words`.
215    if let Some((argc, argv, envp, aux)) = unsafe { parse_stack_words(sp, MAX_STACK_WORDS) } {
216        ARGC.store(argc, Ordering::Relaxed);
217        ARGV_PTR.store(argv as usize, Ordering::Relaxed);
218        ENVP_PTR.store(envp as usize, Ordering::Relaxed);
219
220        AUX_PAGE_SIZE.store(aux.page_size, Ordering::Relaxed);
221        AUX_HWCAP.store(aux.hwcap, Ordering::Relaxed);
222        AUX_HWCAP2.store(aux.hwcap2, Ordering::Relaxed);
223        AUX_PHDR.store(aux.phdr_addr, Ordering::Relaxed);
224        AUX_PHENT.store(aux.phent_size, Ordering::Relaxed);
225        AUX_PHNUM.store(aux.phnum, Ordering::Relaxed);
226        AUX_ENTRY.store(aux.entry_addr, Ordering::Relaxed);
227        AUX_RANDOM.store(aux.random_addr, Ordering::Relaxed);
228        AUX_EXECFN.store(aux.execfn_addr, Ordering::Relaxed);
229
230        #[cfg(feature = "alloc")]
231        {
232            *ENV_TABLE.lock() = None;
233        }
234
235        INITIALIZED.store(true, Ordering::Release);
236    }
237}
238
239/// Returns the decoded [`AuxSummary`] captured at process startup.
240#[must_use]
241pub fn aux_summary() -> AuxSummary {
242    if !INITIALIZED.load(Ordering::Acquire) {
243        return AuxSummary {
244            page_size: DEFAULT_PAGE_SIZE,
245            ..AuxSummary::default()
246        };
247    }
248    let page_sz = AUX_PAGE_SIZE.load(Ordering::Relaxed);
249    AuxSummary {
250        page_size: if page_sz == 0 {
251            DEFAULT_PAGE_SIZE
252        } else {
253            page_sz
254        },
255        hwcap: AUX_HWCAP.load(Ordering::Relaxed),
256        hwcap2: AUX_HWCAP2.load(Ordering::Relaxed),
257        phdr_addr: AUX_PHDR.load(Ordering::Relaxed),
258        phent_size: AUX_PHENT.load(Ordering::Relaxed),
259        phnum: AUX_PHNUM.load(Ordering::Relaxed),
260        entry_addr: AUX_ENTRY.load(Ordering::Relaxed),
261        random_addr: AUX_RANDOM.load(Ordering::Relaxed),
262        execfn_addr: AUX_EXECFN.load(Ordering::Relaxed),
263    }
264}
265
266/// Looks up a value from the auxiliary vector by tag `key`.
267///
268/// `AT_PAGESZ` defaults to `4096` even if [`init_from_stack`] has not been called.
269#[must_use]
270pub fn getauxval(key: u64) -> u64 {
271    let summary = aux_summary();
272    match key {
273        AT_PAGESZ => summary.page_size as u64,
274        AT_HWCAP => summary.hwcap,
275        AT_HWCAP2 => summary.hwcap2,
276        AT_PHDR => summary.phdr_addr,
277        AT_PHENT => summary.phent_size,
278        AT_PHNUM => summary.phnum,
279        AT_ENTRY => summary.entry_addr,
280        AT_RANDOM => summary.random_addr,
281        AT_EXECFN => summary.execfn_addr,
282        _ => 0,
283    }
284}
285
286/// Returns the active system page size in bytes (defaulting to `4096`).
287#[must_use]
288pub fn page_size() -> usize {
289    aux_summary().page_size
290}
291
292/// Returns the command-line arguments (`argv[0..argc]`) as byte vectors.
293#[cfg(feature = "alloc")]
294#[must_use]
295pub fn args_vec() -> Vec<Vec<u8>> {
296    if !INITIALIZED.load(Ordering::Acquire) {
297        return Vec::new();
298    }
299    let argc = ARGC.load(Ordering::Relaxed);
300    let argv = ARGV_PTR.load(Ordering::Relaxed) as *const *const u8;
301    if argc == 0 || argv.is_null() {
302        return Vec::new();
303    }
304
305    let mut out = Vec::with_capacity(argc);
306    let mut i = 0usize;
307    while i < argc {
308        // SAFETY: `argv` was validated by `parse_stack_words` to have `argc` non-null entries.
309        let ptr = unsafe { *argv.add(i) };
310        if ptr.is_null() {
311            break;
312        }
313        // SAFETY: Each `argv[i]` points to a NUL-terminated C string on the initial stack.
314        let len = unsafe { c_strlen(ptr) };
315        let slice = unsafe { core::slice::from_raw_parts(ptr, len) };
316        let mut arg = Vec::with_capacity(len);
317        arg.extend_from_slice(slice);
318        out.push(arg);
319        i += 1;
320    }
321    out
322}
323
324#[cfg(feature = "alloc")]
325fn ensure_env_initialized(guard: &mut Option<EnvPairs>) -> &mut EnvPairs {
326    if guard.is_none() {
327        let mut entries: EnvPairs = Vec::new();
328        if INITIALIZED.load(Ordering::Acquire) {
329            let envp = ENVP_PTR.load(Ordering::Relaxed) as *const *const u8;
330            if !envp.is_null() {
331                let mut idx = 0usize;
332                loop {
333                    // SAFETY: `envp` was validated by `parse_stack_words` to be NULL-terminated.
334                    let ptr = unsafe { *envp.add(idx) };
335                    if ptr.is_null() {
336                        break;
337                    }
338                    // SAFETY: Each `envp[idx]` points to a NUL-terminated `KEY=VALUE` string.
339                    let len = unsafe { c_strlen(ptr) };
340                    let bytes = unsafe { core::slice::from_raw_parts(ptr, len) };
341                    if let Some(eq_pos) = memchr(b'=', bytes) {
342                        let key = bytes[..eq_pos].to_vec();
343                        let val = bytes[eq_pos + 1..].to_vec();
344                        if let Some((_, existing_val)) = entries
345                            .iter_mut()
346                            .find(|(k, _)| k.as_slice() == key.as_slice())
347                        {
348                            *existing_val = val;
349                        } else {
350                            entries.push((key, val));
351                        }
352                    }
353                    idx += 1;
354                }
355            }
356        }
357        *guard = Some(entries);
358    }
359    guard.as_mut().unwrap()
360}
361
362/// Looks up the environment variable `name` and returns a cloned byte vector of its value.
363#[cfg(feature = "alloc")]
364#[must_use]
365pub fn getenv_vec(name: &[u8]) -> Option<Vec<u8>> {
366    if name.is_empty() || memchr(b'=', name).is_some() || memchr(0, name).is_some() {
367        return None;
368    }
369    let mut guard = ENV_TABLE.lock();
370    let table = ensure_env_initialized(&mut guard);
371    table
372        .iter()
373        .find(|(k, _)| k.as_slice() == name)
374        .map(|(_, v)| v.clone())
375}
376
377/// Inserts or updates the environment variable `name` with `value`.
378///
379/// Returns `Err(Errno(EINVAL))` if `name` is empty, contains `'='`, or contains an interior NUL,
380/// or if `value` contains an interior NUL.
381#[cfg(feature = "alloc")]
382pub fn setenv_bytes(name: &[u8], value: &[u8], overwrite: bool) -> SysResult<()> {
383    if name.is_empty()
384        || memchr(b'=', name).is_some()
385        || memchr(0, name).is_some()
386        || memchr(0, value).is_some()
387    {
388        return Err(Errno(EINVAL));
389    }
390
391    let mut guard = ENV_TABLE.lock();
392    let table = ensure_env_initialized(&mut guard);
393    if let Some((_, existing_val)) = table.iter_mut().find(|(k, _)| k.as_slice() == name) {
394        if overwrite {
395            existing_val.clear();
396            existing_val.extend_from_slice(value);
397        }
398        return Ok(());
399    }
400
401    let mut k = Vec::with_capacity(name.len());
402    k.extend_from_slice(name);
403    let mut v = Vec::with_capacity(value.len());
404    v.extend_from_slice(value);
405    table.push((k, v));
406    Ok(())
407}
408
409/// Returns all environment variables as `KEY=VALUE` byte vectors.
410#[cfg(feature = "alloc")]
411#[must_use]
412pub fn environ_vec() -> Vec<Vec<u8>> {
413    let mut guard = ENV_TABLE.lock();
414    let table = ensure_env_initialized(&mut guard);
415    let mut out = Vec::with_capacity(table.len());
416    for (k, v) in table.iter() {
417        let mut entry = Vec::with_capacity(k.len() + 1 + v.len());
418        entry.extend_from_slice(k);
419        entry.push(b'=');
420        entry.extend_from_slice(v);
421        out.push(entry);
422    }
423    out
424}
425
426/// Emits a freestanding `aarch64-unknown-none` process entry point (`_start`), stack initializer,
427/// and panic handler that exits via `exit_group` / `abort`.
428#[macro_export]
429macro_rules! process_entry {
430    ($main_fn:path) => {
431        #[cfg(all(target_arch = "aarch64", target_os = "none"))]
432        #[unsafe(naked)]
433        #[unsafe(no_mangle)]
434        pub unsafe extern "C" fn _start() -> ! {
435            core::arch::naked_asm!(
436                "mov x0, sp",
437                "bl {entry}",
438                "brk #0",
439                entry = sym _libc_rs_start_rust,
440            );
441        }
442
443        #[cfg(all(target_arch = "aarch64", target_os = "none"))]
444        extern "C" fn _libc_rs_start_rust(sp: *const u64) -> ! {
445            // SAFETY: `sp` is the initial EL0 stack pointer passed from `_start`.
446            unsafe {
447                $crate::startup::init_from_stack(sp);
448            }
449            let code = $crate::startup::EntryOutcome::into_exit_code($main_fn());
450            $crate::process::exit_group(code)
451        }
452
453        #[cfg(all(target_arch = "aarch64", target_os = "none"))]
454        #[panic_handler]
455        fn _libc_rs_process_panic(_info: &core::panic::PanicInfo) -> ! {
456            $crate::process::abort()
457        }
458    };
459}
460
461#[cfg(test)]
462mod tests {
463    use super::*;
464
465    const HWCAP_AES: u64 = 1 << 3;
466    const HWCAP_CRC32: u64 = 1 << 7;
467
468    #[test]
469    fn startup_parses_stack_args_env_and_auxv() {
470        let arg0 = b"/bin/app\0";
471        let arg1 = b"--flag\0";
472        let env0 = b"PATH=/bin\0";
473        let env1 = b"MODE=fast\0";
474
475        let stack: [u64; 15] = [
476            2,
477            arg0.as_ptr() as u64,
478            arg1.as_ptr() as u64,
479            0,
480            env0.as_ptr() as u64,
481            env1.as_ptr() as u64,
482            0,
483            AT_PAGESZ,
484            16384,
485            AT_HWCAP,
486            HWCAP_AES | HWCAP_CRC32,
487            AT_ENTRY,
488            0x4000_1000,
489            AT_NULL,
490            0,
491        ];
492
493        // SAFETY: `stack` is a valid synthetic initial EL0 stack image with valid C string pointers.
494        unsafe {
495            init_from_stack(stack.as_ptr());
496        }
497
498        assert_eq!(page_size(), 16384);
499        assert_eq!(getauxval(AT_PAGESZ), 16384);
500        assert_eq!(getauxval(AT_HWCAP), HWCAP_AES | HWCAP_CRC32);
501        assert_eq!(getauxval(AT_ENTRY), 0x4000_1000);
502        assert_eq!(getauxval(999), 0);
503
504        #[cfg(feature = "alloc")]
505        {
506            let args = args_vec();
507            assert_eq!(args.len(), 2);
508            assert_eq!(args[0].as_slice(), b"/bin/app");
509            assert_eq!(args[1].as_slice(), b"--flag");
510
511            assert_eq!(getenv_vec(b"PATH").as_deref(), Some(&b"/bin"[..]));
512            assert_eq!(getenv_vec(b"MODE").as_deref(), Some(&b"fast"[..]));
513            assert_eq!(getenv_vec(b"MISSING"), None);
514
515            setenv_bytes(b"MODE", b"slow", false).unwrap();
516            assert_eq!(getenv_vec(b"MODE").as_deref(), Some(&b"fast"[..]));
517
518            setenv_bytes(b"MODE", b"turbo", true).unwrap();
519            assert_eq!(getenv_vec(b"MODE").as_deref(), Some(&b"turbo"[..]));
520
521            setenv_bytes(b"NEW_VAR", b"123", true).unwrap();
522            assert_eq!(getenv_vec(b"NEW_VAR").as_deref(), Some(&b"123"[..]));
523
524            assert_eq!(setenv_bytes(b"", b"v", true), Err(Errno(EINVAL)));
525            assert_eq!(setenv_bytes(b"BAD=NAME", b"v", true), Err(Errno(EINVAL)));
526            assert_eq!(setenv_bytes(b"BAD\0NAME", b"v", true), Err(Errno(EINVAL)));
527            assert_eq!(setenv_bytes(b"GOOD", b"bad\0val", true), Err(Errno(EINVAL)));
528
529            let env_all = environ_vec();
530            assert!(env_all.iter().any(|e| e.as_slice() == b"PATH=/bin"));
531            assert!(env_all.iter().any(|e| e.as_slice() == b"MODE=turbo"));
532            assert!(env_all.iter().any(|e| e.as_slice() == b"NEW_VAR=123"));
533        }
534    }
535}