[−][src]Trait x86_64::structures::paging::mapper::Mapper

pub trait Mapper<S: PageSize> {
    unsafe fn map_to<A>(
        &mut self, 
        page: Page<S>, 
        frame: PhysFrame<S>, 
        flags: PageTableFlags, 
        frame_allocator: &mut A
    ) -> Result<MapperFlush<S>, MapToError<S>>
    where
        Self: Sized,
        A: FrameAllocator<Size4KiB>;

    fn unmap(
        &mut self, 
        page: Page<S>
    ) -> Result<(PhysFrame<S>, MapperFlush<S>), UnmapError>;

    unsafe fn update_flags(
        &mut self, 
        page: Page<S>, 
        flags: PageTableFlags
    ) -> Result<MapperFlush<S>, FlagUpdateError>;

    fn translate_page(
        &self, 
        page: Page<S>
    ) -> Result<PhysFrame<S>, TranslateError>;

    unsafe fn identity_map<A>(
        &mut self, 
        frame: PhysFrame<S>, 
        flags: PageTableFlags, 
        frame_allocator: &mut A
    ) -> Result<MapperFlush<S>, MapToError<S>>
    where
        Self: Sized,
        A: FrameAllocator<Size4KiB>,
        S: PageSize,
        Self: Mapper<S>,
    { ... }
}

A trait for common page table operations on pages of size S.

Required methods

unsafe fn map_to<A>(
    &mut self,
    page: Page<S>,
    frame: PhysFrame<S>,
    flags: PageTableFlags,
    frame_allocator: &mut A
) -> Result<MapperFlush<S>, MapToError<S>> where
    Self: Sized,
    A: FrameAllocator<Size4KiB>, 

Creates a new mapping in the page table.

This function might need additional physical frames to create new page tables. These frames are allocated from the allocator argument. At most three frames are required.

Safety

Creating page table mappings is a fundamentally unsafe operation because there are various ways to break memory safety through it. For example, re-mapping an in-use page to a different frame changes and invalidates all values stored in that page, resulting in undefined behavior on the next use.

The caller must ensure that no undefined behavior or memory safety violations can occur through the new mapping. Among other things, the caller must prevent the following:

  • Aliasing of &mut references, i.e. two &mut references that point to the same physical address. This is undefined behavior in Rust.
    • This can be ensured by mapping each page to an individual physical frame that is not mapped anywhere else.
  • Creating uninitalized or invalid values: Rust requires that all values have a correct memory layout. For example, a bool must be either a 0 or a 1 in memory, but not a 3 or 4. An exception is the MaybeUninit wrapper type, which abstracts over possibly uninitialized memory.
    • This is only a problem when re-mapping pages to different physical frames. Mapping a page that is not in use yet is fine.

Special care must be taken when sharing pages with other address spaces, e.g. by setting the GLOBAL flag. For example, a global mapping must be the same in all address spaces, otherwise undefined behavior can occur because of TLB races. It's worth noting that all the above requirements also apply to shared mappings, including the aliasing requirements.

fn unmap(
    &mut self,
    page: Page<S>
) -> Result<(PhysFrame<S>, MapperFlush<S>), UnmapError>

Removes a mapping from the page table and returns the frame that used to be mapped.

Note that no page tables or pages are deallocated.

unsafe fn update_flags(
    &mut self,
    page: Page<S>,
    flags: PageTableFlags
) -> Result<MapperFlush<S>, FlagUpdateError>

Updates the flags of an existing mapping.

Safety

This method is unsafe because changing the flags of a mapping might result in undefined behavior. For example, setting the GLOBAL and MUTABLE flags for a page might result in the corruption of values stored in that page from processes running in other address spaces.

fn translate_page(&self, page: Page<S>) -> Result<PhysFrame<S>, TranslateError>

Return the frame that the specified page is mapped to.

This function assumes that the page is mapped to a frame of size S and returns an error otherwise.

Loading content...

Provided methods

unsafe fn identity_map<A>(
    &mut self,
    frame: PhysFrame<S>,
    flags: PageTableFlags,
    frame_allocator: &mut A
) -> Result<MapperFlush<S>, MapToError<S>> where
    Self: Sized,
    A: FrameAllocator<Size4KiB>,
    S: PageSize,
    Self: Mapper<S>, 

Maps the given frame to the virtual page with the same address.

Safety

This is a convencience function that invokes [map_to] internally, so all safety requirements of it also apply for this function.

Loading content...

Implementors

impl<'a> Mapper<Size1GiB> for OffsetPageTable<'a>[src]

impl<'a> Mapper<Size1GiB> for RecursivePageTable<'a>[src]

impl<'a> Mapper<Size2MiB> for OffsetPageTable<'a>[src]

impl<'a> Mapper<Size2MiB> for RecursivePageTable<'a>[src]

impl<'a> Mapper<Size4KiB> for OffsetPageTable<'a>[src]

impl<'a> Mapper<Size4KiB> for RecursivePageTable<'a>[src]

impl<'a, P: PhysToVirt> Mapper<Size1GiB> for MappedPageTable<'a, P>[src]

impl<'a, P: PhysToVirt> Mapper<Size2MiB> for MappedPageTable<'a, P>[src]

impl<'a, P: PhysToVirt> Mapper<Size4KiB> for MappedPageTable<'a, P>[src]

Loading content...