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    // When fixed, require exact placement.
598    if fixed && actual_host != target_guest {
599        return Err(MapError::Sys {
600            name: req.name.clone(),
601            source: std::io::Error::new(
602                std::io::ErrorKind::AddrNotAvailable,
603                format!("kernel placed map at {actual_host:#x}, wanted {target_guest:#x}"),
604            ),
605        });
606    }
607
608    Ok(region)
609}
610
611/// Preferred VA span covering every active segment (host-page aligned ends).
612fn image_preferred_span(
613    host: HostPageSize,
614    active: &[&MapRequest],
615) -> Result<(u64, u64), MapError> {
616    let host_page = host.bytes();
617    let mut lo = u64::MAX;
618    let mut hi = 0_u64;
619    for req in active {
620        lo = lo.min(req.preferred_va);
621        let end = req
622            .preferred_va
623            .checked_add(
624                PageLayout::align_up(req.vmsize, host_page)
625                    .ok_or(MapError::Invalid("vmsize align overflow"))?,
626            )
627            .ok_or(MapError::Invalid("segment end overflow"))?;
628        hi = hi.max(end);
629    }
630    if lo == u64::MAX || hi <= lo {
631        return Err(MapError::Invalid("no span from active segments"));
632    }
633    // Align span start down so MAP_FIXED bases stay host-page aligned when preferred is.
634    let lo = PageLayout::align_down(lo, host_page).unwrap_or(lo);
635    Ok((lo, hi))
636}
637
638/// Best-effort: release PROT_NONE pages left in the reserved span outside mapped segments.
639fn unmap_span_gaps(reserve_base: u64, span_len: u64, regions: &[MappedRegion]) {
640    if span_len == 0 || regions.is_empty() {
641        return;
642    }
643    let span_end = reserve_base.saturating_add(span_len);
644    let mut covered: Vec<(u64, u64)> = regions
645        .iter()
646        .map(|r| {
647            let start = r.guest_addr;
648            let end = start.saturating_add(u64::try_from(r.len).unwrap_or(0));
649            (start, end)
650        })
651        .collect();
652    covered.sort_by_key(|(s, _)| *s);
653
654    let mut cursor = reserve_base;
655    for (start, end) in covered {
656        if start > cursor && start <= span_end {
657            let gap_len = start.saturating_sub(cursor);
658            if let Ok(len) = usize::try_from(gap_len)
659                && len > 0
660            {
661                let ptr = host::u64_as_void_ptr(cursor).cast::<u8>();
662                let _ = host::munmap(ptr, len);
663            }
664        }
665        cursor = cursor.max(end);
666    }
667    if cursor < span_end {
668        let gap_len = span_end.saturating_sub(cursor);
669        if let Ok(len) = usize::try_from(gap_len)
670            && len > 0
671        {
672            let ptr = host::u64_as_void_ptr(cursor).cast::<u8>();
673            let _ = host::munmap(ptr, len);
674        }
675    }
676}
677
678/// Converts Darwin `VM_PROT_*` to host `PROT_*`.
679#[must_use]
680pub const fn darwin_to_host_prot(darwin: u32) -> libc::c_int {
681    if darwin == 0 {
682        return libc::PROT_NONE;
683    }
684    let mut prot = 0;
685    if darwin & VM_PROT_READ != 0 {
686        prot |= libc::PROT_READ;
687    }
688    if darwin & VM_PROT_WRITE != 0 {
689        prot |= libc::PROT_WRITE;
690    }
691    if darwin & VM_PROT_EXECUTE != 0 {
692        prot |= libc::PROT_EXEC;
693    }
694    prot
695}
696
697/// Maps an anonymous RW stack region (guest VA == host VA, kernel-chosen).
698///
699/// `size` is rounded up to the host page size. The returned region's
700/// `guest_addr` is the low address of the mapping; the stack pointer should be
701/// near `guest_addr + vmsize`.
702pub fn map_stack(host: HostPageSize, size: u64) -> Result<MappedRegion, MapError> {
703    let host_page = host.bytes();
704    let map_len_u64 =
705        PageLayout::align_up(size.max(1), host_page).ok_or(MapError::Invalid("stack align"))?;
706    let map_len = usize::try_from(map_len_u64).map_err(|_| MapError::Invalid("stack too large"))?;
707
708    let flags = libc::MAP_PRIVATE | libc::MAP_ANONYMOUS;
709    let prot = libc::PROT_READ | libc::PROT_WRITE;
710    let Some(base) = host::mmap(None, map_len, prot, flags, -1, 0) else {
711        return Err(MapError::Sys {
712            name: "__STACK".into(),
713            source: std::io::Error::last_os_error(),
714        });
715    };
716    Ok(MappedRegion {
717        name: "__STACK".into(),
718        guest_addr: host::ptr_addr_u64(base),
719        ptr: base,
720        len: map_len,
721        prot: VM_PROT_READ | VM_PROT_WRITE,
722        file_bytes: 0,
723        vmsize: map_len_u64,
724    })
725}
726
727/// Temporarily makes a region read/write (for SVC patching).
728pub fn mprotect_rw(region: &MappedRegion) -> Result<(), MapError> {
729    if host::mprotect(region.ptr, region.len, libc::PROT_READ | libc::PROT_WRITE) {
730        Ok(())
731    } else {
732        Err(MapError::Sys {
733            name: region.name.clone(),
734            source: std::io::Error::last_os_error(),
735        })
736    }
737}
738
739/// Restores Darwin-derived host protection on a region.
740pub fn mprotect_darwin(region: &MappedRegion, darwin_prot: u32) -> Result<(), MapError> {
741    let host_prot = darwin_to_host_prot(darwin_prot);
742    if host::mprotect(region.ptr, region.len, host_prot) {
743        Ok(())
744    } else {
745        Err(MapError::Sys {
746            name: region.name.clone(),
747            source: std::io::Error::last_os_error(),
748        })
749    }
750}
751
752#[cfg(test)]
753#[allow(clippy::expect_used, clippy::unwrap_used)]
754mod tests {
755    use super::*;
756    use std::io::{Seek, SeekFrom, Write};
757    use std::path::PathBuf;
758
759    fn temp_file_with(bytes: &[u8]) -> (File, PathBuf) {
760        use std::fs::OpenOptions;
761        let path = std::env::temp_dir().join(format!(
762            "kh-map-test-{}-{}",
763            std::process::id(),
764            bytes.len()
765        ));
766        let mut f = OpenOptions::new()
767            .read(true)
768            .write(true)
769            .create(true)
770            .truncate(true)
771            .open(&path)
772            .expect("create temp");
773        f.write_all(bytes).expect("write");
774        f.seek(SeekFrom::Start(0)).expect("seek");
775        (f, path)
776    }
777
778    #[test]
779    fn skip_pagezero() {
780        let req = MapRequest {
781            name: "__PAGEZERO".into(),
782            preferred_va: 0,
783            vmsize: 0x1_0000_0000,
784            fileoff: 0,
785            filesize: 0,
786            initprot: 0,
787            maxprot: 0,
788        };
789        assert!(req.should_skip());
790    }
791
792    #[test]
793    fn map_anonymous_rw_region() {
794        let host = HostPageSize::detect().expect("host page");
795        let page = u64::from(host.bytes());
796        let payload = b"hello-guest-map";
797        let (mut file, path) = temp_file_with(payload);
798
799        // Prefer a high VA; may fail and slide — both OK for this test.
800        let preferred = 0x0000_0001_0000_0000_u64;
801        let reqs = [MapRequest {
802            name: "__TEST".into(),
803            preferred_va: preferred,
804            vmsize: page,
805            fileoff: 0,
806            filesize: u64::try_from(payload.len()).unwrap(),
807            initprot: VM_PROT_READ | VM_PROT_WRITE,
808            maxprot: VM_PROT_READ | VM_PROT_WRITE,
809        }];
810
811        let mem = GuestMemory::map_image(host, preferred, &reqs, &mut file).expect("map");
812        assert_eq!(mem.regions().len(), 1);
813        let region = mem.regions().first().expect("region");
814        assert!(region.host_len() >= payload.len());
815        let got = region.host_bytes().get(..payload.len()).expect("bytes");
816        assert_eq!(got, payload);
817        assert_eq!(region.file_bytes, u64::try_from(payload.len()).unwrap());
818        drop(mem);
819        drop(std::fs::remove_file(path));
820    }
821
822    #[test]
823    fn prot_conversion() {
824        assert_eq!(darwin_to_host_prot(0), libc::PROT_NONE);
825        assert_eq!(darwin_to_host_prot(VM_PROT_READ), libc::PROT_READ);
826        assert_eq!(
827            darwin_to_host_prot(VM_PROT_READ | VM_PROT_EXECUTE),
828            libc::PROT_READ | libc::PROT_EXEC
829        );
830    }
831
832    /// Real `kh-libsystem` ships with preferred base 0 (`__TEXT` at 0, BSS DATA,
833    /// LINKEDIT). Preferred fixed maps fail on Linux; slid reserved-span must work.
834    #[test]
835    fn map_base0_multi_segment_like_libsystem() {
836        let host = HostPageSize::detect().expect("host page");
837        let page = u64::from(host.bytes());
838        // Layout mirrors staged libSystem.B.dylib (16 KiB TEXT + ~272 KiB DATA BSS + LINKEDIT).
839        let text_sz = page.max(0x4000);
840        let data_sz = 0x4_4000_u64;
841        let link_sz = page.max(0x4000);
842        let text_va = 0_u64;
843        let data_va = text_sz;
844        let link_va = data_va + data_sz;
845
846        let payload = b"base0-text-payload";
847        let (mut file, path) = temp_file_with(payload);
848
849        let reqs = [
850            MapRequest {
851                name: "__TEXT".into(),
852                preferred_va: text_va,
853                vmsize: text_sz,
854                fileoff: 0,
855                filesize: u64::try_from(payload.len()).unwrap(),
856                initprot: VM_PROT_READ | VM_PROT_EXECUTE,
857                maxprot: VM_PROT_READ | VM_PROT_EXECUTE,
858            },
859            MapRequest {
860                name: "__DATA".into(),
861                preferred_va: data_va,
862                vmsize: data_sz,
863                fileoff: 0,
864                filesize: 0,
865                initprot: VM_PROT_READ | VM_PROT_WRITE,
866                maxprot: VM_PROT_READ | VM_PROT_WRITE,
867            },
868            MapRequest {
869                name: "__LINKEDIT".into(),
870                preferred_va: link_va,
871                vmsize: link_sz,
872                fileoff: 0,
873                filesize: 0,
874                initprot: VM_PROT_READ,
875                maxprot: VM_PROT_READ,
876            },
877        ];
878
879        let mem = GuestMemory::map_image(host, 0, &reqs, &mut file).expect("map base0 image");
880        assert_eq!(mem.regions().len(), 3);
881        // Relative layout must be preserved under slide.
882        let text = mem.regions().first().expect("text");
883        let data = mem.regions().get(1).expect("data");
884        let link = mem.regions().get(2).expect("link");
885        assert_eq!(
886            data.guest_addr.wrapping_sub(text.guest_addr),
887            data_va.wrapping_sub(text_va)
888        );
889        assert_eq!(
890            link.guest_addr.wrapping_sub(text.guest_addr),
891            link_va.wrapping_sub(text_va)
892        );
893        let got = text.host_bytes().get(..payload.len()).expect("text bytes");
894        assert_eq!(got, payload);
895        // Preferred base 0 never sticks on Linux; slide may be 0 only if the
896        // kernel actually accepted fixed maps at 0 (rare). Either is fine.
897        let _ = mem.slide();
898        drop(mem);
899        drop(std::fs::remove_file(path));
900    }
901
902    #[test]
903    fn image_span_covers_aligned_ends() {
904        let host = HostPageSize::detect().expect("host page");
905        let page = u64::from(host.bytes());
906        let reqs = [
907            MapRequest {
908                name: "a".into(),
909                preferred_va: 0,
910                vmsize: page,
911                fileoff: 0,
912                filesize: 0,
913                initprot: VM_PROT_READ,
914                maxprot: VM_PROT_READ,
915            },
916            MapRequest {
917                name: "b".into(),
918                preferred_va: page * 2,
919                vmsize: page,
920                fileoff: 0,
921                filesize: 0,
922                initprot: VM_PROT_READ,
923                maxprot: VM_PROT_READ,
924            },
925        ];
926        let refs: Vec<&MapRequest> = reqs.iter().collect();
927        let (lo, hi) = image_preferred_span(host, &refs).expect("span");
928        assert_eq!(lo, 0);
929        assert_eq!(hi, page * 3);
930    }
931}