Skip to main content

kh_runtime/mem/
map.rs

1//! Guest virtual memory backed by host `mmap` / `mprotect` / `munmap`.
2//!
3//! Mapping policy:
4//! - Lengths and host addresses are rounded to the **host** page size.
5//! - Preferred guest VAs are tried first (`MAP_FIXED_NOREPLACE` on Linux).
6//! - On failure, a **contiguous host span** covering the whole image is
7//!   reserved, a uniform slide is derived, and each segment is placed with
8//!   `MAP_FIXED` inside that span. (Placing only the first segment free and
9//!   then `MAP_FIXED_NOREPLACE` neighbours fails on Linux when ASLR put the
10//!   first mapping next to another VMA — common for preferred base `0` dylibs.)
11//! - `__PAGEZERO`-style regions (no access, no file, huge span) are skipped.
12//! - File-backed content is copied into private anonymous pages (simpler than
13//!   partial-page `MAP_PRIVATE` file maps). Executable pages start RW, then
14//!   `mprotect` applies final permissions (W^X friendly).
15
16use std::fs::File;
17use std::io::{Read, Seek, SeekFrom};
18use std::ptr;
19
20use thiserror::Error;
21
22use crate::host;
23
24use super::layout::{HostPageSize, PageLayout};
25
26/// Darwin `VM_PROT_*` bits (same numeric values as XNU).
27pub const VM_PROT_READ: u32 = 0x1;
28pub const VM_PROT_WRITE: u32 = 0x2;
29pub const VM_PROT_EXECUTE: u32 = 0x4;
30
31/// One mapped guest region (host-owned).
32#[derive(Debug)]
33pub struct MappedRegion {
34    /// Segment / region name (for diagnostics).
35    pub name: String,
36    /// Guest virtual address (preferred + slide).
37    pub guest_addr: u64,
38    /// Host mapping base pointer.
39    ptr: *mut u8,
40    /// Host mapping length in bytes (host-page multiple).
41    len: usize,
42    /// Final protection bits (Darwin `VM_PROT_*`).
43    pub prot: u32,
44    /// File bytes copied into the mapping (0 for pure BSS / anonymous).
45    pub file_bytes: u64,
46    /// Virtual size requested by the image (may be smaller than host map).
47    pub vmsize: u64,
48}
49
50// SAFETY: `MappedRegion` uniquely owns the mapping; the pointer is never shared
51// across threads without external synchronization. `Send` is required so
52// `GuestMemory` can move between threads before execution starts.
53unsafe impl Send for MappedRegion {}
54
55impl MappedRegion {
56    /// Host base as a mutable byte slice covering the whole mapping.
57    #[must_use]
58    pub fn host_bytes_mut(&mut self) -> &mut [u8] {
59        // SAFETY: we own this mapping for `len` bytes; it is RW until final
60        // protect, and callers only use this before RX mprotect or on RW pages.
61        unsafe { std::slice::from_raw_parts_mut(self.ptr, self.len) }
62    }
63
64    /// Host base as an immutable byte slice.
65    #[must_use]
66    pub fn host_bytes(&self) -> &[u8] {
67        // SAFETY: mapping is live and owned; length is exact.
68        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
69    }
70
71    /// Host virtual address of the mapping base.
72    #[must_use]
73    pub fn host_addr(&self) -> u64 {
74        host::ptr_addr_u64(self.ptr)
75    }
76
77    /// Host mapping length.
78    #[must_use]
79    pub const fn host_len(&self) -> usize {
80        self.len
81    }
82}
83
84impl Drop for MappedRegion {
85    fn drop(&mut self) {
86        if !self.ptr.is_null() && self.len > 0 {
87            if !host::munmap(self.ptr, self.len) {
88                tracing::warn!(
89                    name = %self.name,
90                    len = self.len,
91                    "munmap failed during MappedRegion drop"
92                );
93            }
94            self.ptr = ptr::null_mut();
95        }
96    }
97}
98
99/// Request to map one segment-like region from a Mach-O image.
100#[derive(Debug, Clone)]
101pub struct MapRequest {
102    /// Segment name.
103    pub name: String,
104    /// Preferred guest VA (slide 0).
105    pub preferred_va: u64,
106    /// Virtual size (`vmsize`).
107    pub vmsize: u64,
108    /// File offset of the first mapped byte (`fileoff`).
109    pub fileoff: u64,
110    /// Bytes to load from the file (`filesize`).
111    pub filesize: u64,
112    /// Initial protection (`initprot`, Darwin bits).
113    pub initprot: u32,
114    /// Maximum protection (`maxprot`, Darwin bits).
115    pub maxprot: u32,
116}
117
118impl MapRequest {
119    /// True when this region should not be mapped (null-catch / empty).
120    #[must_use]
121    pub fn should_skip(&self) -> bool {
122        if self.vmsize == 0 {
123            return true;
124        }
125        let is_pagezero = self.name == "__PAGEZERO"
126            || (self.initprot == 0 && self.fileoff == 0 && self.filesize == 0);
127        // PAGEZERO is typically 4 GiB — never materialize it.
128        is_pagezero
129    }
130}
131
132/// Fully mapped guest image address space (slide applied).
133#[derive(Debug)]
134pub struct GuestMemory {
135    regions: Vec<MappedRegion>,
136    /// Byte slide applied to preferred guest VAs (`actual = preferred + slide`).
137    slide: u64,
138    host: HostPageSize,
139    preferred_base: u64,
140}
141
142/// Errors while mapping guest memory.
143#[derive(Debug, Error)]
144pub enum MapError {
145    /// Invalid argument (zero length, overflow, …).
146    #[error("invalid map request: {0}")]
147    Invalid(&'static str),
148
149    /// `mmap` / `mprotect` failed.
150    #[error("mmap/mprotect failed for {name}: {source}")]
151    Sys {
152        /// Region name.
153        name: String,
154        /// Underlying OS error.
155        #[source]
156        source: std::io::Error,
157    },
158
159    /// File I/O while filling a mapping.
160    #[error("file I/O while mapping {name}: {source}")]
161    File {
162        /// Region name.
163        name: String,
164        /// Underlying I/O error.
165        #[source]
166        source: std::io::Error,
167    },
168
169    /// Could not place the image (fixed and slid attempts failed).
170    #[error("could not place guest image in host VA space")]
171    PlacementFailed,
172}
173
174/// Upper bound on a single slid reservation (guards sparse / pathological layouts).
175const MAX_SLIDE_SPAN: u64 = 512 * 1024 * 1024; // 512 MiB
176
177impl GuestMemory {
178    /// Maps all non-skipped requests into the host address space.
179    ///
180    /// Tries preferred addresses first; on failure reserves a contiguous host
181    /// span for the whole image and places each segment with a uniform slide
182    /// (guest VA == host VA after placement).
183    pub fn map_image(
184        host: HostPageSize,
185        preferred_base: u64,
186        requests: &[MapRequest],
187        file: &mut File,
188    ) -> Result<Self, MapError> {
189        let active: Vec<&MapRequest> = requests.iter().filter(|r| !r.should_skip()).collect();
190        if active.is_empty() {
191            return Ok(Self {
192                regions: Vec::new(),
193                slide: 0,
194                host,
195                preferred_base,
196            });
197        }
198
199        // Attempt 1: preferred VAs (slide = 0, never clobber host maps).
200        match Self::try_map_all(host, preferred_base, 0, &active, file, FixedMode::NoReplace) {
201            Ok(regions) => {
202                return Ok(Self {
203                    regions,
204                    slide: 0,
205                    host,
206                    preferred_base,
207                });
208            }
209            Err(err) => {
210                tracing::debug!(error = %err, "preferred-base map failed; trying slid placement");
211            }
212        }
213
214        // Attempt 2: reserve full image span, slide every segment into it.
215        match Self::try_map_slid_reserved(host, preferred_base, &active, file) {
216            Ok(mem) => return Ok(mem),
217            Err(err) => {
218                tracing::debug!(error = %err, "reserved-span slid map failed; trying first-region slide");
219            }
220        }
221
222        // Attempt 3 (legacy): free-place first region, fixed-relative rest.
223        // Works when the image is a single segment or the kernel left a hole.
224        Self::try_map_slid_first_region(host, preferred_base, &active, file)
225    }
226
227    /// Kernel-chosen contiguous span for the whole image, then `MAP_FIXED` each segment.
228    fn try_map_slid_reserved(
229        host: HostPageSize,
230        preferred_base: u64,
231        active: &[&MapRequest],
232        file: &mut File,
233    ) -> Result<Self, MapError> {
234        let (span_lo, span_hi) = image_preferred_span(host, active)?;
235        let span_len_u64 = span_hi.saturating_sub(span_lo);
236        if span_len_u64 == 0 {
237            return Err(MapError::Invalid("empty image span"));
238        }
239        if span_len_u64 > MAX_SLIDE_SPAN {
240            return Err(MapError::Invalid(
241                "image span too large for slid reservation",
242            ));
243        }
244        let span_len =
245            usize::try_from(span_len_u64).map_err(|_| MapError::Invalid("span too large"))?;
246
247        // Reserve with PROT_NONE so the VA range cannot be stolen before we carve it.
248        let flags = libc::MAP_PRIVATE | libc::MAP_ANONYMOUS;
249        let Some(reserve_ptr) = host::mmap(None, span_len, libc::PROT_NONE, flags, -1, 0) else {
250            return Err(MapError::Sys {
251                name: "__RESERVE".into(),
252                source: std::io::Error::last_os_error(),
253            });
254        };
255        let reserve_base = host::ptr_addr_u64(reserve_ptr);
256        let slide = reserve_base.wrapping_sub(span_lo);
257
258        tracing::debug!(
259            span_lo = format_args!("{span_lo:#x}"),
260            span_hi = format_args!("{span_hi:#x}"),
261            reserve = format_args!("{reserve_base:#x}"),
262            slide = format_args!("{slide:#x}"),
263            "reserved contiguous host span for slid image"
264        );
265
266        // Carve segments with MAP_FIXED (replaces PROT_NONE pages in place).
267        match Self::try_map_all(
268            host,
269            preferred_base,
270            slide,
271            active,
272            file,
273            FixedMode::Replace,
274        ) {
275            Ok(regions) => {
276                // Carve-outs leave PROT_NONE residue in gaps; release it so the
277                // address space does not retain untracked maps.
278                unmap_span_gaps(reserve_base, span_len_u64, &regions);
279                Ok(Self {
280                    regions,
281                    slide,
282                    host,
283                    preferred_base,
284                })
285            }
286            Err(err) => {
287                // Successful segment maps were already dropped by `try_map_all`.
288                // Drop any leftover PROT_NONE from the original reservation.
289                // (May no-op for ranges already replaced+dropped.)
290                let _ = host::munmap(reserve_ptr, span_len);
291                Err(err)
292            }
293        }
294    }
295
296    /// Free-place the first region; map the rest at preferred + slide (fixed, no-replace).
297    fn try_map_slid_first_region(
298        host: HostPageSize,
299        preferred_base: u64,
300        active: &[&MapRequest],
301        file: &mut File,
302    ) -> Result<Self, MapError> {
303        let first = active
304            .first()
305            .copied()
306            .ok_or(MapError::Invalid("no active regions"))?;
307        let first_map = map_one(host, first, first.preferred_va, file, FixedMode::Free)?;
308        let slide = first_map.guest_addr.wrapping_sub(first.preferred_va);
309
310        let mut regions = vec![first_map];
311        for req in active.iter().skip(1) {
312            let target = req.preferred_va.wrapping_add(slide);
313            match map_one(host, req, target, file, FixedMode::NoReplace) {
314                Ok(region) => regions.push(region),
315                Err(err) => {
316                    drop(regions);
317                    tracing::debug!(error = %err, "slid fixed map failed");
318                    return Err(MapError::PlacementFailed);
319                }
320            }
321        }
322
323        Ok(Self {
324            regions,
325            slide,
326            host,
327            preferred_base,
328        })
329    }
330
331    fn try_map_all(
332        host: HostPageSize,
333        preferred_base: u64,
334        slide: u64,
335        active: &[&MapRequest],
336        file: &mut File,
337        fixed: FixedMode,
338    ) -> Result<Vec<MappedRegion>, MapError> {
339        let mut regions = Vec::with_capacity(active.len());
340        for req in active {
341            let target = req.preferred_va.wrapping_add(slide);
342            match map_one(host, req, target, file, fixed) {
343                Ok(region) => regions.push(region),
344                Err(err) => {
345                    drop(regions);
346                    return Err(err);
347                }
348            }
349        }
350        let _ = preferred_base;
351        Ok(regions)
352    }
353
354    /// Applied slide in bytes.
355    #[must_use]
356    pub const fn slide(&self) -> u64 {
357        self.slide
358    }
359
360    /// Preferred base used when planning.
361    #[must_use]
362    pub const fn preferred_base(&self) -> u64 {
363        self.preferred_base
364    }
365
366    /// Host page size policy.
367    #[must_use]
368    pub const fn host(&self) -> HostPageSize {
369        self.host
370    }
371
372    /// Mapped regions in plan order (skips omitted).
373    #[must_use]
374    pub fn regions(&self) -> &[MappedRegion] {
375        &self.regions
376    }
377
378    /// Mutable access to regions (e.g. SVC rewrite before protect).
379    pub fn regions_mut(&mut self) -> &mut [MappedRegion] {
380        &mut self.regions
381    }
382
383    /// Translates a guest VA to a host pointer if it falls in a mapped region.
384    #[must_use]
385    pub fn guest_to_host(&self, guest_va: u64) -> Option<*const u8> {
386        for region in &self.regions {
387            let start = region.guest_addr;
388            let end = start.saturating_add(region.vmsize);
389            if guest_va >= start && guest_va < end {
390                let offset = usize::try_from(guest_va.saturating_sub(start)).ok()?;
391                if offset >= region.len {
392                    return None;
393                }
394                // SAFETY: offset < len, pointer derived from owned mapping base.
395                return Some(unsafe { region.ptr.add(offset) });
396            }
397        }
398        None
399    }
400
401    /// Translates guest VA to a mutable host pointer.
402    #[must_use]
403    pub fn guest_to_host_mut(&mut self, guest_va: u64) -> Option<*mut u8> {
404        for region in &mut self.regions {
405            let start = region.guest_addr;
406            let end = start.saturating_add(region.vmsize);
407            if guest_va >= start && guest_va < end {
408                let offset = usize::try_from(guest_va.saturating_sub(start)).ok()?;
409                if offset >= region.len {
410                    return None;
411                }
412                return Some(unsafe { region.ptr.add(offset) });
413            }
414        }
415        None
416    }
417
418    /// Reads a little-endian `u32` from a mapped guest VA.
419    #[must_use]
420    pub fn read_u32_le(&self, guest_va: u64) -> Option<u32> {
421        let mut buf = [0_u8; 4];
422        self.read_exact(guest_va, &mut buf)?;
423        Some(u32::from_le_bytes(buf))
424    }
425
426    /// Reads a little-endian `u64` from a mapped guest VA.
427    #[must_use]
428    pub fn read_u64_le(&self, guest_va: u64) -> Option<u64> {
429        let mut buf = [0_u8; 8];
430        self.read_exact(guest_va, &mut buf)?;
431        Some(u64::from_le_bytes(buf))
432    }
433
434    /// Writes a little-endian `u64` to a mapped guest VA.
435    ///
436    /// Caller must ensure the region is writable (`mprotect_rw` if needed).
437    pub fn write_u64_le(&mut self, guest_va: u64, value: u64) -> Option<()> {
438        self.write_exact(guest_va, &value.to_le_bytes())
439    }
440
441    /// Copies `buf.len()` bytes from a mapped guest VA into `buf`.
442    pub fn read_exact(&self, guest_va: u64, buf: &mut [u8]) -> Option<()> {
443        if buf.is_empty() {
444            return Some(());
445        }
446        for region in &self.regions {
447            let start = region.guest_addr;
448            let end = start.saturating_add(region.vmsize);
449            if guest_va >= start && guest_va < end {
450                let offset = usize::try_from(guest_va.saturating_sub(start)).ok()?;
451                let need = buf.len();
452                let avail = region.len.saturating_sub(offset);
453                if need > avail {
454                    return None;
455                }
456                let host = region.host_bytes();
457                let src = host.get(offset..offset.saturating_add(need))?;
458                buf.copy_from_slice(src);
459                return Some(());
460            }
461        }
462        None
463    }
464
465    /// Copies `buf` into a mapped guest VA (region must be host-writable).
466    pub fn write_exact(&mut self, guest_va: u64, buf: &[u8]) -> Option<()> {
467        if buf.is_empty() {
468            return Some(());
469        }
470        for region in &mut self.regions {
471            let start = region.guest_addr;
472            let end = start.saturating_add(region.vmsize);
473            if guest_va >= start && guest_va < end {
474                let offset = usize::try_from(guest_va.saturating_sub(start)).ok()?;
475                let need = buf.len();
476                let avail = region.len.saturating_sub(offset);
477                if need > avail {
478                    return None;
479                }
480                let host = region.host_bytes_mut();
481                let dst = host.get_mut(offset..offset.saturating_add(need))?;
482                dst.copy_from_slice(buf);
483                return Some(());
484            }
485        }
486        None
487    }
488
489    /// Testing helper: pretends the image was slid by `delta` without remapping.
490    ///
491    /// Updates [`Self::slide`] and each region's `guest_addr`. Host pointers are
492    /// unchanged (identity is intentionally broken). Used by loader unit tests when
493    /// true preferred-base collisions are unavailable (macOS `MAP_FIXED` clobbers
494    /// blockers). Not for production load paths.
495    #[doc(hidden)]
496    pub fn test_offset_guest_vas(&mut self, delta: u64) {
497        self.slide = self.slide.wrapping_add(delta);
498        for region in &mut self.regions {
499            region.guest_addr = region.guest_addr.wrapping_add(delta);
500        }
501    }
502}
503
504/// How to place a single region relative to a preferred / slid guest VA.
505#[derive(Debug, Clone, Copy, PartialEq, Eq)]
506enum FixedMode {
507    /// Kernel chooses address (`guest_addr` becomes host base).
508    Free,
509    /// Fixed address; do not clobber existing maps (`MAP_FIXED_NOREPLACE` on Linux).
510    NoReplace,
511    /// Fixed address; replace any mapping already at that VA (`MAP_FIXED`).
512    /// Used after a PROT_NONE span reservation so carve-outs succeed.
513    Replace,
514}
515
516fn map_one(
517    host: HostPageSize,
518    req: &MapRequest,
519    target_guest: u64,
520    file: &mut File,
521    mode: FixedMode,
522) -> Result<MappedRegion, MapError> {
523    let host_page = host.bytes();
524    let map_len_u64 = PageLayout::align_up(req.vmsize, host_page)
525        .ok_or(MapError::Invalid("vmsize align overflow"))?;
526    let map_len =
527        usize::try_from(map_len_u64).map_err(|_| MapError::Invalid("vmsize too large"))?;
528    if map_len == 0 {
529        return Err(MapError::Invalid("zero map length"));
530    }
531
532    let mut flags = libc::MAP_PRIVATE | libc::MAP_ANONYMOUS;
533    let fixed = matches!(mode, FixedMode::NoReplace | FixedMode::Replace);
534    match mode {
535        FixedMode::Free => {}
536        FixedMode::NoReplace => flags |= host::fixed_map_flag(),
537        FixedMode::Replace => flags |= libc::MAP_FIXED,
538    }
539
540    // Map RW first so we can fill file content; tighten with mprotect after.
541    let prot_rw = libc::PROT_READ | libc::PROT_WRITE;
542    let fixed_addr = if fixed { Some(target_guest) } else { None };
543
544    let Some(base) = host::mmap(fixed_addr, map_len, prot_rw, flags, -1, 0) else {
545        return Err(MapError::Sys {
546            name: req.name.clone(),
547            source: std::io::Error::last_os_error(),
548        });
549    };
550
551    let actual_host = host::ptr_addr_u64(base);
552    // For non-fixed maps, guest VA becomes the host address (identity slide).
553    let guest_addr = if fixed { target_guest } else { actual_host };
554
555    let mut region = MappedRegion {
556        name: req.name.clone(),
557        guest_addr,
558        ptr: base,
559        len: map_len,
560        prot: req.initprot,
561        file_bytes: 0,
562        vmsize: req.vmsize,
563    };
564
565    // Copy file-backed bytes into the mapping.
566    if req.filesize > 0 {
567        let copy_len = usize::try_from(req.filesize.min(req.vmsize))
568            .map_err(|_| MapError::Invalid("filesize too large"))?;
569        if copy_len > map_len {
570            return Err(MapError::Invalid("filesize exceeds map length"));
571        }
572        file.seek(SeekFrom::Start(req.fileoff))
573            .map_err(|source| MapError::File {
574                name: req.name.clone(),
575                source,
576            })?;
577        let dst = region.host_bytes_mut();
578        let Some(slice) = dst.get_mut(..copy_len) else {
579            return Err(MapError::Invalid("copy slice out of range"));
580        };
581        file.read_exact(slice).map_err(|source| MapError::File {
582            name: req.name.clone(),
583            source,
584        })?;
585        region.file_bytes = u64::try_from(copy_len).unwrap_or(0);
586    }
587
588    // Apply final protection. Empty initprot → PROT_NONE.
589    let host_prot = darwin_to_host_prot(req.initprot);
590    if !host::mprotect(base, map_len, host_prot) {
591        return Err(MapError::Sys {
592            name: req.name.clone(),
593            source: std::io::Error::last_os_error(),
594        });
595    }
596
597    // aarch64: after writing instructions then mprotect(RX), flush I-cache so
598    // the CPU does not execute stale/garbage bytes (G4 SEGV with odd PC/addr).
599    if req.initprot & VM_PROT_EXECUTE != 0 {
600        clear_icache(base, map_len);
601    }
602
603    // When fixed, require exact placement.
604    if fixed && actual_host != target_guest {
605        return Err(MapError::Sys {
606            name: req.name.clone(),
607            source: std::io::Error::new(
608                std::io::ErrorKind::AddrNotAvailable,
609                format!("kernel placed map at {actual_host:#x}, wanted {target_guest:#x}"),
610            ),
611        });
612    }
613
614    Ok(region)
615}
616
617/// Flush D/I caches after writing executable guest code (aarch64 requirement).
618#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
619fn clear_icache(ptr: *mut u8, len: usize) {
620    if ptr.is_null() || len == 0 {
621        return;
622    }
623    // libgcc / compiler-rt — same symbol as hypercall tramp setup.
624    unsafe extern "C" {
625        fn __clear_cache(start: *mut libc::c_void, end: *mut libc::c_void);
626    }
627    // SAFETY: range is the live mapping we just wrote and mprotected.
628    unsafe {
629        let start = ptr.cast::<libc::c_void>();
630        let end = ptr.wrapping_add(len).cast::<libc::c_void>();
631        __clear_cache(start, end);
632    }
633}
634
635#[cfg(not(all(target_arch = "aarch64", target_os = "linux")))]
636fn clear_icache(_ptr: *mut u8, _len: usize) {}
637
638/// Preferred VA span covering every active segment (host-page aligned ends).
639fn image_preferred_span(
640    host: HostPageSize,
641    active: &[&MapRequest],
642) -> Result<(u64, u64), MapError> {
643    let host_page = host.bytes();
644    let mut lo = u64::MAX;
645    let mut hi = 0_u64;
646    for req in active {
647        lo = lo.min(req.preferred_va);
648        let end = req
649            .preferred_va
650            .checked_add(
651                PageLayout::align_up(req.vmsize, host_page)
652                    .ok_or(MapError::Invalid("vmsize align overflow"))?,
653            )
654            .ok_or(MapError::Invalid("segment end overflow"))?;
655        hi = hi.max(end);
656    }
657    if lo == u64::MAX || hi <= lo {
658        return Err(MapError::Invalid("no span from active segments"));
659    }
660    // Align span start down so MAP_FIXED bases stay host-page aligned when preferred is.
661    let lo = PageLayout::align_down(lo, host_page).unwrap_or(lo);
662    Ok((lo, hi))
663}
664
665/// Best-effort: release PROT_NONE pages left in the reserved span outside mapped segments.
666fn unmap_span_gaps(reserve_base: u64, span_len: u64, regions: &[MappedRegion]) {
667    if span_len == 0 || regions.is_empty() {
668        return;
669    }
670    let span_end = reserve_base.saturating_add(span_len);
671    let mut covered: Vec<(u64, u64)> = regions
672        .iter()
673        .map(|r| {
674            let start = r.guest_addr;
675            let end = start.saturating_add(u64::try_from(r.len).unwrap_or(0));
676            (start, end)
677        })
678        .collect();
679    covered.sort_by_key(|(s, _)| *s);
680
681    let mut cursor = reserve_base;
682    for (start, end) in covered {
683        if start > cursor && start <= span_end {
684            let gap_len = start.saturating_sub(cursor);
685            if let Ok(len) = usize::try_from(gap_len)
686                && len > 0
687            {
688                let ptr = host::u64_as_void_ptr(cursor).cast::<u8>();
689                let _ = host::munmap(ptr, len);
690            }
691        }
692        cursor = cursor.max(end);
693    }
694    if cursor < span_end {
695        let gap_len = span_end.saturating_sub(cursor);
696        if let Ok(len) = usize::try_from(gap_len)
697            && len > 0
698        {
699            let ptr = host::u64_as_void_ptr(cursor).cast::<u8>();
700            let _ = host::munmap(ptr, len);
701        }
702    }
703}
704
705/// Converts Darwin `VM_PROT_*` to host `PROT_*`.
706#[must_use]
707pub const fn darwin_to_host_prot(darwin: u32) -> libc::c_int {
708    if darwin == 0 {
709        return libc::PROT_NONE;
710    }
711    let mut prot = 0;
712    if darwin & VM_PROT_READ != 0 {
713        prot |= libc::PROT_READ;
714    }
715    if darwin & VM_PROT_WRITE != 0 {
716        prot |= libc::PROT_WRITE;
717    }
718    if darwin & VM_PROT_EXECUTE != 0 {
719        prot |= libc::PROT_EXEC;
720    }
721    prot
722}
723
724/// Maps an anonymous RW stack region (guest VA == host VA, kernel-chosen).
725///
726/// `size` is rounded up to the host page size. The returned region's
727/// `guest_addr` is the low address of the mapping; the stack pointer should be
728/// near `guest_addr + vmsize`.
729pub fn map_stack(host: HostPageSize, size: u64) -> Result<MappedRegion, MapError> {
730    let host_page = host.bytes();
731    let map_len_u64 =
732        PageLayout::align_up(size.max(1), host_page).ok_or(MapError::Invalid("stack align"))?;
733    let map_len = usize::try_from(map_len_u64).map_err(|_| MapError::Invalid("stack too large"))?;
734
735    let flags = libc::MAP_PRIVATE | libc::MAP_ANONYMOUS;
736    let prot = libc::PROT_READ | libc::PROT_WRITE;
737    let Some(base) = host::mmap(None, map_len, prot, flags, -1, 0) else {
738        return Err(MapError::Sys {
739            name: "__STACK".into(),
740            source: std::io::Error::last_os_error(),
741        });
742    };
743    Ok(MappedRegion {
744        name: "__STACK".into(),
745        guest_addr: host::ptr_addr_u64(base),
746        ptr: base,
747        len: map_len,
748        prot: VM_PROT_READ | VM_PROT_WRITE,
749        file_bytes: 0,
750        vmsize: map_len_u64,
751    })
752}
753
754/// Temporarily makes a region read/write (for SVC patching / bind writes).
755///
756/// No-op when Darwin `prot` already includes write (host mapping is already RW).
757pub fn mprotect_rw(region: &MappedRegion) -> Result<(), MapError> {
758    if region.prot & VM_PROT_WRITE != 0 {
759        return Ok(());
760    }
761    if host::mprotect(region.ptr, region.len, libc::PROT_READ | libc::PROT_WRITE) {
762        Ok(())
763    } else {
764        Err(MapError::Sys {
765            name: region.name.clone(),
766            source: std::io::Error::last_os_error(),
767        })
768    }
769}
770
771/// Restores Darwin-derived host protection on a region.
772pub fn mprotect_darwin(region: &MappedRegion, darwin_prot: u32) -> Result<(), MapError> {
773    let host_prot = darwin_to_host_prot(darwin_prot);
774    if host::mprotect(region.ptr, region.len, host_prot) {
775        Ok(())
776    } else {
777        Err(MapError::Sys {
778            name: region.name.clone(),
779            source: std::io::Error::last_os_error(),
780        })
781    }
782}
783
784#[cfg(test)]
785#[allow(clippy::expect_used, clippy::unwrap_used)]
786mod tests {
787    use super::*;
788    use std::io::{Seek, SeekFrom, Write};
789    use std::path::PathBuf;
790
791    fn temp_file_with(bytes: &[u8]) -> (File, PathBuf) {
792        use std::fs::OpenOptions;
793        let path = std::env::temp_dir().join(format!(
794            "kh-map-test-{}-{}",
795            std::process::id(),
796            bytes.len()
797        ));
798        let mut f = OpenOptions::new()
799            .read(true)
800            .write(true)
801            .create(true)
802            .truncate(true)
803            .open(&path)
804            .expect("create temp");
805        f.write_all(bytes).expect("write");
806        f.seek(SeekFrom::Start(0)).expect("seek");
807        (f, path)
808    }
809
810    #[test]
811    fn skip_pagezero() {
812        let req = MapRequest {
813            name: "__PAGEZERO".into(),
814            preferred_va: 0,
815            vmsize: 0x1_0000_0000,
816            fileoff: 0,
817            filesize: 0,
818            initprot: 0,
819            maxprot: 0,
820        };
821        assert!(req.should_skip());
822    }
823
824    #[test]
825    fn map_anonymous_rw_region() {
826        let host = HostPageSize::detect().expect("host page");
827        let page = u64::from(host.bytes());
828        let payload = b"hello-guest-map";
829        let (mut file, path) = temp_file_with(payload);
830
831        // Prefer a high VA; may fail and slide — both OK for this test.
832        let preferred = 0x0000_0001_0000_0000_u64;
833        let reqs = [MapRequest {
834            name: "__TEST".into(),
835            preferred_va: preferred,
836            vmsize: page,
837            fileoff: 0,
838            filesize: u64::try_from(payload.len()).unwrap(),
839            initprot: VM_PROT_READ | VM_PROT_WRITE,
840            maxprot: VM_PROT_READ | VM_PROT_WRITE,
841        }];
842
843        let mem = GuestMemory::map_image(host, preferred, &reqs, &mut file).expect("map");
844        assert_eq!(mem.regions().len(), 1);
845        let region = mem.regions().first().expect("region");
846        assert!(region.host_len() >= payload.len());
847        let got = region.host_bytes().get(..payload.len()).expect("bytes");
848        assert_eq!(got, payload);
849        assert_eq!(region.file_bytes, u64::try_from(payload.len()).unwrap());
850        drop(mem);
851        drop(std::fs::remove_file(path));
852    }
853
854    #[test]
855    fn prot_conversion() {
856        assert_eq!(darwin_to_host_prot(0), libc::PROT_NONE);
857        assert_eq!(darwin_to_host_prot(VM_PROT_READ), libc::PROT_READ);
858        assert_eq!(
859            darwin_to_host_prot(VM_PROT_READ | VM_PROT_EXECUTE),
860            libc::PROT_READ | libc::PROT_EXEC
861        );
862    }
863
864    /// Real `kh-libsystem` ships with preferred base 0 (`__TEXT` at 0, BSS DATA,
865    /// LINKEDIT). Preferred fixed maps fail on Linux; slid reserved-span must work.
866    #[test]
867    fn map_base0_multi_segment_like_libsystem() {
868        let host = HostPageSize::detect().expect("host page");
869        let page = u64::from(host.bytes());
870        // Layout mirrors staged libSystem.B.dylib (16 KiB TEXT + ~272 KiB DATA BSS + LINKEDIT).
871        let text_sz = page.max(0x4000);
872        let data_sz = 0x4_4000_u64;
873        let link_sz = page.max(0x4000);
874        let text_va = 0_u64;
875        let data_va = text_sz;
876        let link_va = data_va + data_sz;
877
878        let payload = b"base0-text-payload";
879        let (mut file, path) = temp_file_with(payload);
880
881        let reqs = [
882            MapRequest {
883                name: "__TEXT".into(),
884                preferred_va: text_va,
885                vmsize: text_sz,
886                fileoff: 0,
887                filesize: u64::try_from(payload.len()).unwrap(),
888                initprot: VM_PROT_READ | VM_PROT_EXECUTE,
889                maxprot: VM_PROT_READ | VM_PROT_EXECUTE,
890            },
891            MapRequest {
892                name: "__DATA".into(),
893                preferred_va: data_va,
894                vmsize: data_sz,
895                fileoff: 0,
896                filesize: 0,
897                initprot: VM_PROT_READ | VM_PROT_WRITE,
898                maxprot: VM_PROT_READ | VM_PROT_WRITE,
899            },
900            MapRequest {
901                name: "__LINKEDIT".into(),
902                preferred_va: link_va,
903                vmsize: link_sz,
904                fileoff: 0,
905                filesize: 0,
906                initprot: VM_PROT_READ,
907                maxprot: VM_PROT_READ,
908            },
909        ];
910
911        let mem = GuestMemory::map_image(host, 0, &reqs, &mut file).expect("map base0 image");
912        assert_eq!(mem.regions().len(), 3);
913        // Relative layout must be preserved under slide.
914        let text = mem.regions().first().expect("text");
915        let data = mem.regions().get(1).expect("data");
916        let link = mem.regions().get(2).expect("link");
917        assert_eq!(
918            data.guest_addr.wrapping_sub(text.guest_addr),
919            data_va.wrapping_sub(text_va)
920        );
921        assert_eq!(
922            link.guest_addr.wrapping_sub(text.guest_addr),
923            link_va.wrapping_sub(text_va)
924        );
925        let got = text.host_bytes().get(..payload.len()).expect("text bytes");
926        assert_eq!(got, payload);
927        // Preferred base 0 never sticks on Linux; slide may be 0 only if the
928        // kernel actually accepted fixed maps at 0 (rare). Either is fine.
929        let _ = mem.slide();
930        drop(mem);
931        drop(std::fs::remove_file(path));
932    }
933
934    #[test]
935    fn image_span_covers_aligned_ends() {
936        let host = HostPageSize::detect().expect("host page");
937        let page = u64::from(host.bytes());
938        let reqs = [
939            MapRequest {
940                name: "a".into(),
941                preferred_va: 0,
942                vmsize: page,
943                fileoff: 0,
944                filesize: 0,
945                initprot: VM_PROT_READ,
946                maxprot: VM_PROT_READ,
947            },
948            MapRequest {
949                name: "b".into(),
950                preferred_va: page * 2,
951                vmsize: page,
952                fileoff: 0,
953                filesize: 0,
954                initprot: VM_PROT_READ,
955                maxprot: VM_PROT_READ,
956            },
957        ];
958        let refs: Vec<&MapRequest> = reqs.iter().collect();
959        let (lo, hi) = image_preferred_span(host, &refs).expect("span");
960        assert_eq!(lo, 0);
961        assert_eq!(hi, page * 3);
962    }
963}