Helper class for accessing capability properties on pointers. More...

#include <cheri.hh>

Public Types
using	PointerType

Public Member Functions
constexpr	Capability (std::nullptr_t)
	Constructor from a null pointer.
constexpr	Capability ()
	Default constructor, initialises with a null pointer.
constexpr	Capability (decltype(ptr) p)
	Constructor, takes an existing pointer to wrap.
constexpr	Capability (const Capability &other)=default
	Copy constructor, aliases the object that is pointed to by ptr.
Capability &	operator= (const Capability &other)=default
	Replace the pointer that this capability wraps with another.
AddressProxy	address ()
	Access the address of the capability.
ptraddr_t	address () const
	Return the address as an integer from a const capability.
BoundsProxy	bounds ()
	Access (read, set) the capability's bounds.
ptrdiff_t	bounds () const
	Return the bounds as an integer.
PermissionsProxy	permissions ()
	Access the permissions of this capability.
PermissionSet	permissions () const
	Get a copy of the permissions from a const capability.
template<std::same_as< Permission >... Permissions>
void	without_permissions (Permissions... drop)
	Remove some permissions from this capability.
Capability	operator- (ptrdiff_t diff)
	Pointer subtraction.
Capability &	operator-= (ptrdiff_t diff)
	Pointer subtraction.
Capability	operator+ (ptrdiff_t diff)
	Pointer addition.
Capability &	operator+= (ptrdiff_t diff)
	Pointer addition.
bool	is_valid () const
	Returns the tag bit indicating whether this is a valid capability.
bool	is_valid_temporal () const
	Returns the tag bit indicating whether this is a valid capability.
bool	is_sealed () const
	Return whether this is a sealed capability.
uint32_t	type () const
	Returns the type of this capability, 0 if this is not a sealed capability.
ptraddr_t	base () const
	Returns the base address of this capability.
size_t	length () const
	Returns the length of this capability.
ptraddr_t	top () const
	Returns the address of the top of this capability.
constexpr std::partial_ordering	operator<=> (T *other) const
	Capability comparison.
constexpr std::partial_ordering	operator<=> (std::nullptr_t) const
	Comparison against null pointer.
constexpr bool	operator== (const Capability Other) const
constexpr std::partial_ordering	operator<=> (const Capability Other) const
	Capability comparison.
constexpr bool	operator== (std::nullptr_t) const
	Equality operator, wraps the three-way compare operator.
template<typename U = T> requires (!std::same_as<U, void> && !IsSealed)
	operator U* () const
	Implicit cast to the raw pointer type (unsealed version).
template<typename U = T> requires (!std::same_as<U, void> && IsSealed)
	operator CHERI_SEALED (U *)() const
	Implicit cast to the raw pointer type (sealed version).
	operator void * () const
	Implicit cast to a raw pointer type.
T *	operator-> () const
	Access fields of the target as if this were a raw pointer.
T *	get () const
	Explicitly get the raw pointer.
template<typename U = T> requires (!std::same_as<U, void> && !IsSealed)
U &	operator* () const
	Dereference operator.
template<typename U>
Capability< U, IsSealed >	cast () const
	Cast this capability to some other type.
template<typename U>
bool	is_subset_of (Capability< U, IsSealed > other) const
	Returns true if the tags of this and other match and if this conveys no rights that are not present in other.
Capability< T, true >	seal (void *key) const
	Seal this capability with the given key.
Capability< T, false >	unseal (void *key) const
	Unseal this capability with the given key.
template<typename U = T> requires (!std::same_as<U, void>)
U &	operator[] (size_t index) const
	Subscript operator.
bool	is_aligned (size_t align) const
	Returns true if the capability is align-byte aligned, false otherwise.
Capability &	align_down (size_t align)
	Aligns the capability down to the nearest align-byte boundary.
Capability &	align_up (size_t align)
	Aligns the capability up to the nearest align-byte boundary.

Static Public Attributes
static constexpr bool	IsSealed = IsSealedT

Protected Attributes
PointerType	ptr
	The capability that this class wraps.

Friends
class	PropertyProxyBase
	The property proxy base is allowed to directly access the pointer that this class wraps.

Detailed Description

template<typename T, bool IsSealedT = false>
class CHERI::Capability< T, IsSealedT >

Helper class for accessing capability properties on pointers.

Definition at line 481 of file cheri.hh.

Member Typedef Documentation

◆ PointerType

template<typename T, bool IsSealedT = false>

using CHERI::Capability< T, IsSealedT >::PointerType

Initial value:

std::conditional_t<IsSealed, CHERI_SEALED(T *), T *>

Definition at line 485 of file cheri.hh.

Constructor & Destructor Documentation

◆ Capability() [1/3]

template<typename T, bool IsSealedT = false>

CHERI::Capability< T, IsSealedT >::Capability ( std::nullptr_t )

inlineconstexpr

Constructor from a null pointer.

Definition at line 835 of file cheri.hh.

References ptr.

Referenced by align_down(), align_up(), Capability(), cast(), is_subset_of(), operator+(), operator+=(), operator-(), operator-=(), operator<=>(), operator<=>(), operator=(), seal(), and unseal().

◆ Capability() [2/3]

template<typename T, bool IsSealedT = false>

CHERI::Capability< T, IsSealedT >::Capability ( )

inlineconstexpr

Default constructor, initialises with a null pointer.

Definition at line 837 of file cheri.hh.

References ptr.

◆ Capability() [3/3]

template<typename T, bool IsSealedT = false>

CHERI::Capability< T, IsSealedT >::Capability ( decltype(ptr) p )

inlineconstexpr

Constructor, takes an existing pointer to wrap.

Definition at line 839 of file cheri.hh.

References ptr.

Member Function Documentation

◆ address() [1/2]

template<typename T, bool IsSealedT = false>

AddressProxy CHERI::Capability< T, IsSealedT >::address ( )

inline

Access the address of the capability.

Definition at line 851 of file cheri.hh.

Referenced by bounds(), StandardClint::init(), Revocation::BitmapDirect< WordT, TCMBaseAddr >::mark_set_one(), ds::pointer::offset(), and StandardPlic< MaxIntrID, SourceID, Priority >::StandardPlic().

◆ address() [2/2]

template<typename T, bool IsSealedT = false>

ptraddr_t CHERI::Capability< T, IsSealedT >::address ( ) const

inlinenodiscard

Return the address as an integer from a const capability.

Definition at line 859 of file cheri.hh.

References ptr.

◆ align_down()

template<typename T, bool IsSealedT = false>

Capability & CHERI::Capability< T, IsSealedT >::align_down ( size_t align )

inline

Aligns the capability down to the nearest align-byte boundary.

Definition at line 1231 of file cheri.hh.

References Capability(), and ptr.

◆ align_up()

template<typename T, bool IsSealedT = false>

Capability & CHERI::Capability< T, IsSealedT >::align_up ( size_t align )

inline

Aligns the capability up to the nearest align-byte boundary.

Definition at line 1240 of file cheri.hh.

References Capability(), and ptr.

◆ base()

template<typename T, bool IsSealedT = false>

ptraddr_t CHERI::Capability< T, IsSealedT >::base ( ) const

inlinenodiscard

Returns the base address of this capability.

Definition at line 1009 of file cheri.hh.

References ptr.

Referenced by Revocation::BitmapDirect< WordT, TCMBaseAddr >::mark_set_range(), and top().

◆ bounds() [1/2]

template<typename T, bool IsSealedT = false>

BoundsProxy CHERI::Capability< T, IsSealedT >::bounds ( )

inline

Access (read, set) the capability's bounds.

Definition at line 867 of file cheri.hh.

Referenced by CHERI::check_pointer(), StandardClint::init(), and StandardPlic< MaxIntrID, SourceID, Priority >::StandardPlic().

◆ bounds() [2/2]

template<typename T, bool IsSealedT = false>

ptrdiff_t CHERI::Capability< T, IsSealedT >::bounds ( ) const

inlinenodiscard

Return the bounds as an integer.

Definition at line 875 of file cheri.hh.

References address(), and top().

◆ cast()

template<typename T, bool IsSealedT = false>

template<typename U>

Capability< U, IsSealed > CHERI::Capability< T, IsSealedT >::cast ( ) const

inlinenodiscard

Cast this capability to some other type.

Definition at line 1164 of file cheri.hh.

References Capability(), and ptr.

◆ get()

template<typename T, bool IsSealedT = false>

T * CHERI::Capability< T, IsSealedT >::get ( ) const

inlinenodiscard

Explicitly get the raw pointer.

Definition at line 1144 of file cheri.hh.

References ptr.

Referenced by CHERI::check_pointer().

◆ is_aligned()

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::is_aligned ( size_t align ) const

inlinenodiscard

Returns true if the capability is align-byte aligned, false otherwise.

Definition at line 1223 of file cheri.hh.

References ptr.

◆ is_sealed()

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::is_sealed ( ) const

inlinenodiscard

Return whether this is a sealed capability.

Definition at line 992 of file cheri.hh.

References ptr.

Referenced by operator<=>().

◆ is_subset_of()

template<typename T, bool IsSealedT = false>

template<typename U>

bool CHERI::Capability< T, IsSealedT >::is_subset_of ( Capability< U, IsSealed > other ) const

inlinenodiscard

Returns true if the tags of this and other match and if this conveys no rights that are not present in other.

Returns false in all other cases.

Definition at line 1177 of file cheri.hh.

References Capability(), and ptr.

◆ is_valid()

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::is_valid ( ) const

inlinenodiscard

Returns the tag bit indicating whether this is a valid capability.

This returns a value subject to Common Subexpression Elimination (CSE): multiple calls to is_valid on the same capability may be optimized by the compiler into a single call. This may lead to stale results if the tag bit was cleared between the calls. See is_valid_temporal for a non-CSEable alternative.

Definition at line 955 of file cheri.hh.

References ptr.

◆ is_valid_temporal()

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::is_valid_temporal ( ) const

inlinenodiscard

Returns the tag bit indicating whether this is a valid capability.

This variant of is_valid is not subject to CSE.

Definition at line 975 of file cheri.hh.

References ptr.

◆ length()

template<typename T, bool IsSealedT = false>

size_t CHERI::Capability< T, IsSealedT >::length ( ) const

inlinenodiscard

Returns the length of this capability.

Definition at line 1017 of file cheri.hh.

References ptr.

Referenced by top().

◆ operator CHERI_SEALED()

template<typename T, bool IsSealedT = false>

template<typename U = T>
requires (!std::same_as<U, void> && IsSealed)

CHERI::Capability< T, IsSealedT >::operator CHERI_SEALED ( U * ) const

inline

Implicit cast to the raw pointer type (sealed version).

Definition at line 1120 of file cheri.hh.

References ptr.

◆ operator U*()

template<typename T, bool IsSealedT = false>

template<typename U = T>
requires (!std::same_as<U, void> && !IsSealed)

CHERI::Capability< T, IsSealedT >::operator U* ( ) const

inline

Implicit cast to the raw pointer type (unsealed version).

Definition at line 1110 of file cheri.hh.

References ptr.

◆ operator void *()

template<typename T, bool IsSealedT = false>

CHERI::Capability< T, IsSealedT >::operator void * ( ) const

inline

Implicit cast to a raw pointer type.

Definition at line 1128 of file cheri.hh.

References ptr.

◆ operator*()

template<typename T, bool IsSealedT = false>

template<typename U = T>
requires (!std::same_as<U, void> && !IsSealed)

U & CHERI::Capability< T, IsSealedT >::operator* ( ) const

inline

Dereference operator.

Definition at line 1155 of file cheri.hh.

References ptr.

◆ operator+()

template<typename T, bool IsSealedT = false>

Capability CHERI::Capability< T, IsSealedT >::operator+ ( ptrdiff_t diff )

inline

Pointer addition.

Definition at line 930 of file cheri.hh.

References Capability(), and ptr.

◆ operator+=()

template<typename T, bool IsSealedT = false>

Capability & CHERI::Capability< T, IsSealedT >::operator+= ( ptrdiff_t diff )

inline

Pointer addition.

Definition at line 938 of file cheri.hh.

References Capability(), and ptr.

◆ operator-()

template<typename T, bool IsSealedT = false>

Capability CHERI::Capability< T, IsSealedT >::operator- ( ptrdiff_t diff )

inline

Pointer subtraction.

Definition at line 913 of file cheri.hh.

References Capability(), and ptr.

◆ operator-=()

template<typename T, bool IsSealedT = false>

Capability & CHERI::Capability< T, IsSealedT >::operator-= ( ptrdiff_t diff )

inline

Pointer subtraction.

Definition at line 921 of file cheri.hh.

References Capability(), and ptr.

◆ operator->()

template<typename T, bool IsSealedT = false>

T * CHERI::Capability< T, IsSealedT >::operator-> ( ) const

inline

Access fields of the target as if this were a raw pointer.

Definition at line 1136 of file cheri.hh.

References ptr.

◆ operator<=>() [1/3]

template<typename T, bool IsSealedT = false>

std::partial_ordering CHERI::Capability< T, IsSealedT >::operator<=> ( const Capability< T, IsSealedT > Other ) const

inlineconstexpr

Capability comparison.

Defines ordered comparison for capabilities with the same bounds and permissions. All other capabilities are either equivalent (identical bit pattern, including the tag bit) or unordered.

Callers may want to compare addresses, rather than capabilities, if they want a defined comparison that is stable between two objects.

Definition at line 1075 of file cheri.hh.

References Capability(), is_sealed(), and ptr.

◆ operator<=>() [2/3]

template<typename T, bool IsSealedT = false>

std::partial_ordering CHERI::Capability< T, IsSealedT >::operator<=> ( std::nullptr_t ) const

inlineconstexpr

Comparison against null pointer.

Returns equivalent if this is a canonical null pointer, returns unordered for any other (tagged or untagged) value. Callers may often want is_valid instead of this.

Definition at line 1052 of file cheri.hh.

References ptr.

◆ operator<=>() [3/3]

template<typename T, bool IsSealedT = false>

std::partial_ordering CHERI::Capability< T, IsSealedT >::operator<=> ( T * other ) const

inlineconstexpr

Capability comparison.

Defines ordered comparison for capabilities with the same bounds and permissions. All other capabilities are either equivalent (identical bit pattern, including the tag bit) or unordered.

Definition at line 1040 of file cheri.hh.

References Capability().

◆ operator==() [1/2]

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::operator== ( const Capability< T, IsSealedT > Other ) const

inlineconstexpr

Definition at line 1061 of file cheri.hh.

◆ operator==() [2/2]

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::operator== ( std::nullptr_t ) const

inlineconstexpr

Equality operator, wraps the three-way compare operator.

Definition at line 1100 of file cheri.hh.

◆ operator[]()

template<typename T, bool IsSealedT = false>

template<typename U = T>
requires (!std::same_as<U, void>)

U & CHERI::Capability< T, IsSealedT >::operator[] ( size_t index ) const

inline

Subscript operator.

Definition at line 1214 of file cheri.hh.

References ptr.

◆ permissions() [1/2]

template<typename T, bool IsSealedT = false>

PermissionsProxy CHERI::Capability< T, IsSealedT >::permissions ( )

inline

Access the permissions of this capability.

Definition at line 883 of file cheri.hh.

Referenced by CHERI::check_pointer(), and without_permissions().

◆ permissions() [2/2]

template<typename T, bool IsSealedT = false>

PermissionSet CHERI::Capability< T, IsSealedT >::permissions ( ) const

inlinenodiscard

Get a copy of the permissions from a const capability.

Definition at line 891 of file cheri.hh.

References ptr.

◆ seal()

template<typename T, bool IsSealedT = false>

Capability< T, true > CHERI::Capability< T, IsSealedT >::seal ( void * key ) const

inlinenodiscard

Seal this capability with the given key.

Definition at line 1185 of file cheri.hh.

References Capability(), and ptr.

◆ top()

template<typename T, bool IsSealedT = false>

ptraddr_t CHERI::Capability< T, IsSealedT >::top ( ) const

inlinenodiscard

Returns the address of the top of this capability.

Definition at line 1025 of file cheri.hh.

References base(), length(), and ptr.

Referenced by bounds(), Revocation::BitmapDirect< WordT, TCMBaseAddr >::mark_set_range(), and anonymous_namespace{debug.hh}::StackUsageCheck< Mode, Expected, Fn >::~StackUsageCheck().

◆ type()

template<typename T, bool IsSealedT = false>

uint32_t CHERI::Capability< T, IsSealedT >::type ( ) const

inlinenodiscard

Returns the type of this capability, 0 if this is not a sealed capability.

Definition at line 1001 of file cheri.hh.

References ptr.

◆ unseal()

template<typename T, bool IsSealedT = false>

Capability< T, false > CHERI::Capability< T, IsSealedT >::unseal ( void * key ) const

inlinenodiscard

Unseal this capability with the given key.

Definition at line 1195 of file cheri.hh.

References Capability(), and ptr.

◆ without_permissions()

template<typename T, bool IsSealedT = false>

template<std::same_as< Permission >... Permissions>

void CHERI::Capability< T, IsSealedT >::without_permissions ( Permissions... drop )

inline

Remove some permissions from this capability.

Because this function computes the permission mask by clearing bits in the PermissionSet::omnipotent() all-ones mask, rather than from the set of permissions currently held by this Capability, it is safe to use to clear Global permission on a sealed capability.

Definition at line 905 of file cheri.hh.

References CHERI::PermissionSet::omnipotent(), permissions(), and CHERI::PermissionSet::without().

◆ PropertyProxyBase

template<typename T, bool IsSealedT = false>

friend class PropertyProxyBase

friend

The property proxy base is allowed to directly access the pointer that this class wraps.

Definition at line 831 of file cheri.hh.

Member Data Documentation

◆ IsSealed

template<typename T, bool IsSealedT = false>

bool CHERI::Capability< T, IsSealedT >::IsSealed = IsSealedT

staticconstexpr

Definition at line 484 of file cheri.hh.

◆ ptr

template<typename T, bool IsSealedT = false>

PointerType CHERI::Capability< T, IsSealedT >::ptr

protected

The capability that this class wraps.

Definition at line 490 of file cheri.hh.

Referenced by address(), align_down(), align_up(), base(), Capability(), Capability(), Capability(), cast(), get(), is_aligned(), is_sealed(), is_subset_of(), is_valid(), is_valid_temporal(), length(), operator CHERI_SEALED(), operator U*(), operator void *(), operator*(), operator+(), operator+=(), operator-(), operator-=(), operator->(), operator<=>(), operator<=>(), operator[](), permissions(), seal(), top(), type(), and unseal().

The documentation for this class was generated from the following file:

sdk/include/cheri.hh

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ PointerType

Constructor & Destructor Documentation

◆ Capability() [1/3]

◆ Capability() [2/3]

◆ Capability() [3/3]

Member Function Documentation

◆ address() [1/2]

◆ address() [2/2]

◆ align_down()

◆ align_up()

◆ base()

◆ bounds() [1/2]

◆ bounds() [2/2]

◆ cast()

◆ get()

◆ is_aligned()

◆ is_sealed()

◆ is_subset_of()

◆ is_valid()

◆ is_valid_temporal()

◆ length()

◆ operator CHERI_SEALED()

◆ operator U*()

◆ operator void *()

◆ operator*()

◆ operator+()

◆ operator+=()

◆ operator-()

◆ operator-=()

◆ operator->()

◆ operator<=>() [1/3]

◆ operator<=>() [2/3]

◆ operator<=>() [3/3]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator[]()

◆ permissions() [1/2]

◆ permissions() [2/2]

◆ seal()

◆ top()

◆ type()

◆ unseal()

◆ without_permissions()

Friends And Related Symbol Documentation

◆ PropertyProxyBase

Member Data Documentation

◆ IsSealed

◆ ptr