aligned_vmem/api/
leak_zeroed_pages.rs

1use core::ptr::NonNull;
2
3use crate::page::PAGE;
4
5use super::reserve::reserve_aligned;
6
7/// Reserve `size` bytes of **zero-initialised** anonymous virtual memory and
8/// **leak** it for the process lifetime, returning the base pointer.
9///
10/// Folds the leaked-zeroed-sidecar pattern (used by allocators for pre-main
11/// bookkeeping structures that must not route through the very allocator they
12/// implement) into one helper:
13///
14/// - `size` is rounded up to a multiple of [`PAGE`] internally (any non-zero
15///   `size` is accepted; a zero `size` returns `None`). On some platforms
16///   (e.g. macOS with 16 KiB pages, or 64 KiB Windows allocation granularity),
17///   the OS may round further beyond `PAGE`, so the actual granularity
18///   consumed can exceed `PAGE`.
19/// - the span is guaranteed all-zero on every backend, INCLUDING the miri
20///   fallback (`std::alloc` does not zero; this helper zeroes explicitly under
21///   miri), so the returned memory is a valid all-zero initial state.
22/// - the reservation is `mem::forget`-leaked: it lives for the process lifetime
23///   and is never released.
24///
25/// Returns `None` on OOM or a zero `size`. The returned pointer is non-null,
26/// [`PAGE`]-aligned, and valid for the rounded-up size for the whole process
27/// lifetime. Because the reservation is leaked, the returned pointer may be
28/// safely turned into a `&'static` by the caller (subject to the caller's own
29/// aliasing discipline).
30#[must_use]
31pub fn leak_zeroed_pages(size: usize) -> Option<NonNull<u8>> {
32    if size == 0 {
33        return None;
34    }
35    let rounded = size.checked_add(PAGE - 1)? & !(PAGE - 1);
36    let reservation = reserve_aligned(rounded, PAGE)?;
37    let base = reservation.as_ptr();
38
39    // Under miri, `reserve_aligned` falls back to `std::alloc`, which does NOT
40    // zero the bytes; every real OS backend hands back zeroed pages. Zero
41    // explicitly under miri so the all-zero initial-state guarantee holds on
42    // every backend.
43    #[cfg(miri)]
44    // SAFETY: `base` is a fresh, exclusively-owned reservation of `rounded`
45    // bytes; nothing else references it yet, so writing zeros is sound.
46    unsafe {
47        core::ptr::write_bytes(base, 0, rounded);
48    }
49
50    // Leak: the sidecar lives for the process lifetime, never released.
51    core::mem::forget(reservation);
52
53    // SAFETY: `base` is the non-null `as_ptr` of a successful reservation.
54    Some(unsafe { NonNull::new_unchecked(base) })
55}
aligned_vmem/api/leak_zeroed_pages.rs

aligned_vmem/api/
leak_zeroed_pages.rs
