cheri.h File Reference

C definitions for CHERI specific functionality. More...

#include <__cheri_sealed.h>
#include <compartment-macros.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Enumerations
enum	CHERIPermission {   CheriPermissionGlobal = 0 , CheriPermissionLoadGlobal = 1 , CheriPermissionStore = 2 , CheriPermissionLoadMutable = 3 ,   CheriPermissionStoreLocal = 4 , CheriPermissionLoad = 5 , CheriPermissionLoadStoreCapability = 6 , CheriPermissionAccessSystemRegisters = 7 ,   CheriPermissionExecute = 8 , CheriPermissionUnseal = 9 , CheriPermissionSeal = 10 , CheriPermissionUser0 = 11 }
	The complete set of architectural permissions. More...
enum	CHERICauseCode {   CheriCauseCodeNone = 0 , CheriCauseCodeBoundsViolation = 1 , CheriCauseCodeTagViolation = 2 , CheriCauseCodeSealViolation = 3 ,   CheriCauseCodePermitExecuteViolation = 0x11 , CheriCauseCodePermitLoadViolation = 0x12 , CheriCauseCodePermitStoreViolation = 0x13 , CheriCauseCodePermitStoreCapabilityViolation = 0x15 ,   CheriCauseCodePermitStoreLocalCapabilityViolation = 0x16 , CheriCauseCodePermitAccessSystemRegistersViolation = 0x18 , CheriCauseCodeInvalid = -1 }
	The codes used in the cause field of the mtval CSR when the processor takes a CHERI exception. More...
enum	CHERIRegisterNumber {   CheriRegisterNumberCzr = 0x0 , CheriRegisterNumberCra = 0x1 , CheriRegisterNumberCsp = 0x2 , CheriRegisterNumberCgp = 0x3 ,   CheriRegisterNumberCtp = 0x4 , CheriRegisterNumberCT0 = 0x5 , CheriRegisterNumberCT1 = 0x6 , CheriRegisterNumberCT2 = 0x7 ,   CheriRegisterNumberCS0 = 0x8 , CheriRegisterNumberCS1 = 0x9 , CheriRegisterNumberCA0 = 0xa , CheriRegisterNumberCA1 = 0xb ,   CheriRegisterNumberCA2 = 0xc , CheriRegisterNumberCA3 = 0xd , CheriRegisterNumberCA4 = 0xe , CheriRegisterNumberCA5 = 0xf ,   CheriRegisterNumberPcc = 0x20 , CheriRegisterNumberMtcc = 0x3c , CheriRegisterNumberMtdc = 0x3d , CheriRegisterNumberMScratchC = 0x3e ,   CheriRegisterNumberMepcc = 0x3f , CheriRegisterNumberInvalid = -1 }
	Register numbers as reported in cap idx field of mtval CSR when a CHERI exception is taken. More...
enum	CHERISealingType {   CheriSealTypeUnsealed = 0 , CheriSealTypeSentryInheriting , CheriSealTypeSentryDisabling , CheriSealTypeSentryEnabling ,   CheriSealTypeReturnSentryDisabling , CheriSealTypeReturnSentryEnabling , CheriSealTypeFirstDataSealingType = 9 , CheriSealTypeSealedImportTableEntries = CheriSealTypeFirstDataSealingType ,   CheriSealTypeSealedTrustedStacks , CheriSealTypeAllocator , CheriSealTypeStaticToken , CheriSealTypeFirstStaticSoftware = 16 ,   CheriSealTypeFirstDynamicSoftware = 0x1000000 }
	Sealing types. More...

Functions
bool __cheri_libcall	check_pointer (const volatile void *ptr, size_t space, uint32_t rawPermissions, bool checkStackNeeded)
	Checks that ptr is valid, unsealed, has at least rawPermissions, and has at least space bytes after the current offset.

Detailed Description

C definitions for CHERI specific functionality.

Definition in file cheri.h.

Enumeration Type Documentation

CHERICauseCode

enum CHERICauseCode

The codes used in the cause field of the mtval CSR when the processor takes a CHERI exception.

Enumerator
CheriCauseCodeNone	No exception. This value is passed to the error handler after a forced unwind in a called compartment.
CheriCauseCodeBoundsViolation	Attempted to use a capability outside its bounds.
CheriCauseCodeTagViolation	Attempted to use an untagged capability to authorize something.
CheriCauseCodeSealViolation	Attempted to use a sealed capability to authorize something.
CheriCauseCodePermitExecuteViolation	Attempted to jump to a capability without Permission::Execute.
CheriCauseCodePermitLoadViolation	Attempted to load via a capability without Permission::Load.
CheriCauseCodePermitStoreViolation	Attempted to store via a capability without Permission::Store.
CheriCauseCodePermitStoreCapabilityViolation	Attempted to store a tagged capability via a capability without Permission::LoadStoreCapability.
CheriCauseCodePermitStoreLocalCapabilityViolation	Attempted to store a tagged capability without Permission::Global via capability without Permission::StoreLocal.
CheriCauseCodePermitAccessSystemRegistersViolation	Attempted to access a restricted CSR or SCR with PCC without Permission::AccessSystemRegisters.
CheriCauseCodeInvalid	Used to represent a value that has no valid meaning in hardware.

Definition at line 90 of file cheri.h.

CHERIPermission

enum CHERIPermission

The complete set of architectural permissions.

Enumerator
CheriPermissionGlobal	Capability refers to global memory (this capability may be stored anywhere).
CheriPermissionLoadGlobal	Global capabilities can be loaded through this capability. Without this permission, any capability loaded via this capability will have Global and LoadGlobal removed.
CheriPermissionStore	Capability may be used to store. Any store via a capability without this permission will trap.
CheriPermissionLoadMutable	Capabilities with store permission may be loaded through this capability. Without this, any loaded capability will have LoadMutable and Store removed.
CheriPermissionStoreLocal	This capability may be used to store capabilities that do not have Global permission.
CheriPermissionLoad	This capability can be used to load.
CheriPermissionLoadStoreCapability	Any load and store permissions on this capability convey the right to load or store capabilities in addition to data.
CheriPermissionAccessSystemRegisters	If installed as the program counter capability, running code may access privileged system registers.
CheriPermissionExecute	This capability may be used as a jump target and used to execute instructions.
CheriPermissionUnseal	This capability may be used to unseal other capabilities. The 'address' range is in the sealing type namespace and not in the memory namespace.
CheriPermissionSeal	This capability may be used to seal other capabilities. The 'address' range is in the sealing type namespace and not in the memory namespace.
CheriPermissionUser0	Software defined permission bit, no architectural meaning.

Definition at line 20 of file cheri.h.

CHERIRegisterNumber

enum CHERIRegisterNumber

Register numbers as reported in cap idx field of mtval CSR when a CHERI exception is taken.

Values less than 32 refer to general purpose registers and others to SCRs (of these, only PCC can actually cause an exception).

Enumerator
CheriRegisterNumberCzr	The zero register, which always contains the NULL capability.
CheriRegisterNumberCra	$c1 / $cra used by the ABI as the return address. Not preserved across calls.
CheriRegisterNumberCsp	$c2 / $csp used by the ABI as the stack pointer. Preserved across calls.
CheriRegisterNumberCgp	$c3 / $cgp used by the ABI as the global pointer. Not allocatable by the compiler, set by the switcher on compartment entry.
CheriRegisterNumberCtp	$c4 / $ctp used by the ABI as the thread pointer. Currently unused by the compiler. Not preserved across compartment calls.
CheriRegisterNumberCT0	$c5 / $ct0 used by the ABI as temporary register. Not preserved across calls.
CheriRegisterNumberCT1	$c6 / $ct1 used by the ABI as temporary register. Not preserved across calls.
CheriRegisterNumberCT2	$c7 / $ct2 used by the ABI as temporary register. Not preserved across calls.
CheriRegisterNumberCS0	$c8 / $cs0 used by the ABI as a callee-saved register. Preserved across calls.
CheriRegisterNumberCS1	$c9 / $cs1 used by the ABI as a callee-saved register. Preserved across calls.
CheriRegisterNumberCA0	$c10 / $ca0 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberCA1	$c11 / $ca1 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberCA2	$c12 / $ca2 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberCA3	$c13 / $ca3 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberCA4	$c14 / $ca4 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberCA5	$c15 / $ca5 used by the ABI as an argument register. Not preserved across calls.
CheriRegisterNumberPcc	The Program Counter Capability. Special capability register used to authorize instruction fetch. The address is that of the faulting instruction. Also used for accessing read-only globals.
CheriRegisterNumberMtcc	Machine-mode Trap Code Capability. Special capability register that is installed in PCC when the CPU takes a trap. The address has the same semantics as the RISC-V mtvec CSR. Only accessible when PCC has the AccessSystemRegisters permission.
CheriRegisterNumberMtdc	Machine-mode Tusted Data Capability. Special capability register that contains the memory root capability on boot. Only accessible when PCC has the AccessSystemRegisters permission. Use by the RTOS to store a capability to the trusted stack.
CheriRegisterNumberMScratchC	Machine-mode Scratch Capability. Special capabiltiy register that contains the sealing root capability on boot. Only accessible when PCC has the AccessSystemRegisters permission.
CheriRegisterNumberMepcc	Machine-mode Exception Program Counter Capability. Special capability register that contains the PCC of the faulting instruction on trap. The address has the same semantics as the RISC-V mepc CSR. Only accessible when PCC has the AccessSystemRegisters permission.
CheriRegisterNumberInvalid	Indicates a value that is not used by the hardware to refer to a register.

Definition at line 148 of file cheri.h.

CHERISealingType

enum CHERISealingType

Sealing types.

Enumerator
CheriSealTypeUnsealed	0 represents unsealed.
CheriSealTypeSentryInheriting	Sentry that inherits interrupt status.
CheriSealTypeSentryDisabling	Sentry that disables interrupts on calls.
CheriSealTypeSentryEnabling	Sentry that enables interrupts on calls.
CheriSealTypeReturnSentryDisabling	Return sentry that disables interrupts on return.
CheriSealTypeReturnSentryEnabling	Return sentry that enables interrupts on return.
CheriSealTypeFirstDataSealingType	Marker for the first sealing type that's valid for data capabilities.
CheriSealTypeSealedImportTableEntries	The sealing type used for sealed export table entries. This is RTOS- and not CHERIoT-specific.
CheriSealTypeSealedTrustedStacks	The compartment switcher has a sealing type for the trusted stack. This must be the second data sealing type so that we can also permit the switcher to unseal sentries and export table entries. This is RTOS- and not CHERIoT-specific.
CheriSealTypeAllocator	The allocator has a sealing type for the software sealing mechanism with dynamically allocated objects. This is RTOS- and not CHERIoT-specific.
CheriSealTypeStaticToken	The loader reserves a sealing type for the software sealing mechanism. The permit-unseal capability for this is destroyed after the loader has run, which guarantees that anything sealed with this type was present in the original firmware image. The token library has the only permit-unseal capability for this type. This is RTOS- and not CHERIoT-specific.
CheriSealTypeFirstStaticSoftware	The first sealing key that is reserved for use by the allocator's software sealing mechanism and used for static sealing types,. Architecturally, this is the smallest non-interpreted sealing type.
CheriSealTypeFirstDynamicSoftware	The first sealing key in the space that the allocator will dynamically allocate for sealing types. This is RTOS- and not CHERIoT-specific.

Definition at line 280 of file cheri.h.

Function Documentation

check_pointer()

bool __cheri_libcall check_pointer	(	const volatile void *	ptr,
		size_t	space,
		uint32_t	rawPermissions,
		bool	checkStackNeeded )

Checks that ptr is valid, unsealed, has at least rawPermissions, and has at least space bytes after the current offset.

If the permissions do not include Global and checkStackNeeded is false, then this will also check that the capability does not point to the current thread's stack.

To reduce code size, this function is provided as part of the compartment helper library.

Referenced by CHERI::check_pointer().