Struct PagedRange 

pub struct PagedRange<'a> { /* private fields */ }

A single logically-contiguous byte range spread across guest pages.

PagedRange is defined by a GPN (guest page number) slice, a byte offset into that slice’s implied flat address space, and a length.

Interior-page constraint

The first page may start at an arbitrary byte offset and the last page may end before the page boundary, but all interior pages are fully covered. There is no way to skip bytes within an interior page.

  VALID:     ░░████  ██████  ██████  ███░░░
  INVALID:   ░░████  ░░████  ██████  ███░░░
                      ▲ interior page cannot start at non-zero offset

This means two guest memory regions starting at arbitrary GPAs cannot always be represented by a single PagedRange. Use PagedRanges when you need to concatenate multiple independent regions.

Construction

Use PagedRange::new(offset, len, gpns) where offset is the byte offset into the page list and len is the total byte length. The GPN slice must be large enough to cover offset + len bytes.

Implementations

impl<'a> PagedRange<'a>

pub const PAGE_SIZE: usize = PAGE_SIZE

The page size for GPNs. This is always 4KB.

pub const fn new(offset: usize, len: usize, gpns: &'a [u64]) -> Option<Self>

Creates a new range over gpns, starting at offset bytes into the page list, extending for len bytes.

Returns None if offset or len are out of bounds.

pub const fn empty() -> Self

Returns the empty range.

pub fn try_subrange(&self, offset: usize, len: usize) -> Option<Self>

Returns a subrange of this range, or None if the subrange is outside this range.

pub fn subrange(&self, offset: usize, len: usize) -> Self

Returns a subrange of this range.

Panics if the subrange is outside this range.

pub fn len(&self) -> usize

Returns the length of the range in bytes.

pub fn is_empty(&self) -> bool

Returns whether the range is empty.

pub fn offset(&self) -> usize

Returns the byte offset into the first page of the range.

Only the first page can have a non-zero offset; all subsequent pages covered by the range are implicitly page-aligned.

pub fn gpns(&self) -> &'a [u64]

Returns the range’s list of page numbers.

pub fn skip(&mut self, len: usize)

Skips the first len bytes of the range.

Panics if len is larger than the range’s length.

pub fn truncate(&mut self, len: usize)

Truncates the range to len bytes.

Panics if len is larger than the range’s length.

pub fn split(self, offset: usize) -> (Self, Self)

Splits the range at offset.

Panics if offset is outside the range.

pub fn try_split(self, offset: usize) -> Option<(Self, Self)>

Splits the range at offset, returning None if offset is outside the range.

pub fn pop_front_range(&mut self) -> Option<Result<AddressRange, InvalidGpn>>

Removes and returns the first contiguous range.

pub fn reader(self, mem: &'a GuestMemory) -> PagedRangeReader<'a>

Returns a MemoryRead implementation.

pub fn writer(self, mem: &'a GuestMemory) -> PagedRangeWriter<'a>

Returns a MemoryWrite implementation.

pub fn ranges(self) -> PagedRangeRangeIter<'a>

Returns an iterator over the AddressRanges represented by this range.

Trait Implementations

impl<'a> Clone for PagedRange<'a>

fn clone(&self) -> PagedRange<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for PagedRange<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Copy for PagedRange<'a>