Struct MetaSlot

#[repr(C)]
pub(in mm) struct MetaSlot {
    storage: UnsafeCell<[u8; 40]>,
    pub(super) ref_count: AtomicU64,
    pub(super) vtable_ptr: UnsafeCell<MaybeUninit<DynMetadata<dyn AnyFrameMeta>>>,
    pub(super) in_list: AtomicU64,
}

Fields

storage: UnsafeCell<[u8; 40]>

The metadata of a frame.

It is placed at the beginning of a slot because:

• the implementation can simply cast a *const MetaSlot to a *const AnyFrameMeta for manipulation;
• if the metadata need special alignment, we can provide at most PAGE_METADATA_ALIGN bytes of alignment;
• the subsequent fields can utilize the padding of the reference count to save space.

Don’t interpret this field as an array of bytes. It is a placeholder for the metadata of a frame.

ref_count: AtomicU64

The reference count of the page.

Specifically, the reference count has the following meaning:

• REF_COUNT_UNUSED: The page is not in use.
• REF_COUNT_UNIQUE: The page is owned by a UniqueFrame.
• 0: The page is being constructed (Frame::from_unused) or destructured (drop_last_in_place).
• 1..REF_COUNT_MAX: The page is in use.
• REF_COUNT_MAX..REF_COUNT_UNIQUE: Illegal values to prevent the reference count from overflowing. Otherwise, overflowing the reference count will cause soundness issue.

vtable_ptr: UnsafeCell<MaybeUninit<DynMetadata<dyn AnyFrameMeta>>>

The virtual table that indicates the type of the metadata.

in_list: AtomicU64

This is only accessed by crate::mm::frame::linked_list. It stores 0 if the frame is not in any list, otherwise it stores the ID of the list.

It is ugly but allows us to tell if a frame is in a specific list by one relaxed read. Otherwise, if we store it conditionally in storage we would have to ensure that the type is correct before the read, which costs a synchronization.

Implementations

impl MetaSlot

pub(super) fn get_from_unused<M: AnyFrameMeta>( paddr: Paddr, metadata: M, as_unique_ptr: bool, ) -> Result<*const Self, GetFrameError>

Initializes the metadata slot of a frame assuming it is unused.

If successful, the function returns a pointer to the metadata slot. And the slot is initialized with the given metadata.

The resulting reference count held by the returned pointer is REF_COUNT_UNIQUE if as_unique_ptr is true, otherwise 1.

pub(super) fn get_from_in_use( paddr: Paddr, ) -> Result<*const Self, GetFrameError>

Gets another owning pointer to the metadata slot from the given page.

pub(super) unsafe fn inc_ref_count(&self)

Increases the frame reference count by one. For a frame derived from Self

• The caller must have already held a reference to the frame.

pub(super) fn frame_paddr(&self) -> Paddr

Gets the corresponding frame’s physical address.

pub(super) unsafe fn dyn_meta_ptr(&self) -> *mut dyn AnyFrameMeta

Gets a dynamically typed pointer to the stored metadata.

• The stored metadata should be validly derived from Self :: write_meta.

• mutating through the returned pointer should have exclusive mutable access to The metadata slot.

pub(super) fn as_meta_ptr<M: AnyFrameMeta>(&self) -> *mut M

Gets the stored metadata as type M.

Calling the method should be safe, but using the returned pointer would be unsafe. Specifically, the derefernecer should ensure that:

• the stored metadata is initialized (by Self::write_meta) and valid;
• the initialized metadata is of type M;
• the returned pointer should not be dereferenced as mutable unless having exclusive access to the metadata slot.

pub(super) unsafe fn write_meta<M: AnyFrameMeta>(&self, metadata: M)

Writes the metadata to the slot without reading or dropping the previous value.

• should have exclusive mutable access to self.vtable_ptr.

• should have exclusive mutable access to self.storage.

pub(super) unsafe fn drop_last_in_place(&self)

Drops the metadata and deallocates the frame.

• self.ref_count should equal to 0.

• the meta data should be validly derived from Self :: write_meta.

pub(super) unsafe fn drop_meta_in_place(&self)

Drops the metadata of a slot in place.

After this operation, the metadata becomes uninitialized. Any access to the metadata is undefined behavior unless it is re-initialized by Self::write_meta.

• self.ref_count should equal to 0.

• the meta data should be validly derived from Self :: write_meta.