Struct CapabilityPtr

pub struct CapabilityPtr { /* private fields */ }

A pointer to userspace memory with implied authority.

A CapabilityPtr points to memory a userspace process may be permitted to read, write, or execute. It is sized exactly to a CPU register that can pass values between userspace and the kernel ¹. Operations on the pointer may affect permissions, e.g. offsetting the pointer beyond the bounds of the memory object may invalidate it.

CapabilityPtr should be used to store or pass a value between the kernel and userspace that may represent a valid userspace reference, when one party intends the other to access it.

---

1. Depending on the architecture, the size of a CapabilityPtr may be a word size or larger, e.g., if registers can store metadata such as access permissions. ↩

Implementations

impl CapabilityPtr

pub fn addr(self) -> usize

Returns the address of this pointer. Does not expose provenance.

pub fn as_ptr<T>(&self) -> *const T

Returns the pointer component of a CapabilityPtr but without any of the authority.

pub unsafe fn new_with_authority( ptr: *const (), _base: usize, _length: usize, _perms: CapabilityPtrPermissions, ) -> Self

Construct a CapabilityPtr from a raw pointer, with authority ranging over [base, base + length) and permissions perms.

Provenance note: may derive from a pointer other than the input to provide something with valid provenance to justify the other arguments.

Safety

Constructing a CapabilityPtr with metadata may convey authority to dereference this pointer, such as in userspace. When these pointers serve as the only memory isolation primitive in the system, this method can thus break Tock’s isolation model. As semi-trusted kernel code can name this type and method, it is thus marked as unsafe.

pub fn map_or<U, F>(&self, default: U, f: F) -> U

where F: FnOnce(&Self) -> U,

If the CapabilityPtr is null returns default, otherwise applies f to self.

pub fn map_or_else<U, D, F>(&self, default: D, f: F) -> U

where D: FnOnce() -> U, F: FnOnce(&Self) -> U,

If the CapabilityPtr is null returns default, otherwise applies f to self. default is only evaluated if self is not null.

Trait Implementations

impl AddAssign<usize> for CapabilityPtr

fn add_assign(&mut self, rhs: usize)

Increments the address of a CapabilityPtr. If the pointer is offset past its bounds, its authority may be invalidated.

impl Clone for CapabilityPtr

fn clone(&self) -> CapabilityPtr

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CapabilityPtr

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

Formats the value using the given formatter.

impl Default for CapabilityPtr

fn default() -> Self

Returns a null CapabilityPtr.

impl From<CapabilityPtr> for MachineRegister

fn from(from: CapabilityPtr) -> Self

Creates a MachineRegister containing this CapabilityPtr, including its provenance.

impl From<usize> for CapabilityPtr

fn from(from: usize) -> Self

Constructs a CapabilityPtr with a given address but no authority or provenance.

impl Hash for CapabilityPtr

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for CapabilityPtr

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

Formats the value using the given formatter.

impl Ord for CapabilityPtr

fn cmp(&self, other: &CapabilityPtr) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for CapabilityPtr

fn eq(&self, other: &CapabilityPtr) -> 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 PartialOrd for CapabilityPtr

fn partial_cmp(&self, other: &CapabilityPtr) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl UpperHex for CapabilityPtr

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

Formats the value using the given formatter.

impl Copy for CapabilityPtr

impl Eq for CapabilityPtr

impl StructuralPartialEq for CapabilityPtr