Struct sunrise_kernel::frame_allocator::physical_mem_region::PhysicalMemRegion

pub struct PhysicalMemRegion {
    pub(super) frames: usize,
    pub(super) start_addr: usize,
    pub(super) should_free_on_drop: bool,
}

A span of adjacent physical frames. A frame is PAGE_SIZE.

PhysicalMemRegions are allocated by the FrameAllocator. Dropping a PhysicalMemRegion frees it.

Fields

frames: usize

The number of frames in this region.

start_addr: usize

The (physical) address of the start of this region.

should_free_on_drop: bool

Denotes if the frames held in this region should be freed when the whole region is freed. The default have this set to true.

We provide (unsafe) methods for duplicating PhysicalMemRegions, to ease working with them, but the duplicated region must not also free the frames when dropped, as this would cause a double-free.

Implementations

impl PhysicalMemRegion

pub fn address(&self) -> PhysicalAddress

Get the start address of this PhysicalMemRegion.

The address of a PhysicalMemRegion is guaranteed to be page size aligned.

pub fn size(&self) -> usize

Get the size this PhysicalMemRegion spans.

The size of a PhysicalMemRegion is guaranteed to be page size aligned, and non-zero.

pub unsafe fn on_fixed_mmio(
    address: PhysicalAddress,
    length: usize
) -> Result<Self, KernelError>

Constructs a PhysicalMemRegion by circumventing the FrameAllocator. Used for accessing fixed mmio regions, as they should have been marked reserved in the FrameAllocator and will never be returned by it.

On drop the region won't be given back to the FrameAllocator, and thous stay marked as reserved.

Error

• InvalidAddress:
  • address is not PAGE_SIZE aligned.
  • One or more of the frames in this span wasn't marked as reserved in the FrameAllocator, as it could had mistakenly given it as regular RAM.
• InvalidLength:
  • length is not PAGE_SIZE aligned.
  • length is zero.

Safety

pub unsafe fn new_unchecked(physical_addr: PhysicalAddress, len: usize) -> Self

Construct a PhysicalMemRegion by circumventing the FrameAllocator.

Panic

• Panics when the address is not framesize-aligned
• Panics when the len is not framesize-aligned

Safety

This function can be used to allocate the same frame twice, which would cause undefined behavior if written to without additional synchronization.

pub unsafe fn reconstruct(physical_addr: PhysicalAddress, len: usize) -> Self

Constructs a PhysicalMemRegion from a physical address, and a len. Region will be given back to the FrameAllocator on drop.

Unsafe

This function by-passes the FrameAllocator, and should only be used for frames that have been deconstructed and put in the Page Tables, and that are lacking any other form of tracking. This is the case for kernel pages.

This function cannot make any guaranty that the frame can be written to, or even exists at all.

Panic

• Panics if any of the frames in this span wasn't marked as allocated in the frame allocator.
• Panics when the address is not framesize-aligned
• Panics when the len is not framesize-aligned

Safety

This function should only be called to recreate a PhysicalMemRegion that was previously created by FrameAlloc::allocate_region, and mem::forget'd.

pub unsafe fn reconstruct_no_dealloc(
    physical_addr: PhysicalAddress,
    len: usize
) -> Self

Constructs a PhysicalMemRegion from a physical address, and a len. Region won't be given back to the FrameAllocator on drop.

Safety

This function by-passes the FrameAllocator, and should only be used for frames that have been deconstructed and put in the Page Tables, and that are lacking any other form of tracking. This is the case for kernel pages.

This function cannot make any guaranty that the frame can be written to, or even exists at all.

Panic

• Panics if any of the frames in this span wasn't marked as allocated in the frame allocator.
• Panics when the address is not framesize-aligned
• Panics when the len is not framesize-aligned

Trait Implementations

impl Debug for PhysicalMemRegion

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

Formats the value using the given formatter.

impl Drop for PhysicalMemRegion

fn drop(&mut self)

Dropping a PhysicalMemRegion may free its frames.

impl<'a> IntoIterator for &'a PhysicalMemRegion

type Item = PhysicalAddress

The type of the elements being iterated over.

type IntoIter = PhysicalMemRegionIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Splittable for PhysicalMemRegion

fn split_at(&mut self, offset: usize) -> Result<Option<Self>, KernelError>

Splits the given PhysicalMemRegion in two parts, at the given offset.

Errors

• InvalidSize: offset is not PAGE_SIZE aligned.

fn right_split(&mut self, offset: usize) -> Result<Option<Self>, KernelError>

Splits the given object in two at the given offset.