Skip to main content

hyperlight_host/mem/
layout.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3//! This module describes the virtual and physical addresses of a
4//! number of special regions in the hyperlight VM, although we hope
5//! to reduce the number of these over time.
6//!
7//! A snapshot freshly created from an empty VM will result in roughly
8//! the following physical layout:
9//!
10//! +-------------------------------------------+
11//! |             Guest Page Tables             |
12//! +-------------------------------------------+
13//! |              Init Data                    | (GuestBlob size)
14//! +-------------------------------------------+
15//! |             Guest Heap                    |
16//! +-------------------------------------------+
17//! |                PEB Struct                 | (HyperlightPEB size)
18//! +-------------------------------------------+
19//! |               Guest Code                  |
20//! +-------------------------------------------+ 0x1_000
21//! |              NULL guard page              |
22//! +-------------------------------------------+ 0x0_000
23//!
24//! Everything except for the guest page tables is currently
25//! identity-mapped; the guest page tables themselves are mapped at
26//! [`hyperlight_common::layout::SNAPSHOT_PT_GVA`] =
27//! 0xffff_8000_0000_0000.
28//!
29//! - `InitData` - some extra data that can be loaded onto the sandbox during
30//!   initialization.
31//!
32//! - `GuestHeap` - this is a buffer that is used for heap data in the guest. the length
33//!   of this field is returned by the `heap_size()` method of this struct
34//!
35//! There is also a scratch region at the top of physical memory,
36//! which is mostly laid out as a large undifferentiated blob of
37//! memory, although the transport arena and copied page tables have
38//! fixed positions:
39//!
40//! +-------------------------------------------+ (top of physical memory)
41//! |         Exception Stack, Metadata         |
42//! +-------------------------------------------+ (1 page below)
43//! |              Scratch Memory               |
44//! +-------------------------------------------+
45//! |             Guest Page Tables             |
46//! +-------------------------------------------+
47//! |              Transport Arena              |
48//! +-------------------------------------------+ (scratch size)
49
50use std::fmt::Debug;
51use std::mem::size_of;
52
53use hyperlight_common::layout::{QueueDims, TransportArena};
54use hyperlight_common::mem::HyperlightPEB;
55use hyperlight_common::vmem::PAGE_SIZE;
56use tracing::{Span, instrument};
57
58use super::memory_region::MemoryRegionType::{Code, Heap, InitData, Peb};
59use super::memory_region::{
60    DEFAULT_GUEST_BLOB_MEM_FLAGS, GuestMemoryRegion, MemoryRegion, MemoryRegion_,
61    MemoryRegionFlags, MemoryRegionVecBuilder,
62};
63#[cfg(readable_shared_mem)]
64use super::shared_mem::HostSharedMemory;
65use super::shared_mem::{ExclusiveSharedMemory, ReadonlySharedMemory};
66use crate::error::HyperlightError::{MemoryRequestTooBig, MemoryRequestTooSmall};
67use crate::sandbox::SandboxConfiguration;
68use crate::{Result, new_error};
69
70pub(crate) enum BaseGpaRegion<Sn, Sc> {
71    Snapshot(Sn),
72    Scratch(Sc),
73    Mmap(MemoryRegion),
74}
75
76// It's an invariant of this type, checked on creation, that the
77// offset is in bounds for the base region.
78pub(crate) struct ResolvedGpa<Sn, Sc> {
79    pub(crate) offset: usize,
80    pub(crate) base: BaseGpaRegion<Sn, Sc>,
81}
82
83impl AsRef<[u8]> for ExclusiveSharedMemory {
84    fn as_ref(&self) -> &[u8] {
85        self.as_slice()
86    }
87}
88impl AsRef<[u8]> for ReadonlySharedMemory {
89    fn as_ref(&self) -> &[u8] {
90        self.as_slice()
91    }
92}
93
94impl<Sn, Sc> ResolvedGpa<Sn, Sc> {
95    pub(crate) fn with_memories<Sn2, Sc2>(self, sn: Sn2, sc: Sc2) -> ResolvedGpa<Sn2, Sc2> {
96        ResolvedGpa {
97            offset: self.offset,
98            base: match self.base {
99                BaseGpaRegion::Snapshot(_) => BaseGpaRegion::Snapshot(sn),
100                BaseGpaRegion::Scratch(_) => BaseGpaRegion::Scratch(sc),
101                BaseGpaRegion::Mmap(r) => BaseGpaRegion::Mmap(r),
102            },
103        }
104    }
105}
106impl<'a> BaseGpaRegion<&'a [u8], &'a [u8]> {
107    pub(crate) fn as_ref<'b>(&'b self) -> &'a [u8] {
108        match self {
109            BaseGpaRegion::Snapshot(sn) => sn,
110            BaseGpaRegion::Scratch(sc) => sc,
111            BaseGpaRegion::Mmap(r) => unsafe {
112                #[allow(clippy::useless_conversion)]
113                let host_region_base: usize = r.host_region.start.into();
114                #[allow(clippy::useless_conversion)]
115                let host_region_end: usize = r.host_region.end.into();
116                let len = host_region_end - host_region_base;
117                std::slice::from_raw_parts(host_region_base as *const u8, len)
118            },
119        }
120    }
121}
122impl<'a> ResolvedGpa<&'a [u8], &'a [u8]> {
123    pub(crate) fn as_ref<'b>(&'b self) -> &'a [u8] {
124        let base = self.base.as_ref();
125        if self.offset > base.len() {
126            return &[];
127        }
128        &self.base.as_ref()[self.offset..]
129    }
130}
131/// A read-only abstraction over the different kinds of backing memory
132/// a [`ResolvedGpa`] can point at (the host snapshot mapping, the
133/// scratch mapping, or a raw `&[u8]` view of either), letting callers
134/// copy guest bytes out without caring which concrete memory type they
135/// hold.
136///
137/// This trait only exists in builds that actually read guest memory
138/// through it — see the `readable_shared_mem` cfg alias in `build.rs`
139/// for the exact conditions (the `gdb` debug path and the
140/// shared-snapshot `mem_profile` path). In every other configuration it
141/// is compiled out entirely, so there is no dead code to `#[allow]`.
142#[cfg(readable_shared_mem)]
143pub(crate) trait ReadableSharedMemory {
144    fn copy_to_slice(&self, slice: &mut [u8], offset: usize) -> Result<()>;
145}
146#[cfg(readable_shared_mem)]
147impl ReadableSharedMemory for &HostSharedMemory {
148    fn copy_to_slice(&self, slice: &mut [u8], offset: usize) -> Result<()> {
149        Ok(HostSharedMemory::copy_to_slice(self, slice, offset)?)
150    }
151}
152/// Coherence workaround for the blanket impl below.
153///
154/// We want `ReadableSharedMemory` for both `&HostSharedMemory` (above)
155/// and for any `T: AsRef<[u8]>` (so that `ExclusiveSharedMemory` /
156/// `ReadonlySharedMemory` and their references are covered by a single
157/// impl). A naive `impl<T: AsRef<[u8]>> ReadableSharedMemory for T`
158/// would *overlap* the `&HostSharedMemory` impl — the compiler can't
159/// prove `&HostSharedMemory` never implements `AsRef<[u8]>` — and is
160/// rejected with E0119.
161///
162/// To break the overlap we introduce a private marker trait and
163/// implement it *only* for the specific types we want the blanket impl
164/// to cover (deliberately excluding `&HostSharedMemory`). The blanket
165/// impl is then bounded on this marker rather than on `AsRef<[u8]>`
166/// directly, so the two impls provably never overlap.
167#[cfg(readable_shared_mem)]
168mod coherence_hack {
169    use super::{ExclusiveSharedMemory, ReadonlySharedMemory};
170    // Used only as a bound on the blanket impl below, so the name reads
171    // as unused even though removing it breaks compilation.
172    #[allow(unused)]
173    pub(super) trait SharedMemoryAsRefMarker: AsRef<[u8]> {}
174    impl SharedMemoryAsRefMarker for ExclusiveSharedMemory {}
175    impl SharedMemoryAsRefMarker for &ExclusiveSharedMemory {}
176    impl SharedMemoryAsRefMarker for ReadonlySharedMemory {}
177    impl SharedMemoryAsRefMarker for &ReadonlySharedMemory {}
178}
179#[cfg(readable_shared_mem)]
180impl<T: coherence_hack::SharedMemoryAsRefMarker> ReadableSharedMemory for T {
181    fn copy_to_slice(&self, slice: &mut [u8], offset: usize) -> Result<()> {
182        let ss: &[u8] = self.as_ref();
183        let end = offset + slice.len();
184        if end > ss.len() {
185            return Err(new_error!(
186                "Attempt to read up to {} in memory of size {}",
187                offset + slice.len(),
188                self.as_ref().len()
189            ));
190        }
191        slice.copy_from_slice(&ss[offset..end]);
192        Ok(())
193    }
194}
195/// Copy `slice.len()` bytes out of the resolved guest region.
196///
197/// Only the `gdb` debug path uses this one-argument convenience (it
198/// already carries the offset inside `self`); `mem_profile` reads via
199/// the two-argument inherent methods instead. Hence it is gated on the
200/// `gdb` cfg alone, even though the [`ReadableSharedMemory`] trait it
201/// relies on is available slightly more widely.
202#[cfg(gdb)]
203impl<Sn: ReadableSharedMemory, Sc: ReadableSharedMemory> ResolvedGpa<Sn, Sc> {
204    pub(crate) fn copy_to_slice(&self, slice: &mut [u8]) -> Result<()> {
205        match &self.base {
206            BaseGpaRegion::Snapshot(sn) => sn.copy_to_slice(slice, self.offset),
207            BaseGpaRegion::Scratch(sc) => sc.copy_to_slice(slice, self.offset),
208            BaseGpaRegion::Mmap(r) => unsafe {
209                #[allow(clippy::useless_conversion)]
210                let host_region_base: usize = r.host_region.start.into();
211                #[allow(clippy::useless_conversion)]
212                let host_region_end: usize = r.host_region.end.into();
213                let len = host_region_end - host_region_base;
214                // Safety: it's a documented invariant of MemoryRegion
215                // that the memory must remain alive as long as the
216                // sandbox is alive, and the way this code is used,
217                // the lifetimes of the snapshot and scratch memories
218                // ensure that the sandbox is still alive. This could
219                // perhaps be cleaned up/improved/made harder to
220                // misuse significantly, but it would require a much
221                // larger rework.
222                let ss = std::slice::from_raw_parts(host_region_base as *const u8, len);
223                let end = self.offset + slice.len();
224                if end > ss.len() {
225                    return Err(new_error!(
226                        "Attempt to read up to {} in memory of size {}",
227                        self.offset + slice.len(),
228                        ss.len()
229                    ));
230                }
231                slice.copy_from_slice(&ss[self.offset..end]);
232                Ok(())
233            },
234        }
235    }
236}
237
238#[derive(Copy, Clone)]
239pub(crate) struct SandboxMemoryLayout {
240    /// The heap size of this sandbox.
241    heap_size: usize,
242    /// The size of the guest code section.
243    code_size: usize,
244    /// Guest virtual address of the code section.
245    code_gva: usize,
246    /// The size of the init data section (guest blob).
247    init_data_size: usize,
248    /// Permission flags for the init data region.
249    init_data_permissions: Option<MemoryRegionFlags>,
250    /// The size of the scratch region in physical memory.
251    scratch_size: usize,
252    /// G2H ring and buffer pool dimensions.
253    g2h_dims: QueueDims,
254    /// H2G ring and buffer pool dimensions.
255    h2g_dims: QueueDims,
256    /// Capacity of each G2H upper-tier buffer.
257    g2h_buffer_size: usize,
258    /// Capacity of each H2G buffer.
259    h2g_buffer_size: usize,
260    /// Fixed ring and pool placement within scratch.
261    transport_arena: TransportArena,
262    /// Size of the primary guest memory region at `BASE_ADDRESS`
263    /// (code, PEB, heap, init data). For a snapshot-backed layout
264    /// this is also the guest-visible prefix of the host snapshot
265    /// mapping.
266    snapshot_size: usize,
267    /// Size of the page-table region. Sits at the tail of the host
268    /// snapshot mapping but is never mapped to the guest from there.
269    /// On restore the host copies it into scratch, where the guest
270    /// sees it at `SNAPSHOT_PT_GVA`. `None` until page tables are built.
271    pt_size: Option<usize>,
272}
273
274impl Debug for SandboxMemoryLayout {
275    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
276        let mut ff = f.debug_struct("SandboxMemoryLayout");
277        ff.field(
278            "Total Memory Size",
279            &format_args!("{:#x}", self.get_memory_size().unwrap_or(0)),
280        )
281        .field("Code Size", &format_args!("{:#x}", self.code_size))
282        .field("Code GVA", &format_args!("{:#x}", self.code_gva))
283        .field("Heap Size", &format_args!("{:#x}", self.heap_size))
284        .field(
285            "Init Data Size",
286            &format_args!("{:#x}", self.init_data_size),
287        )
288        .field("Scratch Size", &format_args!("{:#x}", self.scratch_size))
289        .field("G2H Queue Size", &self.get_g2h_queue_size())
290        .field("H2G Queue Size", &self.get_h2g_queue_size())
291        .field("G2H Buffer Size", &self.g2h_buffer_size)
292        .field("H2G Buffer Size", &self.h2g_buffer_size)
293        .field("G2H Pool Pages", &self.get_g2h_pool_pages())
294        .field("H2G Pool Pages", &self.get_h2g_pool_pages())
295        .field("Snapshot Size", &format_args!("{:#x}", self.snapshot_size))
296        .field("PT Size", &format_args!("{:#x}", self.pt_size.unwrap_or(0)))
297        .field(
298            "Guest Code Offset",
299            &format_args!("{:#x}", self.guest_code_offset()),
300        )
301        .field("PEB Offset", &format_args!("{:#x}", self.peb_offset()))
302        .field("PEB Address", &format_args!("{:#x}", self.peb_address()));
303        ff.field(
304            "Guest Heap Buffer Offset",
305            &format_args!("{:#x}", self.guest_heap_buffer_offset()),
306        )
307        .field(
308            "Init Data Offset",
309            &format_args!("{:#x}", self.init_data_offset()),
310        )
311        .finish()
312    }
313}
314
315impl SandboxMemoryLayout {
316    /// The maximum amount of memory a single sandbox will be allowed.
317    ///
318    /// Both the scratch region and the snapshot region are bounded by
319    /// this size. The value is arbitrary but chosen to be large enough
320    /// for most workloads while preventing accidental resource exhaustion.
321    pub(crate) const MAX_MEMORY_SIZE: usize = (16 * 1024 * 1024 * 1024) - Self::BASE_ADDRESS; // 16 GiB - BASE_ADDRESS
322
323    /// The base address of the sandbox's memory.
324    pub(crate) const BASE_ADDRESS: usize = 0x4000;
325
326    /// Create a new `SandboxMemoryLayout` with the given
327    /// `SandboxConfiguration`, code size and stack/heap size.
328    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
329    pub(crate) fn new(
330        cfg: SandboxConfiguration,
331        code_size: usize,
332        init_data_size: usize,
333        init_data_permissions: Option<MemoryRegionFlags>,
334    ) -> Result<Self> {
335        let heap_size = usize::try_from(cfg.get_heap_size())?;
336        let scratch_size = cfg.get_scratch_size();
337        if scratch_size > Self::MAX_MEMORY_SIZE {
338            return Err(MemoryRequestTooBig(scratch_size, Self::MAX_MEMORY_SIZE));
339        }
340        if !scratch_size.is_multiple_of(PAGE_SIZE) {
341            return Err(new_error!(
342                "scratch size {scratch_size} must be a multiple of {PAGE_SIZE}"
343            ));
344        }
345        let g2h_queue_size = cfg.get_g2h_queue_size();
346        let h2g_queue_size = cfg.get_h2g_queue_size();
347        let g2h_buffer_size = cfg.get_g2h_buffer_size();
348        let h2g_buffer_size = cfg.get_h2g_buffer_size();
349        let g2h_pool_pages = cfg.get_g2h_pool_pages();
350        let h2g_pool_pages = cfg.get_h2g_pool_pages();
351
352        let g2h_dims = QueueDims::new(g2h_queue_size, g2h_pool_pages)
353            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
354        let h2g_dims = QueueDims::new(h2g_queue_size, h2g_pool_pages)
355            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
356        let arena_base_gpa = hyperlight_common::layout::scratch_base_gpa(scratch_size);
357        let transport_arena = TransportArena::new(arena_base_gpa, g2h_dims, h2g_dims)
358            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
359        let min_scratch_size = hyperlight_common::layout::min_scratch_size(transport_arena.size());
360        if scratch_size < min_scratch_size {
361            return Err(MemoryRequestTooSmall(scratch_size, min_scratch_size));
362        }
363
364        let mut ret = Self {
365            heap_size,
366            code_size,
367            code_gva: Self::BASE_ADDRESS,
368            init_data_size,
369            init_data_permissions,
370            pt_size: None,
371            scratch_size,
372            g2h_dims,
373            h2g_dims,
374            g2h_buffer_size,
375            h2g_buffer_size,
376            transport_arena,
377            snapshot_size: 0,
378        };
379        ret.set_snapshot_size(ret.get_memory_size()?);
380        Ok(ret)
381    }
382
383    pub(crate) fn heap_size(&self) -> usize {
384        self.heap_size
385    }
386
387    pub(crate) fn code_size(&self) -> usize {
388        self.code_size
389    }
390
391    pub(crate) fn init_data_size(&self) -> usize {
392        self.init_data_size
393    }
394
395    pub(crate) fn init_data_permissions(&self) -> Option<MemoryRegionFlags> {
396        self.init_data_permissions
397    }
398
399    pub(crate) fn get_scratch_size(&self) -> usize {
400        self.scratch_size
401    }
402
403    pub(crate) fn get_g2h_queue_size(&self) -> usize {
404        usize::from(self.g2h_dims.size().get())
405    }
406
407    pub(crate) fn get_h2g_queue_size(&self) -> usize {
408        usize::from(self.h2g_dims.size().get())
409    }
410
411    pub(crate) fn get_g2h_buffer_size(&self) -> usize {
412        self.g2h_buffer_size
413    }
414
415    pub(crate) fn get_h2g_buffer_size(&self) -> usize {
416        self.h2g_buffer_size
417    }
418
419    pub(crate) fn get_g2h_pool_pages(&self) -> usize {
420        self.g2h_dims.pool_pages().get()
421    }
422
423    pub(crate) fn get_h2g_pool_pages(&self) -> usize {
424        self.h2g_dims.pool_pages().get()
425    }
426
427    pub(crate) fn get_g2h_queue_dims(&self) -> QueueDims {
428        self.g2h_dims
429    }
430
431    pub(crate) fn get_h2g_queue_dims(&self) -> QueueDims {
432        self.h2g_dims
433    }
434
435    /// Guest-visible prefix size of the snapshot blob.
436    pub(crate) fn snapshot_size(&self) -> usize {
437        self.snapshot_size
438    }
439
440    /// Recorded page-table tail size, `None` until page tables are built.
441    pub(crate) fn pt_size(&self) -> Option<usize> {
442        self.pt_size
443    }
444
445    /// Page-table tail size, or 0 if page tables are not yet built.
446    pub(crate) fn get_pt_size(&self) -> usize {
447        self.pt_size.unwrap_or(0)
448    }
449
450    /// Record the size of the page-table tail appended to the
451    /// snapshot blob. The PT bytes live at the end of the blob and
452    /// the host mapping, outside the guest mapping of the snapshot
453    /// region, and are copied into the scratch region on restore.
454    /// `snapshot_size` (the guest-visible prefix of the blob) is an
455    /// independent field and must be set separately.
456    pub(crate) fn set_pt_size(&mut self, size: usize) -> Result<()> {
457        let min_fixed_scratch =
458            hyperlight_common::layout::min_scratch_size(self.transport_arena.size());
459        let min_scratch = min_fixed_scratch.saturating_add(size);
460        if self.scratch_size < min_scratch {
461            return Err(MemoryRequestTooSmall(self.scratch_size, min_scratch));
462        }
463        self.pt_size = Some(size);
464        Ok(())
465    }
466
467    pub(crate) fn set_snapshot_size(&mut self, new_size: usize) {
468        self.snapshot_size = new_size;
469    }
470
471    /// Returns the memory regions associated with this memory layout,
472    /// suitable for passing to a hypervisor for mapping into memory
473    pub(crate) fn get_memory_regions(&self) -> Result<Vec<MemoryRegion_<GuestMemoryRegion>>> {
474        let mut builder = MemoryRegionVecBuilder::new(Self::BASE_ADDRESS, Self::BASE_ADDRESS);
475
476        // code
477        let peb_offset = builder.push_page_aligned(
478            self.code_size,
479            MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE,
480            Code,
481        );
482
483        let expected_peb_offset = TryInto::<usize>::try_into(self.peb_offset())?;
484
485        if peb_offset != expected_peb_offset {
486            return Err(new_error!(
487                "PEB offset does not match expected PEB offset expected:  {}, actual:  {}",
488                expected_peb_offset,
489                peb_offset
490            ));
491        }
492
493        // PEB
494        let heap_offset =
495            builder.push_page_aligned(size_of::<HyperlightPEB>(), MemoryRegionFlags::READ, Peb);
496
497        let expected_heap_offset = TryInto::<usize>::try_into(self.guest_heap_buffer_offset())?;
498
499        if heap_offset != expected_heap_offset {
500            return Err(new_error!(
501                "Guest Heap offset does not match expected Guest Heap offset expected:  {}, actual:  {}",
502                expected_heap_offset,
503                heap_offset
504            ));
505        }
506
507        // heap
508        #[cfg(feature = "executable_heap")]
509        let init_data_offset = builder.push_page_aligned(
510            self.heap_size,
511            MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE,
512            Heap,
513        );
514        #[cfg(not(feature = "executable_heap"))]
515        let init_data_offset = builder.push_page_aligned(
516            self.heap_size,
517            MemoryRegionFlags::READ | MemoryRegionFlags::WRITE,
518            Heap,
519        );
520
521        let expected_init_data_offset = TryInto::<usize>::try_into(self.init_data_offset())?;
522
523        if init_data_offset != expected_init_data_offset {
524            return Err(new_error!(
525                "Init Data offset does not match expected Init Data offset expected:  {}, actual:  {}",
526                expected_init_data_offset,
527                init_data_offset
528            ));
529        }
530
531        // init data
532        let after_init_offset = if self.init_data_size > 0 {
533            let mem_flags = self
534                .init_data_permissions
535                .unwrap_or(DEFAULT_GUEST_BLOB_MEM_FLAGS);
536            builder.push_page_aligned(self.init_data_size, mem_flags, InitData)
537        } else {
538            init_data_offset
539        };
540
541        let final_offset = after_init_offset;
542
543        let expected_final_offset = TryInto::<usize>::try_into(self.get_memory_size()?)?;
544
545        // This function is primarily used to construct
546        // GuestMemoryRegions used to populate initial guest page
547        // tables. Therefore, the regions above are aligned based on
548        // the guest page size. However, the total final size of the
549        // region mapped into the guest needs to be aligned based on
550        // the host page size. Therefore, align both of these values
551        // to both page sizes before comparing them.
552        let final_offset = final_offset.next_multiple_of(page_size::get());
553        let expected_final_offset =
554            expected_final_offset.next_multiple_of(hyperlight_common::vmem::PAGE_SIZE);
555
556        if final_offset != expected_final_offset {
557            return Err(new_error!(
558                "Final offset does not match expected Final offset expected:  {}, actual:  {}",
559                expected_final_offset,
560                final_offset
561            ));
562        }
563
564        let mut regions = builder.build();
565        for region in &mut regions {
566            if region.region_type == Code {
567                let end = self
568                    .code_gva
569                    .checked_add(region.guest_region.len())
570                    .ok_or_else(|| {
571                        new_error!(
572                            "code mapping overflow: base {:#x} + size {:#x}",
573                            self.code_gva,
574                            region.guest_region.len()
575                        )
576                    })?;
577                region.guest_region = self.code_gva..end;
578            }
579        }
580        Ok(regions)
581    }
582
583    /// Set the code GVA after checking that it does not overlap another region.
584    pub(crate) fn set_code_gva(&mut self, code_gva: u64) -> Result<()> {
585        let code_gva = usize::try_from(code_gva)?;
586        let code_end = code_gva
587            .checked_add(self.code_size.next_multiple_of(PAGE_SIZE))
588            .ok_or_else(|| {
589                new_error!(
590                    "code mapping overflow: base {:#x} + size {:#x}",
591                    code_gva,
592                    self.code_size
593                )
594            })?;
595        for region in self.get_memory_regions()? {
596            if region.region_type == Code {
597                continue;
598            }
599            if code_gva < region.guest_region.end && region.guest_region.start < code_end {
600                return Err(new_error!(
601                    "code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
602                    code_gva,
603                    code_end,
604                    region.region_type,
605                    region.guest_region.start,
606                    region.guest_region.end,
607                ));
608            }
609        }
610        self.code_gva = code_gva;
611        Ok(())
612    }
613
614    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
615    pub(crate) fn write_init_data(&self, out: &mut [u8], bytes: &[u8]) -> Result<()> {
616        out[self.init_data_offset()..self.init_data_offset() + self.init_data_size]
617            .copy_from_slice(bytes);
618        Ok(())
619    }
620
621    /// Write the finished memory layout to `mem` and return `Ok` if
622    /// successful.
623    ///
624    /// Note: `mem` may have been modified, even if `Err` was returned
625    /// from this function.
626    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
627    pub(crate) fn write_peb(&self, mem: &mut [u8]) -> Result<()> {
628        use hyperlight_common::mem::GuestMemoryRegion;
629
630        let guest_base = Self::BASE_ADDRESS as u64;
631
632        let peb = HyperlightPEB {
633            init_data: GuestMemoryRegion {
634                size: (self.get_unaligned_memory_size() - self.init_data_offset()) as u64,
635                ptr: guest_base + self.init_data_offset() as u64,
636            },
637            guest_heap: GuestMemoryRegion {
638                size: self.heap_size as u64,
639                ptr: guest_base + self.guest_heap_buffer_offset() as u64,
640            },
641        };
642
643        let offset = self.peb_offset();
644        let bytes = bytemuck::bytes_of(&peb);
645        let end = offset + bytes.len();
646        let mem_len = mem.len();
647        let dst = mem.get_mut(offset..end).ok_or_else(|| {
648            new_error!(
649                "memory too small to write PEB: need {} bytes at offset {:#x}, have {} bytes",
650                bytes.len(),
651                offset,
652                mem_len
653            )
654        })?;
655        dst.copy_from_slice(bytes);
656
657        Ok(())
658    }
659
660    /// Determine what region this gpa is in, and its offset into that region
661    pub(crate) fn resolve_gpa(
662        &self,
663        gpa: u64,
664        mmap_regions: &[MemoryRegion],
665    ) -> Option<ResolvedGpa<(), ()>> {
666        let scratch_base = hyperlight_common::layout::scratch_base_gpa(self.scratch_size);
667        if gpa >= scratch_base && gpa < scratch_base + self.scratch_size as u64 {
668            return Some(ResolvedGpa {
669                offset: (gpa - scratch_base) as usize,
670                base: BaseGpaRegion::Scratch(()),
671            });
672        } else if gpa >= SandboxMemoryLayout::BASE_ADDRESS as u64
673            && gpa < SandboxMemoryLayout::BASE_ADDRESS as u64 + self.snapshot_size as u64
674        {
675            return Some(ResolvedGpa {
676                offset: gpa as usize - SandboxMemoryLayout::BASE_ADDRESS,
677                base: BaseGpaRegion::Snapshot(()),
678            });
679        }
680        for rgn in mmap_regions {
681            if gpa >= rgn.guest_region.start as u64 && gpa < rgn.guest_region.end as u64 {
682                return Some(ResolvedGpa {
683                    offset: gpa as usize - rgn.guest_region.start,
684                    base: BaseGpaRegion::Mmap(rgn.clone()),
685                });
686            }
687        }
688        None
689    }
690}
691
692/// Changes to the below methods is part of Snapshot ABI, and
693/// changing any output shifts where the loader
694/// reads captured bytes and breaks existing snapshots. Any change here
695/// is a snapshot ABI break: see the `layout_offsets_are_pinned` test
696/// and docs/snapshot-versioning.md.
697impl SandboxMemoryLayout {
698    /// Offset of the PEB struct within the snapshot region.
699    pub(crate) fn peb_offset(&self) -> usize {
700        self.code_size.next_multiple_of(PAGE_SIZE)
701    }
702
703    /// Guest physical address of the PEB.
704    pub(crate) fn peb_address(&self) -> usize {
705        Self::BASE_ADDRESS + self.peb_offset()
706    }
707
708    /// Offset of the guest heap buffer within the snapshot region.
709    pub(crate) fn guest_heap_buffer_offset(&self) -> usize {
710        (self.peb_offset() + size_of::<HyperlightPEB>()).next_multiple_of(PAGE_SIZE)
711    }
712
713    /// Offset of the init data section within the snapshot region.
714    pub(crate) fn init_data_offset(&self) -> usize {
715        (self.guest_heap_buffer_offset() + self.heap_size).next_multiple_of(PAGE_SIZE)
716    }
717
718    /// The code offset is always 0.
719    pub(crate) fn guest_code_offset(&self) -> usize {
720        0
721    }
722
723    /// Guest physical address of the code section.
724    pub(crate) fn get_guest_code_gpa(&self) -> usize {
725        Self::BASE_ADDRESS + self.guest_code_offset()
726    }
727
728    /// Guest virtual address of the code section.
729    pub(crate) fn get_guest_code_gva(&self) -> usize {
730        self.code_gva
731    }
732
733    /// Offset from the beginning of the scratch region to the location
734    /// where page tables are eagerly copied on restore.
735    pub(crate) fn get_pt_base_scratch_offset(&self) -> usize {
736        self.transport_arena.size()
737    }
738
739    /// Base GPA to which the page tables are eagerly copied on restore.
740    pub(crate) fn get_pt_base_gpa(&self) -> u64 {
741        self.transport_arena.end_addr()
742    }
743
744    /// First GPA available to the guest scratch allocator.
745    pub(crate) fn get_first_free_scratch_gpa(&self) -> u64 {
746        self.get_pt_base_gpa() + self.pt_size.unwrap_or(0) as u64
747    }
748
749    /// Exact transport placement in the fixed scratch prefix.
750    pub(crate) fn get_transport_arena(&self) -> TransportArena {
751        self.transport_arena
752    }
753
754    /// Total size of guest memory in `self`'s memory layout.
755    fn get_unaligned_memory_size(&self) -> usize {
756        self.init_data_offset() + self.init_data_size
757    }
758
759    /// Total size of guest memory in `self`'s memory layout, aligned
760    /// to page size boundaries.
761    pub(crate) fn get_memory_size(&self) -> Result<usize> {
762        let total_memory = self.get_unaligned_memory_size();
763
764        // Size should be a multiple of host page size.
765        let remainder = total_memory % page_size::get();
766        let multiples = total_memory / page_size::get();
767        let size = match remainder {
768            0 => total_memory,
769            _ => (multiples + 1) * page_size::get(),
770        };
771
772        if size > Self::MAX_MEMORY_SIZE {
773            Err(MemoryRequestTooBig(size, Self::MAX_MEMORY_SIZE))
774        } else {
775            Ok(size)
776        }
777    }
778}
779
780#[cfg(test)]
781mod tests {
782    use super::*;
783
784    // helper func for testing
785    fn get_expected_memory_size(layout: &SandboxMemoryLayout) -> usize {
786        let mut expected_size = 0;
787        // in order of layout
788        expected_size += layout.code_size;
789
790        // PEB
791        let peb_and_array = size_of::<HyperlightPEB>();
792        expected_size += peb_and_array.next_multiple_of(PAGE_SIZE);
793
794        expected_size += layout.heap_size.next_multiple_of(PAGE_SIZE);
795
796        expected_size.next_multiple_of(page_size::get())
797    }
798
799    #[test]
800    fn test_get_memory_size() {
801        let sbox_cfg = SandboxConfiguration::default();
802        let sbox_mem_layout = SandboxMemoryLayout::new(sbox_cfg, 4096, 0, None).unwrap();
803        assert_eq!(
804            sbox_mem_layout.get_memory_size().unwrap(),
805            get_expected_memory_size(&sbox_mem_layout)
806        );
807    }
808
809    #[test]
810    fn transport_arena_starts_at_scratch_base() {
811        let cfg = SandboxConfiguration::default();
812        let mut layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
813        let arena = layout.get_transport_arena();
814        let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
815
816        assert_eq!(arena.base_addr(), scratch_base);
817        assert_eq!(layout.get_pt_base_gpa(), arena.end_addr());
818        assert_eq!(layout.get_pt_base_scratch_offset(), arena.size());
819
820        layout.set_pt_size(PAGE_SIZE).unwrap();
821
822        assert_eq!(layout.get_transport_arena(), arena);
823        assert_eq!(
824            layout.get_first_free_scratch_gpa(),
825            arena.end_addr() + PAGE_SIZE as u64
826        );
827    }
828
829    #[test]
830    fn transport_memory_is_part_of_minimum_scratch_size() {
831        let mut cfg = SandboxConfiguration::default();
832        let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
833        let minimum =
834            hyperlight_common::layout::min_scratch_size(layout.get_transport_arena().size());
835        cfg.set_scratch_size(minimum);
836        let mut layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
837
838        assert!(matches!(
839            layout.set_pt_size(PAGE_SIZE),
840            Err(MemoryRequestTooSmall(..))
841        ));
842    }
843
844    #[test]
845    fn transport_minimum_rejects_capacity_overflow() {
846        for (g2h_pages, h2g_pages) in [
847            (usize::MAX, 4),
848            (8, usize::MAX),
849            (usize::MAX / PAGE_SIZE, 1),
850        ] {
851            let mut cfg = SandboxConfiguration::default();
852            cfg.set_g2h_pool_pages(g2h_pages);
853            cfg.set_h2g_pool_pages(h2g_pages);
854
855            let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None);
856            assert!(matches!(layout, Err(MemoryRequestTooSmall(_, usize::MAX))));
857        }
858    }
859
860    #[test]
861    fn rejects_unaligned_scratch_size() {
862        let mut cfg = SandboxConfiguration::default();
863        cfg.set_scratch_size(SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1);
864
865        let error = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap_err();
866        assert_eq!(
867            error.to_string(),
868            format!(
869                "scratch size {} must be a multiple of {PAGE_SIZE}",
870                SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1
871            )
872        );
873    }
874
875    #[test]
876    fn code_gva_updates_code_region() {
877        let mut layout =
878            SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
879        let code_gva = 0x100_0000;
880        layout.set_code_gva(code_gva).unwrap();
881
882        assert_eq!(
883            layout.get_guest_code_gpa(),
884            SandboxMemoryLayout::BASE_ADDRESS
885        );
886        assert_eq!(layout.get_guest_code_gva(), code_gva as usize);
887        let code = layout
888            .get_memory_regions()
889            .unwrap()
890            .into_iter()
891            .find(|region| region.region_type == Code)
892            .unwrap();
893        assert_eq!(code.host_region.start, SandboxMemoryLayout::BASE_ADDRESS);
894        assert_eq!(code.guest_region.start, code_gva as usize);
895    }
896
897    #[test]
898    fn code_gva_rejects_overlap() {
899        let mut layout =
900            SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
901        assert!(layout.set_code_gva(layout.peb_address() as u64).is_err());
902    }
903
904    #[test]
905    fn test_max_memory_sandbox() {
906        let mut cfg = SandboxConfiguration::default();
907        // scratch_size exceeds 16 GiB limit
908        cfg.set_scratch_size(17 * 1024 * 1024 * 1024);
909        let layout = SandboxMemoryLayout::new(cfg, 4096, 4096, None);
910        assert!(matches!(layout.unwrap_err(), MemoryRequestTooBig(..)));
911    }
912
913    /// Pinned region offsets. These methods place every region that a
914    /// restored snapshot is interpreted against, so a change shifts
915    /// where the loader reads captured bytes and breaks existing
916    /// snapshots. Treat a failure as an ABI change: follow
917    /// docs/snapshot-versioning.md rather than editing the constants.
918    #[test]
919    fn layout_offsets_are_pinned() {
920        /// `assert_eq!` carrying the shared snapshot-ABI failure
921        /// message, mirroring `abi_assert!` in the snapshot tripwires.
922        macro_rules! pin_eq {
923            ($left:expr, $right:expr) => {
924                assert_eq!(
925                    $left, $right,
926                    "snapshot ABI changed: this breaks loading of existing snapshots. \
927                     Do not just update the expected value to make this compile. \
928                     See docs/snapshot-versioning.md."
929                );
930            };
931        }
932
933        // The scratch region's top GVA and GPA are baked into snapshot
934        // page tables by `map_specials`, so they are part of the
935        // snapshot ABI. The pins below fix offsets from this base.
936        #[cfg(target_arch = "x86_64")]
937        {
938            pin_eq!(
939                hyperlight_common::layout::SCRATCH_TOP_GVA,
940                0xffff_ffff_ffff_efff
941            );
942            pin_eq!(
943                hyperlight_common::layout::SCRATCH_TOP_GPA,
944                0x0000_000f_ffff_ffff
945            );
946        }
947        #[cfg(target_arch = "aarch64")]
948        {
949            pin_eq!(
950                hyperlight_common::layout::SCRATCH_TOP_GVA,
951                0x0000_ffff_ffff_dfff
952            );
953            pin_eq!(
954                hyperlight_common::layout::SCRATCH_TOP_GPA,
955                0x0000_000f_ffff_bfff
956            );
957        }
958
959        // `map_specials` bakes the IO page mapping into snapshot page
960        // tables, so its address is part of the snapshot ABI. amd64 has
961        // no IO page. aarch64 maps one fixed GPA to one fixed GVA.
962        #[cfg(target_arch = "x86_64")]
963        pin_eq!(hyperlight_common::layout::io_page(), None);
964        #[cfg(target_arch = "aarch64")]
965        pin_eq!(
966            hyperlight_common::layout::io_page(),
967            Some((0x0000_000f_ffff_f000, 0x0000_ffff_ffff_e000))
968        );
969
970        let mut cfg = SandboxConfiguration::default();
971        cfg.set_heap_size(0x2000);
972        cfg.set_scratch_size(0x30000);
973        let layout = SandboxMemoryLayout::new(cfg, 0x1000, 0, None).unwrap();
974
975        pin_eq!(layout.guest_code_offset(), 0);
976        pin_eq!(layout.peb_offset(), 0x1000);
977        pin_eq!(layout.peb_address(), 0x5000);
978        pin_eq!(layout.guest_heap_buffer_offset(), 0x2000);
979        pin_eq!(layout.init_data_offset(), 0x4000);
980        pin_eq!(layout.get_memory_size().unwrap(), 0x4000);
981
982        pin_eq!(layout.get_scratch_size(), 0x30000);
983        pin_eq!(layout.get_pt_size(), 0);
984
985        pin_eq!(layout.get_pt_base_scratch_offset(), 0x15000);
986
987        let arena = layout.get_transport_arena();
988        let scratch_base_gpa = hyperlight_common::layout::scratch_base_gpa(0x30000);
989        pin_eq!(arena.g2h_ring_addr() - scratch_base_gpa, 0);
990        pin_eq!(arena.h2g_ring_addr() - scratch_base_gpa, 0x410);
991        pin_eq!(arena.mbx_addr() - scratch_base_gpa, 0x618);
992        pin_eq!(arena.g2h_pool_addr() - scratch_base_gpa, 0x1000);
993        pin_eq!(arena.h2g_pool_addr() - scratch_base_gpa, 0xd000);
994        pin_eq!(arena.end_addr() - scratch_base_gpa, 0x15000);
995
996        // The transport arena sits at the scratch base. The page tables
997        // follow it. With the `SCRATCH_TOP` pins above, these fix the
998        // absolute addresses.
999        pin_eq!(
1000            layout.get_pt_base_gpa() - hyperlight_common::layout::scratch_base_gpa(0x30000),
1001            0x15000
1002        );
1003        // pt_size is zero here, so the first free scratch GPA equals
1004        // the page table base.
1005        pin_eq!(
1006            layout.get_first_free_scratch_gpa(),
1007            layout.get_pt_base_gpa()
1008        );
1009
1010        // A second snapshot layout keeps the transport prefix fixed
1011        // relative to its scratch base.
1012        let mut cfg = SandboxConfiguration::default();
1013        cfg.set_heap_size(0x5000);
1014        cfg.set_scratch_size(0x40000);
1015        let layout = SandboxMemoryLayout::new(cfg, 0x3000, 0, None).unwrap();
1016
1017        pin_eq!(layout.guest_code_offset(), 0);
1018        pin_eq!(layout.peb_offset(), 0x3000);
1019        pin_eq!(layout.peb_address(), 0x7000);
1020        pin_eq!(layout.guest_heap_buffer_offset(), 0x4000);
1021        pin_eq!(layout.init_data_offset(), 0x9000);
1022        pin_eq!(
1023            layout.get_memory_size().unwrap(),
1024            0x9000_usize.next_multiple_of(page_size::get())
1025        );
1026
1027        pin_eq!(layout.get_scratch_size(), 0x40000);
1028        pin_eq!(layout.get_pt_size(), 0);
1029
1030        pin_eq!(layout.get_pt_base_scratch_offset(), 0x15000);
1031
1032        let arena = layout.get_transport_arena();
1033        let scratch_base_gpa = hyperlight_common::layout::scratch_base_gpa(0x40000);
1034        pin_eq!(arena.g2h_ring_addr() - scratch_base_gpa, 0);
1035        pin_eq!(arena.h2g_ring_addr() - scratch_base_gpa, 0x410);
1036        pin_eq!(arena.mbx_addr() - scratch_base_gpa, 0x618);
1037        pin_eq!(arena.g2h_pool_addr() - scratch_base_gpa, 0x1000);
1038        pin_eq!(arena.h2g_pool_addr() - scratch_base_gpa, 0xd000);
1039        pin_eq!(arena.end_addr() - scratch_base_gpa, 0x15000);
1040
1041        pin_eq!(
1042            layout.get_pt_base_gpa() - hyperlight_common::layout::scratch_base_gpa(0x40000),
1043            0x15000
1044        );
1045        pin_eq!(
1046            layout.get_first_free_scratch_gpa(),
1047            layout.get_pt_base_gpa()
1048        );
1049    }
1050}