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