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//! |                PEB Struct                 | (HyperlightPEB size)
16//! +-------------------------------------------+
17//! |               Guest Code                  |
18//! +-------------------------------------------+ 0x1_000
19//! |              NULL guard page              |
20//! +-------------------------------------------+ 0x0_000
21//!
22//! Everything except for the guest page tables is currently
23//! identity-mapped; the guest page tables themselves are mapped at
24//! [`hyperlight_common::layout::SNAPSHOT_PT_GVA`] =
25//! 0xffff_8000_0000_0000.
26//!
27//! - `InitData` - some extra data that can be loaded onto the sandbox during
28//!   initialization.
29//!
30//! The guest heap is outside this layout. The guest maps heap pages
31//! from scratch on first touch.
32//!
33//! There is also a scratch region at the top of physical memory,
34//! which is mostly laid out as a large undifferentiated blob of
35//! memory. The copied page tables start at the scratch base, which moves
36//! with the scratch size. The transport arena's address does not depend
37//! on the scratch size:
38//!
39//! +-------------------------------------------+ (top of physical memory)
40//! |         Exception Stack, Metadata         |
41//! +-------------------------------------------+ (reserved pages below)
42//! | Guard page (not in the guest page tables) |
43//! +-------------------------------------------+ (SCRATCH_TRANSPORT_GAP_PAGES)
44//! |              Transport Arena              |
45//! +-------------------------------------------+
46//! |              Scratch Memory               |
47//! +-------------------------------------------+
48//! |             Guest Page Tables             |
49//! +-------------------------------------------+ (scratch size)
50
51use std::fmt::Debug;
52use std::mem::size_of;
53
54use hyperlight_common::layout::{QueueDims, TransportArena};
55use hyperlight_common::mem::HyperlightPEB;
56use hyperlight_common::vmem::PAGE_SIZE;
57use tracing::{Span, instrument};
58
59use super::memory_region::MemoryRegionType::{Code, InitData, Peb};
60use super::memory_region::{
61    DEFAULT_GUEST_BLOB_MEM_FLAGS, GuestMemoryRegion, MemoryRegion_, MemoryRegionFlags,
62    MemoryRegionVecBuilder,
63};
64use crate::error::HyperlightError::{MemoryRequestTooBig, MemoryRequestTooSmall};
65use crate::sandbox::SandboxConfiguration;
66use crate::{Result, new_error};
67
68#[derive(Copy, Clone)]
69pub(crate) struct SandboxMemoryLayout {
70    /// The size of the guest code section.
71    code_size: usize,
72    /// Guest virtual address of the code section.
73    code_gva: usize,
74    /// The size of the init data section (guest blob).
75    init_data_size: usize,
76    /// Permission flags for the init data region.
77    init_data_permissions: Option<MemoryRegionFlags>,
78    /// The size of the scratch region in physical memory.
79    scratch_size: usize,
80    /// G2H ring and buffer pool dimensions.
81    g2h_dims: QueueDims,
82    /// H2G ring and buffer pool dimensions.
83    h2g_dims: QueueDims,
84    /// Capacity of each G2H upper-tier buffer.
85    g2h_buffer_size: usize,
86    /// Capacity of each H2G buffer.
87    h2g_buffer_size: usize,
88    /// Fixed ring and pool placement within scratch.
89    transport_arena: TransportArena,
90}
91
92impl Debug for SandboxMemoryLayout {
93    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
94        let mut ff = f.debug_struct("SandboxMemoryLayout");
95        ff.field(
96            "Total Memory Size",
97            &format_args!("{:#x}", self.get_memory_size().unwrap_or(0)),
98        )
99        .field("Code Size", &format_args!("{:#x}", self.code_size))
100        .field("Code GVA", &format_args!("{:#x}", self.code_gva))
101        .field(
102            "Init Data Size",
103            &format_args!("{:#x}", self.init_data_size),
104        )
105        .field("Scratch Size", &format_args!("{:#x}", self.scratch_size))
106        .field("G2H Queue Size", &self.get_g2h_queue_size())
107        .field("H2G Queue Size", &self.get_h2g_queue_size())
108        .field("G2H Buffer Size", &self.g2h_buffer_size)
109        .field("H2G Buffer Size", &self.h2g_buffer_size)
110        .field("G2H Pool Pages", &self.get_g2h_pool_pages())
111        .field("H2G Pool Pages", &self.get_h2g_pool_pages())
112        .field(
113            "Guest Code Offset",
114            &format_args!("{:#x}", self.guest_code_offset()),
115        )
116        .field("PEB Offset", &format_args!("{:#x}", self.peb_offset()))
117        .field("PEB Address", &format_args!("{:#x}", self.peb_address()))
118        .field(
119            "Init Data Offset",
120            &format_args!("{:#x}", self.init_data_offset()),
121        )
122        .finish()
123    }
124}
125
126impl SandboxMemoryLayout {
127    /// The maximum amount of memory a single sandbox will be allowed.
128    ///
129    /// Both the scratch region and the snapshot region are bounded by
130    /// this size. The value is arbitrary but chosen to be large enough
131    /// for most workloads while preventing accidental resource exhaustion.
132    pub(crate) const MAX_MEMORY_SIZE: usize = (16 * 1024 * 1024 * 1024) - Self::BASE_ADDRESS; // 16 GiB - BASE_ADDRESS
133
134    /// The base address of the sandbox's memory.
135    pub(crate) const BASE_ADDRESS: usize = 0x4000;
136
137    /// Create a new `SandboxMemoryLayout` with the given
138    /// `SandboxConfiguration` and code size.
139    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
140    pub(crate) fn new(
141        cfg: SandboxConfiguration,
142        code_size: usize,
143        init_data_size: usize,
144        init_data_permissions: Option<MemoryRegionFlags>,
145    ) -> Result<Self> {
146        let scratch_size = cfg.get_scratch_size();
147        if scratch_size > Self::MAX_MEMORY_SIZE {
148            return Err(MemoryRequestTooBig(scratch_size, Self::MAX_MEMORY_SIZE));
149        }
150        if !scratch_size.is_multiple_of(PAGE_SIZE) {
151            return Err(new_error!(
152                "scratch size {scratch_size} must be a multiple of {PAGE_SIZE}"
153            ));
154        }
155        let g2h_queue_size = cfg.get_g2h_queue_size();
156        let h2g_queue_size = cfg.get_h2g_queue_size();
157        let g2h_buffer_size = cfg.get_g2h_buffer_size();
158        let h2g_buffer_size = cfg.get_h2g_buffer_size();
159        let g2h_pool_pages = cfg.get_g2h_pool_pages();
160        let h2g_pool_pages = cfg.get_h2g_pool_pages();
161
162        let g2h_dims = QueueDims::new(g2h_queue_size, g2h_pool_pages)
163            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
164        let h2g_dims = QueueDims::new(h2g_queue_size, h2g_pool_pages)
165            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
166        let transport_arena = Self::transport_arena_for(g2h_dims, h2g_dims)
167            .ok_or(MemoryRequestTooSmall(scratch_size, usize::MAX))?;
168        let min_scratch_size = Self::min_scratch_for(&transport_arena);
169        if scratch_size < min_scratch_size {
170            return Err(MemoryRequestTooSmall(
171                scratch_size,
172                min_scratch_size.next_multiple_of(Self::host_page_size()),
173            ));
174        }
175
176        let ret = Self {
177            code_size,
178            code_gva: Self::BASE_ADDRESS,
179            init_data_size,
180            init_data_permissions,
181            scratch_size,
182            g2h_dims,
183            h2g_dims,
184            g2h_buffer_size,
185            h2g_buffer_size,
186            transport_arena,
187        };
188        ret.get_memory_size()?;
189        Ok(ret)
190    }
191
192    /// Granularity the host maps scratch in: host pages, which can be
193    /// larger than the guest's.
194    pub(crate) fn host_page_size() -> usize {
195        PAGE_SIZE.max(page_size::get())
196    }
197
198    /// Fixed scratch overhead: the arena and the guard page above it count
199    /// as transport memory.
200    fn min_scratch_for(arena: &TransportArena) -> usize {
201        hyperlight_common::layout::min_scratch_size(
202            arena
203                .size()
204                .saturating_add(hyperlight_common::layout::SCRATCH_TRANSPORT_GAP_PAGES * PAGE_SIZE),
205        )
206    }
207
208    /// Smallest scratch for this layout before page tables.
209    pub(crate) fn min_scratch(&self) -> usize {
210        Self::min_scratch_for(&self.transport_arena)
211    }
212
213    /// The transport arena sits below the reserved top pages, at an
214    /// address that does not depend on the scratch size.
215    fn transport_arena_for(g2h: QueueDims, h2g: QueueDims) -> Option<TransportArena> {
216        let len = TransportArena::new(0, g2h, h2g)?.size() as u64;
217        let base = hyperlight_common::layout::scratch_transport_end_gpa().checked_sub(len)?;
218        TransportArena::new(base, g2h, h2g)
219    }
220
221    /// This layout with another scratch size. Room for the page tables is
222    /// checked when they are built (`ensure_page_tables_fit`), since their
223    /// size depends on the guest's mappings.
224    pub(crate) fn with_scratch_size(&self, scratch_size: usize) -> Result<Self> {
225        if scratch_size > Self::MAX_MEMORY_SIZE {
226            return Err(MemoryRequestTooBig(scratch_size, Self::MAX_MEMORY_SIZE));
227        }
228        // The host maps scratch in host pages, which can be larger than
229        // the guest's. A size checked here is one a restore can map.
230        let page = Self::host_page_size();
231        let min = self.min_scratch().next_multiple_of(page);
232        if scratch_size < min {
233            return Err(MemoryRequestTooSmall(scratch_size, min));
234        }
235        if !scratch_size.is_multiple_of(page) {
236            return Err(new_error!(
237                "scratch size {scratch_size} must be a multiple of {page}"
238            ));
239        }
240        let mut ret = *self;
241        ret.scratch_size = scratch_size;
242        Ok(ret)
243    }
244
245    /// Scratch offset of the transport arena.
246    pub(crate) fn arena_scratch_offset(&self) -> usize {
247        debug_assert!(
248            self.transport_arena.base_addr()
249                > hyperlight_common::layout::scratch_base_gpa(self.scratch_size),
250            "the minimum scratch size keeps the arena above the scratch base"
251        );
252        (self.transport_arena.base_addr()
253            - hyperlight_common::layout::scratch_base_gpa(self.scratch_size)) as usize
254    }
255
256    /// Scratch offset of the checkpoint mailbox.
257    pub(crate) fn mbx_scratch_offset(&self) -> usize {
258        self.arena_scratch_offset() + self.transport_arena.mbx_offset()
259    }
260
261    pub(crate) fn code_size(&self) -> usize {
262        self.code_size
263    }
264
265    pub(crate) fn init_data_size(&self) -> usize {
266        self.init_data_size
267    }
268
269    pub(crate) fn init_data_permissions(&self) -> Option<MemoryRegionFlags> {
270        self.init_data_permissions
271    }
272
273    pub(crate) fn get_scratch_size(&self) -> usize {
274        self.scratch_size
275    }
276
277    pub(crate) fn get_g2h_queue_size(&self) -> usize {
278        usize::from(self.g2h_dims.size().get())
279    }
280
281    pub(crate) fn get_h2g_queue_size(&self) -> usize {
282        usize::from(self.h2g_dims.size().get())
283    }
284
285    pub(crate) fn get_g2h_buffer_size(&self) -> usize {
286        self.g2h_buffer_size
287    }
288
289    pub(crate) fn get_h2g_buffer_size(&self) -> usize {
290        self.h2g_buffer_size
291    }
292
293    pub(crate) fn get_g2h_pool_pages(&self) -> usize {
294        self.g2h_dims.pool_pages().get()
295    }
296
297    pub(crate) fn get_h2g_pool_pages(&self) -> usize {
298        self.h2g_dims.pool_pages().get()
299    }
300
301    pub(crate) fn get_g2h_queue_dims(&self) -> QueueDims {
302        self.g2h_dims
303    }
304
305    pub(crate) fn get_h2g_queue_dims(&self) -> QueueDims {
306        self.h2g_dims
307    }
308
309    pub(crate) fn ensure_page_tables_fit(&self, page_table_len: usize) -> Result<()> {
310        let min_scratch = self.min_scratch().saturating_add(page_table_len);
311        if self.scratch_size < min_scratch {
312            // Report a size the host can map.
313            let page = Self::host_page_size();
314            return Err(MemoryRequestTooSmall(
315                self.scratch_size,
316                min_scratch.next_multiple_of(page),
317            ));
318        }
319        Ok(())
320    }
321
322    /// Returns the memory regions associated with this memory layout,
323    /// suitable for passing to a hypervisor for mapping into memory
324    pub(crate) fn get_memory_regions(&self) -> Result<Vec<MemoryRegion_<GuestMemoryRegion>>> {
325        let mut builder = MemoryRegionVecBuilder::new(Self::BASE_ADDRESS, Self::BASE_ADDRESS);
326
327        // code
328        let peb_offset = builder.push_page_aligned(
329            self.code_size,
330            MemoryRegionFlags::READ | MemoryRegionFlags::WRITE | MemoryRegionFlags::EXECUTE,
331            Code,
332        );
333
334        let expected_peb_offset = TryInto::<usize>::try_into(self.peb_offset())?;
335
336        if peb_offset != expected_peb_offset {
337            return Err(new_error!(
338                "PEB offset does not match expected PEB offset expected:  {}, actual:  {}",
339                expected_peb_offset,
340                peb_offset
341            ));
342        }
343
344        // PEB
345        let init_data_offset =
346            builder.push_page_aligned(size_of::<HyperlightPEB>(), MemoryRegionFlags::READ, Peb);
347
348        let expected_init_data_offset = TryInto::<usize>::try_into(self.init_data_offset())?;
349
350        if init_data_offset != expected_init_data_offset {
351            return Err(new_error!(
352                "Init Data offset does not match expected Init Data offset expected:  {}, actual:  {}",
353                expected_init_data_offset,
354                init_data_offset
355            ));
356        }
357
358        // init data
359        let after_init_offset = if self.init_data_size > 0 {
360            let mem_flags = self
361                .init_data_permissions
362                .unwrap_or(DEFAULT_GUEST_BLOB_MEM_FLAGS);
363            builder.push_page_aligned(self.init_data_size, mem_flags, InitData)
364        } else {
365            init_data_offset
366        };
367
368        let final_offset = after_init_offset;
369
370        let expected_final_offset = TryInto::<usize>::try_into(self.get_memory_size()?)?;
371
372        // This function is primarily used to construct
373        // GuestMemoryRegions used to populate initial guest page
374        // tables. Therefore, the regions above are aligned based on
375        // the guest page size. However, the total final size of the
376        // region mapped into the guest needs to be aligned based on
377        // the host page size. Therefore, align both of these values
378        // to both page sizes before comparing them.
379        let final_offset = final_offset.next_multiple_of(page_size::get());
380        let expected_final_offset =
381            expected_final_offset.next_multiple_of(hyperlight_common::vmem::PAGE_SIZE);
382
383        if final_offset != expected_final_offset {
384            return Err(new_error!(
385                "Final offset does not match expected Final offset expected:  {}, actual:  {}",
386                expected_final_offset,
387                final_offset
388            ));
389        }
390
391        let mut regions = builder.build();
392        for region in &mut regions {
393            if region.region_type == Code {
394                let end = self
395                    .code_gva
396                    .checked_add(region.guest_region.len())
397                    .ok_or_else(|| {
398                        new_error!(
399                            "code mapping overflow: base {:#x} + size {:#x}",
400                            self.code_gva,
401                            region.guest_region.len()
402                        )
403                    })?;
404                region.guest_region = self.code_gva..end;
405            }
406        }
407        Ok(regions)
408    }
409
410    /// Set the code GVA after checking that it does not overlap another region.
411    pub(crate) fn set_code_gva(&mut self, code_gva: u64) -> Result<()> {
412        let code_gva = usize::try_from(code_gva)?;
413        let code_end = code_gva
414            .checked_add(self.code_size.next_multiple_of(PAGE_SIZE))
415            .ok_or_else(|| {
416                new_error!(
417                    "code mapping overflow: base {:#x} + size {:#x}",
418                    code_gva,
419                    self.code_size
420                )
421            })?;
422        for region in self.get_memory_regions()? {
423            if region.region_type == Code {
424                continue;
425            }
426            if code_gva < region.guest_region.end && region.guest_region.start < code_end {
427                return Err(new_error!(
428                    "code mapping [{:#x}, {:#x}) conflicts with {:?} region [{:#x}, {:#x})",
429                    code_gva,
430                    code_end,
431                    region.region_type,
432                    region.guest_region.start,
433                    region.guest_region.end,
434                ));
435            }
436        }
437        self.code_gva = code_gva;
438        Ok(())
439    }
440
441    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
442    pub(crate) fn write_init_data(&self, out: &mut [u8], bytes: &[u8]) -> Result<()> {
443        out[self.init_data_offset()..self.init_data_offset() + self.init_data_size]
444            .copy_from_slice(bytes);
445        Ok(())
446    }
447
448    /// Write the finished memory layout to `mem` and return `Ok` if
449    /// successful.
450    ///
451    /// Note: `mem` may have been modified, even if `Err` was returned
452    /// from this function.
453    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
454    pub(crate) fn write_peb(&self, mem: &mut [u8]) -> Result<()> {
455        use hyperlight_common::mem::GuestMemoryRegion;
456
457        let guest_base = Self::BASE_ADDRESS as u64;
458
459        let peb = HyperlightPEB {
460            init_data: GuestMemoryRegion {
461                size: (self.get_unaligned_memory_size() - self.init_data_offset()) as u64,
462                ptr: guest_base + self.init_data_offset() as u64,
463            },
464        };
465
466        let offset = self.peb_offset();
467        let bytes = bytemuck::bytes_of(&peb);
468        let end = offset + bytes.len();
469        let mem_len = mem.len();
470        let dst = mem.get_mut(offset..end).ok_or_else(|| {
471            new_error!(
472                "memory too small to write PEB: need {} bytes at offset {:#x}, have {} bytes",
473                bytes.len(),
474                offset,
475                mem_len
476            )
477        })?;
478        dst.copy_from_slice(bytes);
479
480        Ok(())
481    }
482}
483
484/// Changes to the below methods is part of Snapshot ABI, and
485/// changing any output shifts where the loader
486/// reads captured bytes and breaks existing snapshots. Any change here
487/// is a snapshot ABI break: see the `layout_offsets_are_pinned` test
488/// and docs/snapshot-versioning.md.
489impl SandboxMemoryLayout {
490    /// Offset of the PEB struct within the snapshot region.
491    pub(crate) fn peb_offset(&self) -> usize {
492        self.code_size.next_multiple_of(PAGE_SIZE)
493    }
494
495    /// Guest physical address of the PEB.
496    pub(crate) fn peb_address(&self) -> usize {
497        Self::BASE_ADDRESS + self.peb_offset()
498    }
499
500    /// Offset of the init data section within the snapshot region.
501    pub(crate) fn init_data_offset(&self) -> usize {
502        (self.peb_offset() + size_of::<HyperlightPEB>()).next_multiple_of(PAGE_SIZE)
503    }
504
505    /// The code offset is always 0.
506    pub(crate) fn guest_code_offset(&self) -> usize {
507        0
508    }
509
510    /// Guest physical address of the code section.
511    pub(crate) fn get_guest_code_gpa(&self) -> usize {
512        Self::BASE_ADDRESS + self.guest_code_offset()
513    }
514
515    /// Guest virtual address of the code section.
516    pub(crate) fn get_guest_code_gva(&self) -> usize {
517        self.code_gva
518    }
519
520    /// Offset from the beginning of the scratch region to the location
521    /// where page tables are eagerly copied on restore.
522    pub(crate) fn get_pt_base_scratch_offset(&self) -> usize {
523        0
524    }
525
526    /// Base GPA to which the page tables are eagerly copied on restore.
527    pub(crate) fn get_pt_base_gpa(&self) -> u64 {
528        hyperlight_common::layout::scratch_base_gpa(self.scratch_size)
529    }
530
531    /// Exact transport placement below the reserved scratch-top pages.
532    pub(crate) fn get_transport_arena(&self) -> TransportArena {
533        self.transport_arena
534    }
535
536    /// Total size of guest memory in `self`'s memory layout.
537    fn get_unaligned_memory_size(&self) -> usize {
538        self.init_data_offset() + self.init_data_size
539    }
540
541    /// Total size of guest memory in `self`'s memory layout, aligned
542    /// to page size boundaries.
543    pub(crate) fn get_memory_size(&self) -> Result<usize> {
544        let total_memory = self.get_unaligned_memory_size();
545
546        // Size should be a multiple of host page size.
547        let remainder = total_memory % page_size::get();
548        let multiples = total_memory / page_size::get();
549        let size = match remainder {
550            0 => total_memory,
551            _ => (multiples + 1) * page_size::get(),
552        };
553
554        if size > Self::MAX_MEMORY_SIZE {
555            Err(MemoryRequestTooBig(size, Self::MAX_MEMORY_SIZE))
556        } else {
557            Ok(size)
558        }
559    }
560}
561
562#[cfg(test)]
563mod tests {
564    use super::*;
565
566    // helper func for testing
567    fn get_expected_memory_size(layout: &SandboxMemoryLayout) -> usize {
568        let mut expected_size = 0;
569        // in order of layout
570        expected_size += layout.code_size;
571
572        // PEB
573        let peb_and_array = size_of::<HyperlightPEB>();
574        expected_size += peb_and_array.next_multiple_of(PAGE_SIZE);
575
576        expected_size.next_multiple_of(page_size::get())
577    }
578
579    #[test]
580    fn test_get_memory_size() {
581        let sbox_cfg = SandboxConfiguration::default();
582        let sbox_mem_layout = SandboxMemoryLayout::new(sbox_cfg, 4096, 0, None).unwrap();
583        assert_eq!(
584            sbox_mem_layout.get_memory_size().unwrap(),
585            get_expected_memory_size(&sbox_mem_layout)
586        );
587    }
588
589    #[test]
590    fn transport_arena_sits_below_the_reserved_top() {
591        let cfg = SandboxConfiguration::default();
592        let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
593        let arena = layout.get_transport_arena();
594        let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
595
596        assert_eq!(
597            arena.end_addr()
598                + (hyperlight_common::layout::SCRATCH_TRANSPORT_GAP_PAGES * PAGE_SIZE) as u64,
599            hyperlight_common::layout::scratch_reserved_top_gpa()
600        );
601        assert_eq!(layout.get_pt_base_gpa(), scratch_base);
602        assert_eq!(layout.get_pt_base_scratch_offset(), 0);
603
604        layout.ensure_page_tables_fit(PAGE_SIZE).unwrap();
605
606        assert_eq!(layout.get_transport_arena(), arena);
607    }
608
609    /// A different scratch size keeps the arena where it is, so a guest's
610    /// cached ring addresses stay valid in a resized snapshot.
611    #[test]
612    fn resizing_scratch_keeps_the_transport_arena() {
613        let mut cfg = SandboxConfiguration::default();
614        cfg.set_scratch_size(4 << 20);
615        let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
616        // Sizes in host pages, which can be larger than the guest's.
617        let page = SandboxMemoryLayout::host_page_size();
618        let half = (layout.get_scratch_size() / 2).next_multiple_of(page);
619        let smaller = layout.with_scratch_size(half).unwrap();
620
621        assert_eq!(smaller.get_transport_arena(), layout.get_transport_arena());
622        assert_eq!(
623            smaller.get_pt_base_gpa(),
624            hyperlight_common::layout::scratch_base_gpa(half)
625        );
626        assert_eq!(
627            smaller.mbx_scratch_offset() + (layout.get_scratch_size() - half),
628            layout.mbx_scratch_offset()
629        );
630        assert!(matches!(
631            layout.with_scratch_size(layout.min_scratch() - 1),
632            Err(MemoryRequestTooSmall(..))
633        ));
634        assert!(layout.with_scratch_size(half + 1).is_err());
635        assert!(matches!(
636            layout.with_scratch_size(
637                SandboxMemoryLayout::MAX_MEMORY_SIZE.next_multiple_of(page) + page
638            ),
639            Err(MemoryRequestTooBig(..))
640        ));
641
642        let larger = layout
643            .with_scratch_size(layout.get_scratch_size() * 2)
644            .unwrap();
645        assert_eq!(larger.get_transport_arena(), layout.get_transport_arena());
646        assert_eq!(
647            larger.mbx_scratch_offset(),
648            layout.mbx_scratch_offset() + layout.get_scratch_size()
649        );
650    }
651
652    #[test]
653    fn transport_memory_is_part_of_minimum_scratch_size() {
654        let mut cfg = SandboxConfiguration::default();
655        let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
656        let minimum = layout.min_scratch();
657        cfg.set_scratch_size(minimum);
658        let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap();
659
660        assert!(matches!(
661            layout.ensure_page_tables_fit(PAGE_SIZE),
662            Err(MemoryRequestTooSmall(..))
663        ));
664    }
665
666    #[test]
667    fn transport_minimum_rejects_capacity_overflow() {
668        for (g2h_pages, h2g_pages) in [
669            (usize::MAX, 4),
670            (8, usize::MAX),
671            (usize::MAX / PAGE_SIZE, 1),
672        ] {
673            let mut cfg = SandboxConfiguration::default();
674            cfg.set_g2h_pool_pages(g2h_pages);
675            cfg.set_h2g_pool_pages(h2g_pages);
676
677            let layout = SandboxMemoryLayout::new(cfg, 4096, 0, None);
678            assert!(matches!(layout, Err(MemoryRequestTooSmall(_, usize::MAX))));
679        }
680    }
681
682    #[test]
683    fn rejects_unaligned_scratch_size() {
684        let mut cfg = SandboxConfiguration::default();
685        cfg.set_scratch_size(SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1);
686
687        let error = SandboxMemoryLayout::new(cfg, 4096, 0, None).unwrap_err();
688        assert_eq!(
689            error.to_string(),
690            format!(
691                "scratch size {} must be a multiple of {PAGE_SIZE}",
692                SandboxConfiguration::DEFAULT_SCRATCH_SIZE + 1
693            )
694        );
695    }
696
697    #[test]
698    fn code_gva_updates_code_region() {
699        let mut layout =
700            SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
701        let code_gva = 0x100_0000;
702        layout.set_code_gva(code_gva).unwrap();
703
704        assert_eq!(
705            layout.get_guest_code_gpa(),
706            SandboxMemoryLayout::BASE_ADDRESS
707        );
708        assert_eq!(layout.get_guest_code_gva(), code_gva as usize);
709        let code = layout
710            .get_memory_regions()
711            .unwrap()
712            .into_iter()
713            .find(|region| region.region_type == Code)
714            .unwrap();
715        assert_eq!(code.host_region.start, SandboxMemoryLayout::BASE_ADDRESS);
716        assert_eq!(code.guest_region.start, code_gva as usize);
717    }
718
719    #[test]
720    fn code_gva_rejects_overlap() {
721        let mut layout =
722            SandboxMemoryLayout::new(SandboxConfiguration::default(), PAGE_SIZE, 0, None).unwrap();
723        assert!(layout.set_code_gva(layout.peb_address() as u64).is_err());
724    }
725
726    #[test]
727    fn test_max_memory_sandbox() {
728        let mut cfg = SandboxConfiguration::default();
729        // scratch_size exceeds 16 GiB limit
730        cfg.set_scratch_size(17 * 1024 * 1024 * 1024);
731        let layout = SandboxMemoryLayout::new(cfg, 4096, 4096, None);
732        assert!(matches!(layout.unwrap_err(), MemoryRequestTooBig(..)));
733    }
734
735    /// Pinned region offsets. These methods place every region that a
736    /// restored snapshot is interpreted against, so a change shifts
737    /// where the loader reads captured bytes and breaks existing
738    /// snapshots. Treat a failure as an ABI change: follow
739    /// docs/snapshot-versioning.md rather than editing the constants.
740    #[test]
741    fn layout_offsets_are_pinned() {
742        /// `assert_eq!` carrying the shared snapshot-ABI failure
743        /// message, mirroring `abi_assert!` in the snapshot tripwires.
744        macro_rules! pin_eq {
745            ($left:expr, $right:expr) => {
746                assert_eq!(
747                    $left, $right,
748                    "snapshot ABI changed: this breaks loading of existing snapshots. \
749                     Do not just update the expected value to make this compile. \
750                     See docs/snapshot-versioning.md."
751                );
752            };
753        }
754
755        // The scratch region's top GVA and GPA are baked into snapshot
756        // page tables by `map_specials`, so they are part of the
757        // snapshot ABI. The pins below fix offsets from this base.
758        #[cfg(target_arch = "x86_64")]
759        {
760            pin_eq!(
761                hyperlight_common::layout::SCRATCH_TOP_GVA,
762                0xffff_ffff_ffff_efff
763            );
764            pin_eq!(
765                hyperlight_common::layout::SCRATCH_TOP_GPA,
766                0x0000_000f_ffff_ffff
767            );
768        }
769        #[cfg(target_arch = "aarch64")]
770        {
771            pin_eq!(
772                hyperlight_common::layout::SCRATCH_TOP_GVA,
773                0x0000_ffff_ffff_dfff
774            );
775            pin_eq!(
776                hyperlight_common::layout::SCRATCH_TOP_GPA,
777                0x0000_000f_ffff_bfff
778            );
779        }
780
781        // `map_specials` bakes the IO page mapping into snapshot page
782        // tables, so its address is part of the snapshot ABI. amd64 has
783        // no IO page. aarch64 maps one fixed GPA to one fixed GVA.
784        #[cfg(target_arch = "x86_64")]
785        pin_eq!(hyperlight_common::layout::io_page(), None);
786        #[cfg(target_arch = "aarch64")]
787        pin_eq!(
788            hyperlight_common::layout::io_page(),
789            Some((0x0000_000f_ffff_f000, 0x0000_ffff_ffff_e000))
790        );
791
792        let mut cfg = SandboxConfiguration::default();
793        cfg.set_scratch_size(0x30000);
794        let layout = SandboxMemoryLayout::new(cfg, 0x1000, 0, None).unwrap();
795
796        pin_eq!(layout.guest_code_offset(), 0);
797        pin_eq!(layout.peb_offset(), 0x1000);
798        pin_eq!(layout.peb_address(), 0x5000);
799        pin_eq!(layout.init_data_offset(), 0x2000);
800        pin_eq!(
801            layout.get_memory_size().unwrap(),
802            0x2000_usize.next_multiple_of(page_size::get())
803        );
804
805        pin_eq!(layout.get_scratch_size(), 0x30000);
806        pin_eq!(layout.get_pt_base_scratch_offset(), 0);
807
808        // The transport arena sits below the reserved top pages, at an
809        // address that does not depend on the scratch size. The page
810        // tables start at the scratch base. With the `SCRATCH_TOP` pins
811        // above, these fix the absolute addresses.
812        let arena = layout.get_transport_arena();
813        let scratch_top = hyperlight_common::layout::SCRATCH_TOP_GPA as u64 + 1;
814        pin_eq!(scratch_top - arena.g2h_ring_addr(), 0x22000);
815        pin_eq!(arena.h2g_ring_addr() - arena.g2h_ring_addr(), 0x410);
816        pin_eq!(arena.mbx_addr() - arena.g2h_ring_addr(), 0x618);
817        pin_eq!(arena.g2h_pool_addr() - arena.g2h_ring_addr(), 0x1000);
818        pin_eq!(arena.h2g_pool_addr() - arena.g2h_ring_addr(), 0xd000);
819        pin_eq!(scratch_top - arena.end_addr(), 0xd000);
820        pin_eq!(
821            layout.get_pt_base_gpa(),
822            hyperlight_common::layout::scratch_base_gpa(0x30000)
823        );
824        // A second snapshot layout, with a different scratch size, keeps
825        // the transport arena at the same address.
826        let mut cfg = SandboxConfiguration::default();
827        cfg.set_scratch_size(0x40000);
828        let layout = SandboxMemoryLayout::new(cfg, 0x3000, 0, None).unwrap();
829
830        pin_eq!(layout.guest_code_offset(), 0);
831        pin_eq!(layout.peb_offset(), 0x3000);
832        pin_eq!(layout.peb_address(), 0x7000);
833        pin_eq!(layout.init_data_offset(), 0x4000);
834        pin_eq!(
835            layout.get_memory_size().unwrap(),
836            0x4000_usize.next_multiple_of(page_size::get())
837        );
838
839        pin_eq!(layout.get_scratch_size(), 0x40000);
840        pin_eq!(layout.get_pt_base_scratch_offset(), 0);
841
842        let arena = layout.get_transport_arena();
843        let scratch_top = hyperlight_common::layout::SCRATCH_TOP_GPA as u64 + 1;
844        pin_eq!(scratch_top - arena.g2h_ring_addr(), 0x22000);
845        pin_eq!(arena.h2g_ring_addr() - arena.g2h_ring_addr(), 0x410);
846        pin_eq!(arena.mbx_addr() - arena.g2h_ring_addr(), 0x618);
847        pin_eq!(arena.g2h_pool_addr() - arena.g2h_ring_addr(), 0x1000);
848        pin_eq!(arena.h2g_pool_addr() - arena.g2h_ring_addr(), 0xd000);
849        pin_eq!(scratch_top - arena.end_addr(), 0xd000);
850
851        pin_eq!(
852            layout.get_pt_base_gpa(),
853            hyperlight_common::layout::scratch_base_gpa(0x40000)
854        );
855    }
856}