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. Because it is register sized, CapabilityPtr is guaranteed to be at least the size of a word (usize) ¹. Operations on the pointer may affect permissions, e.g. offsetting the pointer beyond the bounds of the memory object invalidates it. Like a *const (), a CapabilityPtr may also “hide” information by storing a word of data with no memory access permissions.

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 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

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 the “default value” for a type.

impl From<CapabilityPtr> for usize

fn from(from: CapabilityPtr) -> Self

Returns the address of the CapabilityPtr. Provenance note: may not expose provenance.

impl From<usize> for CapabilityPtr

fn from(from: usize) -> Self

Constructs a CapabilityPtr with a given address and no authority

Provenance note: may have null 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

Format the capability as a lowercase hex string. Will print at least the address, and any platform specific metadata if it exists.

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

Format the capability as an uppercase hex string. Will print at least the address, and any platform specific metadata if it exists.

impl Copy for CapabilityPtr

impl Eq for CapabilityPtr

impl StructuralPartialEq for CapabilityPtr