Module ranges

guestmem

Module ranges 

Source
Expand description

Types representing contiguous and discontiguous ranges of guest memory.

The primary type is PagedRange, which describes a single logically contiguous byte range scattered across potentially-discontiguous guest pages. It is used throughout the storage and virtio stacks to describe IO buffers.

§Memory model

A PagedRange is defined by a GPN (guest page number) list, a starting byte offset, and a length. The byte range is a contiguous window into the flat byte space implied by concatenating the pages:

  gpns:   [ GPN_0 ]  [ GPN_1 ]  [ GPN_2 ]  [ GPN_3 ]
  bytes:  0    4095  4096  8191  8192 12287 12288 16383

               start                            end
                 │                               │
  GPN_0:  ░░░░░░░█████████   ◄── first page: partial (offset > 0)
  GPN_1:  ██████████████████ ◄── interior page: always fully covered
  GPN_2:  ██████████████████ ◄── interior page: always fully covered
  GPN_3:  █████████░░░░░░░░░ ◄── last page: partial (end < page boundary)

Key constraint: only the first and last pages may be partially covered. All interior pages are implicitly fully used. There is no way to express a gap or a non-zero starting offset on an interior page.

This means you cannot combine two arbitrary guest memory regions (e.g., two virtio descriptors with arbitrary GPAs) into a single PagedRange unless every region boundary falls on a page boundary. See PagedRanges for a type that can represent multiple disjoint PagedRanges as a single logical buffer.

Structs§

AddressRange
A range of bytes in the guest address space.
PagedRange
A single logically-contiguous byte range spread across guest pages.
PagedRangeRangeIter
An iterator returned by PagedRange::ranges().
PagedRangeReader
A MemoryRead implementation for PagedRange.
PagedRangeWriter
A MemoryWrite implementation for PagedRange.
PagedRanges
A list of PagedRanges.
PagedRangesIter
An iterator returned by PagedRanges::paged_ranges.
PagedRangesReader
A MemoryRead implementation for PagedRanges.
PagedRangesWriter
A MemoryWrite implementation for PagedRanges.