Module vm_memory::guest_memory

Traits to track and access the physical memory of the guest.

To make the abstraction as generic as possible, all the core traits declared here only define methods to access guest’s memory, and never define methods to manage (create, delete, insert, remove etc) guest’s memory. This way, the guest memory consumers (virtio device drivers, vhost drivers and boot loaders etc) may be decoupled from the guest memory provider (typically a hypervisor).

Traits and Structs

• GuestAddress: represents a guest physical address (GPA).
• MemoryRegionAddress: represents an offset inside a region.
• GuestMemoryRegion: represent a continuous region of guest’s physical memory.
• GuestMemory: represent a collection of GuestMemoryRegion objects. The main responsibilities of the GuestMemory trait are:
  • hide the detail of accessing guest’s physical address.
  • map a request address to a GuestMemoryRegion object and relay the request to it.
  • handle cases where an access request spanning two or more GuestMemoryRegion objects.

Whenever a collection of GuestMemoryRegion objects is mutable, GuestAddressSpace should be implemented for clients to obtain a GuestMemory reference or smart pointer.

The GuestMemoryRegion trait has an associated B: Bitmap type which is used to handle dirty bitmap tracking. Backends are free to define the granularity (or whether tracking is actually performed at all). Those that do implement tracking functionality are expected to ensure the correctness of the underlying Bytes implementation. The user has to explicitly record (using the handle returned by GuestRegionMmap::bitmap) write accesses performed via pointers, references, or slices returned by methods of GuestMemory,GuestMemoryRegion, VolatileSlice, VolatileRef, or VolatileArrayRef.

Structs

• FileOffset
  Represents the start point within a File that backs a GuestMemoryRegion.
• GuestAddress
  Represents a guest physical address (GPA).
• MemoryRegionAddress
  Represents an offset inside a region.

Enums

• Error
  Errors associated with handling guest memory accesses.

Traits

• GuestAddressSpace
  GuestAddressSpace provides a way to retrieve a GuestMemory object. The vm-memory crate already provides trivial implementation for references to GuestMemory or reference-counted GuestMemory objects, but the trait can also be implemented by any other struct in order to provide temporary access to a snapshot of the memory map.
• GuestMemory
  GuestMemory represents a container for an immutable collection of GuestMemoryRegion objects. GuestMemory provides the Bytes<GuestAddress> trait to hide the details of accessing guest memory by physical address. Interior mutability is not allowed for implementations of GuestMemory so that they always provide a consistent view of the memory map.
• GuestMemoryIterator
  Lifetime generic associated iterators. The actual iterator type is defined through associated item Iter, for example:
• GuestMemoryRegion
  Represents a continuous region of guest physical memory.

Type Aliases

• GuestUsize
  Type of the raw value stored in a GuestAddress object.
• Result
  Result of guest memory operations.