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.

CapabilityPtrs can be the sole memory isolation primitive in the system, thus great care must be taken with this method, as errors can break Tock’s isolation model.

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

Safety

NOTE: Hardware capability support is experimental in Tock. The intent of this type is to capture semantics general to any hardware capability implementation, however, there is no upstream support for any such hardware today. As such, the exact safety conditions may change in the future.

Callers are responsible for ensuring that the authority conveyed by this pointer does not violate Tock’s isolation model, under an assumption that hardware capabilities are the sole memory isolation mechanism.

Authority is conveyed solely by the base, length, and perms. The value in ptr may be freely changed by untrusted code. When executing on a platform with hardware capability enforcement, callers may assume that on any attempt to use ptr, hardware will verify that:

• ptr is within the bounds [base, base + length).
• The access type is allowed by perms.

Callers are responsible for restricting access to this pointer, i.e., ensuring that a pointer which allows access to process memory is only given to the correct process.

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 duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for CapabilityPtr

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

Equality operator ==.

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

Inequality operator !=.

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 StructuralPartialEq for CapabilityPtr

impl UpperHex for CapabilityPtr

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

Formats the value using the given formatter.