hyperlight-common 0.18.0

Hyperlight's components common to host and guest.
Documentation
// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 The Hyperlight Authors.

use super::*;

fn make_slot_pool(slot_count: usize, slot_size: usize) -> SlotPool {
    let layout = SlotLayout::new(0x80000, slot_size, slot_count).unwrap();
    SlotPool::new(layout).unwrap()
}

fn make_tiered_slot_pool(lower_count: usize, upper_count: usize) -> SlotPool {
    let lower = SlotLayout::new(0x80000, 256, lower_count).unwrap();
    let upper = SlotLayout::new(0x90000, 4096, upper_count).unwrap();
    SlotPool::new_tiered(lower, upper).unwrap()
}

#[test]
fn test_slot_pool_preserves_exact_base() {
    let layout = SlotLayout::new(0x80001, 4096, 2).unwrap();
    assert_eq!(layout.base_addr(), 0x80001);
    assert_eq!(layout.slot_size(), 4096);
    assert_eq!(layout.slot_count(), 2);
    assert_eq!(layout.byte_len(), 8192);
    assert_eq!(layout.end_addr(), 0x82001);

    let pool = SlotPool::new(layout).unwrap();

    assert_eq!(pool.base_addr(), 0x80001);
    assert_eq!(pool.byte_len(), 8192);
    assert_eq!(pool.count(), 2);
    assert_eq!(pool.slot_addr(0), Some(0x80001));
    assert_eq!(pool.slot_addr(1), Some(0x81001));
}

#[test]
fn test_tiered_slot_pool_reports_layouts() {
    let lower = SlotLayout::new(0x80001, 0x100, 2).unwrap();
    let upper = SlotLayout::new(0x90001, 0x1000, 2).unwrap();
    let pool = SlotPool::new_tiered(lower, upper).unwrap();

    let (lower, upper) = pool.layouts();
    assert_eq!(lower, Some(SlotLayout::new(0x80001, 0x100, 2).unwrap()));
    assert_eq!(upper, SlotLayout::new(0x90001, 0x1000, 2).unwrap());
    assert_eq!(pool.base_addr(), 0x80001);
    assert_eq!(pool.byte_len(), 0x12000);
    assert_eq!(pool.slot_size(), 0x1000);
    assert_eq!(pool.count(), 4);
    assert_eq!(pool.slot_addr(0), Some(0x80001));
    assert_eq!(pool.slot_addr(1), Some(0x80101));
    assert_eq!(pool.slot_addr(2), Some(0x90001));
    assert_eq!(pool.slot_addr(3), Some(0x91001));
    assert_eq!(pool.slot_addr(4), None);
}

#[test]
fn test_tiered_slot_pool_combines_contiguous_equal_sized_layouts() {
    let lower = SlotLayout::new(0x80000, 0x100, 2).unwrap();
    let upper = SlotLayout::new(0x80200, 0x100, 3).unwrap();
    let pool = SlotPool::new_tiered(lower, upper).unwrap();

    assert_eq!(
        pool.layouts(),
        (None, SlotLayout::new(0x80000, 0x100, 5).unwrap())
    );
    assert_eq!(pool.base_addr(), 0x80000);
    assert_eq!(pool.byte_len(), 0x500);
    assert_eq!(pool.slot_size(), 0x100);
    assert_eq!(pool.count(), 5);
    assert_eq!(pool.num_free_lower(), 0);
    assert_eq!(pool.num_free_upper(), 5);
    assert_eq!(pool.slot_addr(4), Some(0x80400));
}

#[test]
fn test_tiered_slot_pool_rejects_invalid_layout() {
    let lower = SlotLayout::new(0x80000, 0x100, 32).unwrap();
    let overlapping_upper = SlotLayout::new(0x81000, 0x1000, 2).unwrap();
    let overlapping = SlotPool::new_tiered(lower, overlapping_upper);
    assert!(matches!(overlapping, Err(AllocError::InvalidArg)));

    let lower = SlotLayout::new(0x80000, 0x100, 2).unwrap();
    let separated_upper = SlotLayout::new(0x80300, 0x100, 2).unwrap();
    let separated = SlotPool::new_tiered(lower, separated_upper);
    assert!(matches!(separated, Err(AllocError::InvalidArg)));

    let lower = SlotLayout::new(0x80000, 0x1000, 2).unwrap();
    let smaller_upper = SlotLayout::new(0x90000, 0x100, 32).unwrap();
    let reversed_sizes = SlotPool::new_tiered(lower, smaller_upper);
    assert!(matches!(reversed_sizes, Err(AllocError::InvalidArg)));
}

#[cfg(target_pointer_width = "64")]
#[test]
fn test_slot_layout_rejects_unrepresentable_slot_size() {
    assert!(matches!(
        SlotLayout::new(0x80000, u32::MAX as usize + 1, 1),
        Err(AllocError::InvalidArg)
    ));
}

#[test]
fn test_slot_layout_rejects_empty_geometry() {
    assert!(matches!(
        SlotLayout::new(0, 0, 1),
        Err(AllocError::InvalidArg)
    ));
    assert!(matches!(
        SlotLayout::new(0, 1, 0),
        Err(AllocError::EmptyRegion)
    ));
}

#[test]
fn test_slot_layout_accepts_maximum_descriptor_capacity() {
    let layout = SlotLayout::new(0, u32::MAX as usize, 1).unwrap();
    assert_eq!(layout.slot_size(), u32::MAX as usize);
    assert_eq!(layout.byte_len(), u32::MAX as usize);
    assert_eq!(layout.end_addr(), u64::from(u32::MAX));
}

#[test]
fn test_slot_layout_rejects_overflowing_ranges() {
    assert!(matches!(
        SlotLayout::new(0, u32::MAX as usize, usize::MAX),
        Err(AllocError::Overflow)
    ));
    assert!(matches!(
        SlotLayout::new(u64::MAX, 1, 1),
        Err(AllocError::Overflow)
    ));
    assert!(matches!(
        SlotLayout::new(u64::MAX - 7, 4, 2),
        Err(AllocError::Overflow)
    ));

    let layout = SlotLayout::new(u64::MAX - 8, 4, 2).unwrap();
    assert_eq!(layout.end_addr(), u64::MAX);

    let pool = SlotPool::new(layout).unwrap();
    assert_eq!(pool.byte_len(), 8);
}

#[test]
fn test_slot_layout_bounds_free_list_capacity() {
    let max_slots = isize::MAX as usize / core::mem::size_of::<u64>();
    let layout = SlotLayout::new(0, 1, max_slots).unwrap();
    assert_eq!(layout.slot_count(), max_slots);

    assert!(matches!(
        SlotLayout::new(0, 1, max_slots + 1),
        Err(AllocError::Overflow)
    ));
}

#[test]
fn test_tiered_slot_pool_validates_merged_capacity_before_allocating() {
    let max_slots = isize::MAX as usize / core::mem::size_of::<u64>();
    let lower = SlotLayout::new(0, 1, max_slots).unwrap();
    let upper = SlotLayout::new(lower.end_addr(), 1, 1).unwrap();

    assert!(matches!(
        SlotPool::new_tiered(lower, upper),
        Err(AllocError::Overflow)
    ));
}

#[test]
fn test_tiered_slot_pool_routes_by_size() {
    let pool = make_tiered_slot_pool(2, 2);
    let lower = pool.alloc(128).unwrap();
    let upper = pool.alloc(257).unwrap();

    assert_eq!(lower.len, 256);
    assert!((0x80000..0x80200).contains(&lower.addr));
    assert_eq!(upper.len, 4096);
    assert!((0x90000..0x92000).contains(&upper.addr));
    assert_eq!(pool.allocation_len(lower.addr).unwrap(), 256);
    assert_eq!(pool.allocation_len(upper.addr).unwrap(), 4096);
}

#[test]
fn test_tiered_slot_pool_lower_falls_back_when_full() {
    let pool = make_tiered_slot_pool(1, 2);

    let lower = pool.alloc(128).unwrap();
    let fallback = pool.alloc(128).unwrap();

    assert_eq!(lower.len, 256);
    assert_eq!(fallback.len, 4096);
    assert!((0x90000..0x92000).contains(&fallback.addr));
}

#[test]
fn test_tiered_slot_pool_does_not_mask_lower_errors() {
    let pool = make_tiered_slot_pool(1, 1);

    assert!(matches!(pool.alloc(0), Err(AllocError::InvalidArg)));
    assert!(matches!(pool.alloc(4097), Err(AllocError::OutOfMemory)));
    assert_eq!(pool.num_free(), 2);
}

#[test]
fn test_tiered_slot_pool_reports_free_tier_counts() {
    let pool = make_tiered_slot_pool(2, 3);

    assert_eq!(pool.num_free_lower(), 2);
    assert_eq!(pool.num_free_upper(), 3);

    let lower = pool.alloc(128).unwrap();
    let upper = pool.alloc(4096).unwrap();
    assert_eq!(pool.num_free_lower(), 1);
    assert_eq!(pool.num_free_upper(), 2);

    pool.dealloc(lower.addr).unwrap();
    pool.dealloc(upper.addr).unwrap();
    assert_eq!(pool.num_free_lower(), 2);
    assert_eq!(pool.num_free_upper(), 3);
}

#[test]
fn test_tiered_slot_pool_dealloc_routes_by_region() {
    let pool = make_tiered_slot_pool(1, 1);
    let lower = pool.alloc(128).unwrap();
    let upper = pool.alloc(1024).unwrap();

    pool.dealloc(lower.addr).unwrap();
    pool.dealloc(upper.addr).unwrap();
    assert_eq!(pool.num_free(), 2);
    assert!(matches!(
        pool.dealloc(lower.addr),
        Err(AllocError::InvalidFree(_, _))
    ));
    assert!(matches!(
        pool.dealloc(0x88000),
        Err(AllocError::InvalidFree(_, _))
    ));
}

#[test]
fn test_tiered_slot_pool_live_addrs_are_deterministic() {
    let pool = make_tiered_slot_pool(2, 2);
    assert_eq!(pool.num_live(), 0);

    let lower_high = pool.alloc(128).unwrap();
    let upper_high = pool.alloc(1024).unwrap();
    let lower_low = pool.alloc(128).unwrap();

    assert_eq!(pool.num_live(), 3);
    assert_eq!(
        pool.live_addrs(),
        vec![lower_low.addr, lower_high.addr, upper_high.addr]
    );
}

#[test]
fn test_slot_pool_dealloc_out_of_range() {
    let pool = make_slot_pool(4, 4096);
    let _ = pool.alloc(4096).unwrap();

    assert!(matches!(
        pool.dealloc(0xDEAD),
        Err(AllocError::InvalidFree(0xDEAD, 0))
    ));
}

#[test]
fn test_slot_pool_dealloc_misaligned() {
    let pool = make_slot_pool(4, 4096);
    let _ = pool.alloc(4096).unwrap();

    assert!(matches!(
        pool.dealloc(0x80001),
        Err(AllocError::InvalidFree(0x80001, 0))
    ));
}

#[test]
fn test_slot_pool_dealloc_double_free() {
    let pool = make_slot_pool(4, 4096);
    let a = pool.alloc(4096).unwrap();
    pool.dealloc(a.addr).unwrap();

    // Second dealloc should fail - address is already in the free list
    assert!(matches!(
        pool.dealloc(a.addr),
        Err(AllocError::InvalidFree(_, _))
    ));
}

#[test]
fn test_slot_pool_dealloc_addr_and_allocation_len() {
    let pool = make_slot_pool(4, 4096);
    let alloc = pool.alloc(4096).unwrap();

    assert_eq!(pool.allocation_len(alloc.addr).unwrap(), 4096);
    pool.dealloc(alloc.addr).unwrap();
    assert!(matches!(
        pool.allocation_len(alloc.addr),
        Err(AllocError::InvalidFree(_, 0))
    ));
}

#[test]
fn test_slot_pool_random_order_dealloc() {
    let pool = make_slot_pool(8, 4096);

    let mut allocs: Vec<Allocation> = (0..8).map(|_| pool.alloc(4096).unwrap()).collect();
    assert_eq!(pool.num_free(), 0);

    // Dealloc in reverse order
    allocs.reverse();
    for a in &allocs {
        pool.dealloc(a.addr).unwrap();
    }
    assert_eq!(pool.num_free(), 8);

    // All slots should be re-allocatable
    let reallocs: Vec<Allocation> = (0..8).map(|_| pool.alloc(4096).unwrap()).collect();
    assert_eq!(pool.num_free(), 0);

    // Verify all addresses are distinct
    let mut addrs: Vec<u64> = reallocs.iter().map(|a| a.addr).collect();
    addrs.sort();
    addrs.dedup();
    assert_eq!(addrs.len(), 8);
}

#[test]
fn test_slot_pool_interleaved_alloc_dealloc_order() {
    let pool = make_slot_pool(4, 4096);

    let a0 = pool.alloc(4096).unwrap();
    let a1 = pool.alloc(4096).unwrap();
    let a2 = pool.alloc(4096).unwrap();
    let a3 = pool.alloc(4096).unwrap();
    assert_eq!(pool.num_free(), 0);

    // Free middle slots first (out of allocation order)
    pool.dealloc(a2.addr).unwrap();
    pool.dealloc(a0.addr).unwrap();
    assert_eq!(pool.num_free(), 2);

    // Re-alloc gets the out-of-order slots back (LIFO)
    let b0 = pool.alloc(4096).unwrap();
    assert_eq!(b0.addr, a0.addr);
    let b1 = pool.alloc(4096).unwrap();
    assert_eq!(b1.addr, a2.addr);

    // Free everything in yet another order
    pool.dealloc(a1.addr).unwrap();
    pool.dealloc(b0.addr).unwrap();
    pool.dealloc(b1.addr).unwrap();
    pool.dealloc(a3.addr).unwrap();
    assert_eq!(pool.num_free(), 4);

    // All 4 original addresses should be available
    let mut final_addrs: Vec<u64> = (0..4).map(|_| pool.alloc(4096).unwrap().addr).collect();
    final_addrs.sort();
    let expected: Vec<u64> = (0..4).map(|i| 0x80000 + i * 4096).collect();
    assert_eq!(final_addrs, expected);
}

#[test]
fn test_slot_pool_dealloc_order_independent_of_alloc_order() {
    let pool = make_slot_pool(6, 256);

    // Allocate all
    let allocs: Vec<Allocation> = (0..6).map(|_| pool.alloc(256).unwrap()).collect();

    // Dealloc in scattered order: 4, 1, 5, 0, 3, 2
    let order = [4, 1, 5, 0, 3, 2];
    for &i in &order {
        pool.dealloc(allocs[i].addr).unwrap();
    }
    assert_eq!(pool.num_free(), 6);

    // Re-allocate all and verify we get back the full set
    let mut realloc_addrs: Vec<u64> = (0..6).map(|_| pool.alloc(256).unwrap().addr).collect();
    realloc_addrs.sort();

    let mut orig_addrs: Vec<u64> = allocs.iter().map(|a| a.addr).collect();
    orig_addrs.sort();

    assert_eq!(realloc_addrs, orig_addrs);
}