Struct virtio_device::mem::DeviceRange

pub struct DeviceRange<'a>(/* private fields */);

Represents a range of memory as seen from the device.

A DeviceRange can be accessed through the try_ptr and try_mut_ptr methods. Although these functions are guaranteed to point to valid memory, due to the requirements on new, raw pointers are still returned as the memory may always be being modified in parallel by the guest and so references cannot be safely created. The onus therefore is on the caller to access this memory in a way that is safe under concurrent modifications.

Although there may be concurrent modifications, these are only from the guest, and it can be assumed that a DeviceRange does not alias any other Rust objects from the heap, stack, globals etc.

With the requirements on new users of a DeviceRange can assume that pointers returned from try_ptr and try_mut_ptr are valid for reads and writes and are correctly aligned. Further, it can be assumed that ptr.offset(N) is valid for any N < len() / size_of::<T>(). These pointer are only valid as long as the original DeviceRange is still alive.

The expected way to get DeviceRange is through DriverMem::translate, and it is only implementations of that trait that are expected to use new and actually construct a DeviceRange.

Implementations

impl<'a> DeviceRange<'a>

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

Split the range at offset producing two new ranges.

Returns None if offset is not in the range, otherwise produces the two ranges [start.. start + offset) and [start + offset ..end).

pub fn len(&self) -> usize

pub unsafe fn new(range: Range<usize>) -> Self

Construct a new DeviceRange.

Safety

The provided range must be:

• Valid memory that can be read or written to if it were cast to a pointer.
• Not alias any Rust objects from the heap, stack, globals etc.
• Remain valid for the lifetime 'a.

pub fn try_mut_ptr<T>(&self) -> Option<*mut T>

Attempt to get a pointer to a mutable T at the start of the range.

Returns a None if the range is too small to represent a T, or if the start of the range has the wrong alignment. Although there ways to safely perform accesses to unaligned pointers, as virtio requires all objects to be placed with correct alignment any misalignment represents a configuration issue.

The caller may assume that if a pointer is returned that it is valid for reads and writes of an object of size and alignment of T, however no guarantee is made on T being a copy-able object that can be safely read or written. Further, the returned pointer is valid only as long as the underlying DeviceRange is alive.

pub fn try_ptr<T>(&self) -> Option<*const T>

Attempt to get a pointer to a T at the start of the range.

See try_mut_ptr.

pub fn get(&self) -> Range<usize>

Retrieve the underlying range.

Trait Implementations

impl<'a> Clone for DeviceRange<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for DeviceRange<'a>

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

Formats the value using the given formatter.

impl<'a> PartialEq for DeviceRange<'a>

fn eq(&self, other: &DeviceRange<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Eq for DeviceRange<'a>

impl<'a> StructuralPartialEq for DeviceRange<'a>