Struct Frame

#[repr(transparent)]
pub struct Frame<M: AnyFrameMeta + ?Sized> {
    ptr: *const MetaSlot,
    _marker: PhantomData<M>,
}

A smart pointer to a frame.

A frame is a contiguous range of bytes in physical memory. The Frame type is a smart pointer to a frame that is reference-counted.

Frames are associated with metadata. The type of the metadata M is determines the kind of the frame. If M implements AnyUFrameMeta, the frame is a untyped frame. Otherwise, it is a typed frame.

Fields

ptr: *const MetaSlot

_marker: PhantomData<M>

Implementations

impl<M: AnyFrameMeta> Frame<M>

pub fn from_unused(paddr: Paddr, metadata: M) -> Result<Self, GetFrameError>

Gets a Frame with a specific usage from a raw, unused page.

The caller should provide the initial metadata of the page.

If the provided frame is not truly unused at the moment, it will return an error. If wanting to acquire a frame that is already in use, use Frame::from_in_use instead.

pub fn meta(&self) -> &M

Gets the metadata of this page.

impl Frame<dyn AnyFrameMeta>

pub fn from_in_use(paddr: Paddr) -> Result<Self, GetFrameError>

Gets a dynamically typed Frame from a raw, in-use page.

If the provided frame is not in use at the moment, it will return an error.

The returned frame will have an extra reference count to the frame.

impl<M: AnyFrameMeta + ?Sized> Frame<M>

pub fn start_paddr(&self) -> Paddr

Gets the physical address of the start of the frame.

pub const fn map_level(&self) -> PagingLevel

Gets the map level of this page.

This is the level of the page table entry that maps the frame, which determines the size of the frame.

Currently, the level is always 1, which means the frame is a regular page frame.

pub const fn size(&self) -> usize

Gets the size of this page in bytes.

pub fn dyn_meta(&self) -> &dyn AnyFrameMeta

Gets the dyncamically-typed metadata of this frame.

If the type is known at compile time, use Frame::meta instead.

pub fn reference_count(&self) -> u64

Gets the reference count of the frame.

It returns the number of all references to the frame, including all the existing frame handles (Frame, Frame<dyn AnyFrameMeta>), and all the mappings in the page table that points to the frame.

Safety

The function is safe to call, but using it requires extra care. The reference count can be changed by other threads at any time including potentially between calling this method and acting on the result.

pub fn borrow(&self) -> FrameRef<'_, M>

Borrows a reference from the given frame.

pub(super) fn into_raw(self) -> Paddr

Forgets the handle to the frame.

This will result in the frame being leaked without calling the custom dropper.

A physical address to the frame is returned in case the frame needs to be restored using Frame::from_raw later. This is useful when some architectural data structures need to hold the frame handle such as the page table.

pub(super) unsafe fn from_raw(paddr: Paddr) -> Self

Restores a forgotten Frame from a physical address. For the frame pointed by paddr

• The frame must be forgotten by core::mem::forget, ManuallyDrop, or [into_raw].

fn slot(&self) -> &MetaSlot

impl<C: PageTableConfig> Frame<PageTablePageMeta<C>>

pub(super) fn level(&self) -> PagingLevel

pub(super) fn alloc(level: PagingLevel) -> Self

Allocates a new empty page table node.

pub(crate) unsafe fn activate(&self)

Activates the page table assuming it is a root page table.

Here we ensure not dropping an active page table by making a processor a page table owner. When activating a page table, the reference count of the last activated page table is decremented. And that of the current page table is incremented.

Safety

The caller must ensure that the page table to be activated has proper mappings for the kernel and has the correct const parameters matching the current CPU.

Panics

Only top-level page tables can be activated using this function.

• The page table should be valid by having proper mapping and level.

pub(super) unsafe fn first_activate(&self)

Activates the (root) page table assuming it is the first activation.

It will not try dropping the last activate page table. It is the same with Self::activate() in other senses.

• This function should be called only once per system.

• The page table, from the perspective of mapping and level, should be valid.

Trait Implementations

impl<M: AnyFrameMeta + ?Sized> Clone for Frame<M>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M: AnyFrameMeta + ?Sized> Debug for Frame<M>

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

Formats the value using the given formatter.

impl<M: AnyFrameMeta + ?Sized> Drop for Frame<M>

fn drop(&mut self)

Executes the destructor for this type.

impl<M: AnyFrameMeta> From<Frame<M>> for Frame<dyn AnyFrameMeta>

fn from(frame: Frame<M>) -> Self

Converts to this type from the input type.

impl<M: AnyUFrameMeta> From<Frame<M>> for UFrame

fn from(frame: Frame<M>) -> Self

Converts to this type from the input type.

impl<M: AnyFrameMeta + ?Sized> From<Frame<M>> for Segment<M>

fn from(frame: Frame<M>) -> Self

Converts to this type from the input type.

impl From<Frame<dyn AnyUFrameMeta>> for Frame<dyn AnyFrameMeta>

fn from(frame: UFrame) -> Self

Converts to this type from the input type.

impl<M: AnyFrameMeta + ?Sized> From<UniqueFrame<M>> for Frame<M>

fn from(unique: UniqueFrame<M>) -> Self

Converts to this type from the input type.

impl<M: AnyFrameMeta + ?Sized> NonNullPtr for Frame<M>

const ALIGN_BITS: u32 = 3u32

The power of two of the pointer alignment.

type Target = PhantomData<Frame<M>>

The target type that this pointer refers to.

type Ref<'a> = FrameRef<'a, M> where Self: 'a

A type that behaves just like a shared reference to the NonNullPtr.

fn into_raw(self) -> NonNull<Self::Target>

Converts to a raw pointer.

unsafe fn from_raw(raw: NonNull<Self::Target>) -> Self

Converts back from a raw pointer.

unsafe fn raw_as_ref<'a>(raw: NonNull<Self::Target>) -> Self::Ref<'a>

Obtains a shared reference to the original pointer.

fn ref_as_raw(ptr_ref: Self::Ref<'_>) -> NonNull<Self::Target>

Converts a shared reference to a raw pointer.

impl<M: AnyFrameMeta + ?Sized> PartialEq for Frame<M>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<M: AnyFrameMeta + ?Sized> TryFrom<Frame<M>> for UniqueFrame<M>

fn try_from(frame: Frame<M>) -> Result<Self, Self::Error>

Tries to get a unique frame from a shared frame.

If the reference count is not 1, the frame is returned back.

type Error = Frame<M>

The type returned in the event of a conversion error.

impl<M: AnyFrameMeta> TryFrom<Frame<dyn AnyFrameMeta>> for Frame<M>

fn try_from(dyn_frame: Frame<dyn AnyFrameMeta>) -> Result<Self, Self::Error>

Tries converting a Frame<dyn AnyFrameMeta> into the statically-typed Frame.

If the usage of the frame is not the same as the expected usage, it will return the dynamic frame itself as is.

type Error = Frame<dyn AnyFrameMeta>

The type returned in the event of a conversion error.

impl TryFrom<Frame<dyn AnyFrameMeta>> for UFrame

fn try_from(dyn_frame: Frame<dyn AnyFrameMeta>) -> Result<Self, Self::Error>

Tries converting a Frame<dyn AnyFrameMeta> into UFrame.

If the usage of the frame is not the same as the expected usage, it will return the dynamic frame itself as is.

type Error = Frame<dyn AnyFrameMeta>

The type returned in the event of a conversion error.

impl<UM: AnyUFrameMeta + ?Sized> UntypedMem for Frame<UM>

fn reader(&self) -> VmReader<'_, Infallible>

Borrows a reader that can read the untyped memory.

fn writer(&self) -> VmWriter<'_, Infallible>

Borrows a writer that can write the untyped memory.

impl<UM: AnyUFrameMeta + ?Sized> VmIo for Frame<UM>

fn read(&self, offset: usize, writer: &mut VmWriter<'_>) -> Result<()>

Reads requested data at a specified offset into a given VmWriter.

fn write(&self, offset: usize, reader: &mut VmReader<'_>) -> Result<()>

Writes all data from a given VmReader at a specified offset.

fn read_bytes(&self, offset: usize, buf: &mut [u8]) -> Result<()>

Reads a specified number of bytes at a specified offset into a given buffer.

fn read_val<T: Pod>(&self, offset: usize) -> Result<T>

Reads a value of a specified type at a specified offset.

fn read_slice<T: Pod>(&self, offset: usize, slice: &mut [T]) -> Result<()>

Reads a slice of a specified type at a specified offset.

fn write_bytes(&self, offset: usize, buf: &[u8]) -> Result<()>

Writes a specified number of bytes from a given buffer at a specified offset.

fn write_val<T: Pod>(&self, offset: usize, new_val: &T) -> Result<()>

Writes a value of a specified type at a specified offset.

fn write_slice<T: Pod>(&self, offset: usize, slice: &[T]) -> Result<()>

Writes a slice of a specified type at a specified offset.

fn write_vals<'a, T: Pod + 'a, I: Iterator<Item = &'a T>>( &self, offset: usize, iter: I, align: usize, ) -> Result<usize>

Writes a sequence of values given by an iterator (iter) from the specified offset (offset).

impl<M: AnyFrameMeta + ?Sized> Eq for Frame<M>

impl<M: AnyFrameMeta + ?Sized> Send for Frame<M>

impl<M: AnyFrameMeta + ?Sized> Sync for Frame<M>