Struct Mapping 

pub struct Mapping<R: Mappable, A: Ty> { /* private fields */ }

Available on crate feature full only.

An owned memory mapping.

This will allocate any required memory when created, and register any lazily mapped memory as such. It will also manage the page tables to correctly unmap the memory when dropped, and deallocate any memory previously allocated.

See the module level documentation for more information.

Implementations

impl<R: Mappable> Mapping<R, Kernel>

pub fn as_mut_ptr_range(&mut self) -> Range<*mut u8>

Returns the two unsafe mutable pointers that span the range of the mapping.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

pub fn as_ptr_range(&self) -> Range<*const u8>

Returns the two unsafe pointers that span the range of the mapping.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

pub fn as_mut_ptr(&mut self) -> *mut u8

Returns an unsafe mutable to the beginning of the mapping.

pub fn as_ptr(&self) -> *const u8

Returns an unsafe pointer to the beginning of the mapping.

pub unsafe fn from_raw_parts<const RAM: bool, T>( frames: Frames<RAM, T>, base_page: RawPage, protection: Protection, caching: Caching, ) -> Self

where R: Default,

Creates a Mapping directly from its raw components.

Safety

A section of virtual memory starting at base_page must be allocation by the kernel global virtual allocator. This section must be equal in length to R::virtual_size(frames.count()). The section of virtual memory from base_page + R::base_virtual_offset() must be contiguously mapped to the physical memory owned by frames, with the cache and protection attributes given in caching and protection.

These requirements are always upheld by the return values of [into_raw_parts]. Other mapping sources are allowed if all the invariants are upheld.

pub fn into_raw_parts( self, ) -> (Option<Frames<false>>, RawPage, Protection, Caching)

Decomposes a Mapping into its raw components.

impl<R: Mappable> Mapping<R, Userspace>

pub fn as_mut_ptr_range(&mut self) -> Range<User<'_, *mut u8>>

Available on non-crate feature use_std only.

Returns the two mutable user pointers that span the range of the mapping.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

pub fn as_ptr_range(&self) -> Range<User<'_, *const u8>>

Available on non-crate feature use_std only.

Returns the two user pointers that span the range of the mapping.

The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.

pub fn as_mut_ptr(&mut self) -> User<'_, *mut u8>

Available on non-crate feature use_std only.

Returns a mutable user pointer to the beginning of the mapping.

pub fn as_ptr(&self) -> User<'_, *const u8>

Available on non-crate feature use_std only.

Returns a user pointer to the beginning of the mapping.

impl<R: Mappable, A: Ty> Mapping<R, A>

pub fn grow_in_place_by( &mut self, extra_length: usize, ) -> Result<(), AllocError>

Add extra_length pages to the end of the existing mapping.

The mapping is grown in place, such that any addresses pointing within the existing mapping remain valid.

The underlying physical memory may no longer be contiguous after this operation.

Errors

Returns an AllocError describing the allocation that failed.

Examples

use kernel_api::mapping::{Config, Ty, Mmap};
use kernel_api::memory::PAGE_SIZE;
use core::num::NonZero;

let mut mapping = Config::new(NonZero::new(1).unwrap(), Ty::KERNEL_OTHER)
                      .map::<Mmap>()?;
assert_eq!(mapping.page_len(), 1);

mapping.grow_in_place_by(1)?;
assert_eq!(mapping.page_len(), 2);

pub fn byte_len(&self) -> usize

The valid length of this mapping in bytes.

Examples

use kernel_api::mapping::{Config, Ty, Mmap};
use kernel_api::memory::PAGE_SIZE;
use core::num::NonZero;

let mapping = Config::new(NonZero::new(1).unwrap(), Ty::KERNEL_OTHER)
                  .map::<Mmap>()?;
assert_eq!(mapping.byte_len(), 1 * PAGE_SIZE);

pub fn page_len(&self) -> usize

The valid length of this mapping in pages.

Examples

use kernel_api::mapping::{Config, Ty, Mmap};
use core::num::NonZero;

let mapping = Config::new(NonZero::new(1).unwrap(), Ty::KERNEL_OTHER)
                  .map::<Mmap>()?;
assert_eq!(mapping.page_len(), 1);

pub fn physical_start(&self) -> Option<RawFrame>

Returns the RawFrame that this mapping is mapped to.

This only makes sense for a physically contiguous mapping, and will return None in other situations.

Examples

use kernel_api::mapping::{Config, Ty, Mmap};
use core::num::NonZero;

let mapping = Config::new(NonZero::new(1).unwrap(), Ty::KERNEL_OTHER)
                  .map::<Mmap>()?;
assert!(mapping.physical_start().is_some());

use kernel_api::mapping::{Config, Ty, Mmap};
use core::num::NonZero;

let mapping = Config::new(NonZero::new(1).unwrap(), Ty::KERNEL_OTHER)
                  .with_vmo(get_vmo(), 0)
                  .map::<Mmap>()?;
assert!(mapping.physical_start().is_none());

pub fn virtual_valid_start(&self) -> RawPage

The first page in the mapping that is mapped to physical memory. The region of virtual memory from virtual_valid_start() to virtual_valid_start() + physical_length is mapped.

pub fn set_writable(&mut self, writable: bool)

Trait Implementations

impl<R: Mappable, A: Ty> Debug for Mapping<R, A>

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

Formats the value using the given formatter.

impl<R: Mappable, A: Ty> Drop for Mapping<R, A>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.