sdk/include/cheri.h - 3p/cheriot-rtos - Git at Google

 // Copyright CHERIoT Contributors.
 // SPDX-License-Identifier: MIT

 #pragma once
 #include <compartment-macros.h>
 #include <stddef.h>
 #include <stdint.h>

 struct Timeout;

 /**
  * The complete set of architectural permissions.
  */
 enum CHERIPermission
 {
 	/**
 	 * Capability refers to global memory (this capability may be stored
 	 * anywhere).
 	 */
 	CheriPermissionGlobal = 0,
 	/**
 	 * Global capabilities can be loaded through this capability.  Without
 	 *  this permission, any capability loaded via this capability will
 	 *  have `Global` and `LoadGlobal` removed.
 	 */
 	CheriPermissionLoadGlobal = 1,
 	/**
 	 * Capability may be used to store.  Any store via a capability without
 	 * this permission will trap.
 	 */
 	CheriPermissionStore = 2,
 	/**
 	 * Capabilities with store permission may be loaded through this
 	 * capability.  Without this, any loaded capability will have
 	 * `LoadMutable` and `Store` removed.
 	 */
 	CheriPermissionLoadMutable = 3,
 	/**
 	 * This capability may be used to store capabilities that do not have
 	 * `Global` permission.
 	 */
 	CheriPermissionStoreLocal = 4,
 	/**
 	 * This capability can be used to load.
 	 */
 	CheriPermissionLoad = 5,
 	/**
 	 * Any load and store permissions on this capability convey the right to
 	 * load or store capabilities in addition to data.
 	 */
 	CheriPermissionLoadStoreCapability = 6,
 	/**
 	 * If installed as the program counter capability, running code may
 	 * access privileged system registers.
 	 */
 	CheriPermissionAccessSystemRegisters = 7,
 	/**
 	 * This capability may be used as a jump target and used to execute
 	 * instructions.
 	 */
 	CheriPermissionExecute = 8,
 	/**
 	 * This capability may be used to unseal other capabilities.  The
 	 * 'address' range is in the sealing type namespace and not in the
 	 * memory namespace.
 	 */
 	CheriPermissionUnseal = 9,
 	/**
 	 * This capability may be used to seal other capabilities.  The
 	 * 'address' range is in the sealing type namespace and not in the
 	 * memory namespace.
 	 */
 	CheriPermissionSeal = 10,
 	/**
 	 * Software defined permission bit, no architectural meaning.
 	 */
 	CheriPermissionUser0 = 11
 };

 /**
  * The codes used in the cause field of the mtval CSR when the processor
  * takes a CHERI exception.
  */
 enum CHERICauseCode
 {
 	/**
 	 * No exception. This value is passed to the error handler after a
 	 * forced unwind in a called compartment.
 	 */
 	CheriCauseCodeNone = 0,
 	/**
 	 * Attempted to use a capability outside its bounds.
 	 */
 	CheriCauseCodeBoundsViolation = 1,
 	/**
 	 * Attempted to use an untagged capability to authorize something.
 	 */
 	CheriCauseCodeTagViolation = 2,
 	/**
 	 * Attempted to use a sealed capability to authorize something.
 	 */
 	CheriCauseCodeSealViolation = 3,
 	/**
 	 * Attempted to jump to a capability without `Permission::Execute`.
 	 */
 	CheriCauseCodePermitExecuteViolation = 0x11,
 	/**
 	 * Attempted to load via a capability without `Permission::Load`.
 	 */
 	CheriCauseCodePermitLoadViolation = 0x12,
 	/**
 	 * Attempted to store via a capability without `Permission::Store`.
 	 */
 	CheriCauseCodePermitStoreViolation = 0x13,
 	/**
 	 * Attempted to store a tagged capability via a capability without
 	 * `Permission::LoadStoreCapability`.
 	 */
 	CheriCauseCodePermitStoreCapabilityViolation = 0x15,
 	/**
 	 * Attempted to store a tagged capability without `Permission::Global`
 	 * via capability without `Permission::StoreLocal`.
 	 */
 	CheriCauseCodePermitStoreLocalCapabilityViolation = 0x16,
 	/**
 	 * Attempted to access a restricted CSR or SCR with PCC without
 	 * `Permission::AccessSystemRegisters`.
 	 */
 	CheriCauseCodePermitAccessSystemRegistersViolation = 0x18,
 	/**
 	 * Used to represent a value that has no valid meaning in hardware.
 	 */
 	CheriCauseCodeInvalid = -1
 };

 /**
  * 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).
  */
 enum CHERIRegisterNumber
 {
 	/**
 	 * The zero register, which always contains the `NULL` capability.
 	 */
 	CheriRegisterNumberCzr = 0x0,
 	/**
 	 * `$c1` / `$cra` used by the ABI as the return address.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCra = 0x1,
 	/**
 	 * `$c2` / `$csp` used by the ABI as the stack pointer.
 	 * Preserved across calls.
 	 */
 	CheriRegisterNumberCsp = 0x2,
 	/**
 	 * `$c3` / `$cgp` used by the ABI as the global pointer.
 	 * Not allocatable by the compiler, set by the switcher on compartment
 	 * entry.
 	 */
 	CheriRegisterNumberCgp = 0x3,
 	/**
 	 * `$c4` / `$ctp` used by the ABI as the thread pointer.
 	 * Currently unused by the compiler.
 	 * Not preserved across compartment calls.
 	 */
 	CheriRegisterNumberCtp = 0x4,
 	/**
 	 * `$c5` / `$ct0` used by the ABI as temporary register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCT0 = 0x5,
 	/**
 	 * `$c6` / `$ct1` used by the ABI as temporary register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCT1 = 0x6,
 	/**
 	 * `$c7` / `$ct2` used by the ABI as temporary register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCT2 = 0x7,
 	/**
 	 * `$c8` / `$cs0` used by the ABI as a callee-saved register.
 	 * Preserved across calls.
 	 */
 	CheriRegisterNumberCS0 = 0x8,
 	/**
 	 * `$c9` / `$cs1` used by the ABI as a callee-saved register.
 	 * Preserved across calls.
 	 */
 	CheriRegisterNumberCS1 = 0x9,
 	/**
 	 * `$c10` / `$ca0` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA0 = 0xa,
 	/**
 	 * `$c11` / `$ca1` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA1 = 0xb,
 	/**
 	 * `$c12` / `$ca2` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA2 = 0xc,
 	/**
 	 * `$c13` / `$ca3` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA3 = 0xd,
 	/**
 	 * `$c14` / `$ca4` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA4 = 0xe,
 	/**
 	 * `$c15` / `$ca5` used by the ABI as an argument register.
 	 * Not preserved across calls.
 	 */
 	CheriRegisterNumberCA5 = 0xf,
 	/**
 	 * 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.
 	 */
 	CheriRegisterNumberPcc = 0x20,
 	/**
 	 * 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.
 	 */
 	CheriRegisterNumberMtcc = 0x3c,
 	/**
 	 * 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.
 	 */
 	CheriRegisterNumberMtdc = 0x3d,
 	/**
 	 * Machine-mode Scratch Capability. Special capabiltiy register that
 	 * contains the sealing root capability on boot. Only accessible when
 	 * PCC has the AccessSystemRegisters permission.
 	 */
 	CheriRegisterNumberMScratchC = 0x3e,
 	/**
 	 * 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.
 	 */
 	CheriRegisterNumberMepcc = 0x3f,
 	/**
 	 * Indicates a value that is not used by the hardware to refer to a
 	 * register.
 	 */
 	CheriRegisterNumberInvalid = -1
 };

 /**
  * Sealing types.
  */
 enum CHERISealingType
 {
 	/**
 	 * 0 represents unsealed.
 	 */
 	CheriSealTypeUnsealed = 0,

 	/**
 	 * Sentry that inherits interrupt status.
 	 */
 	CheriSealTypeSentryInheriting,

 	/**
 	 * Sentry that disables interrupts on calls.
 	 */
 	CheriSealTypeSentryDisabling,

 	/**
 	 * Sentry that enables interrupts on calls.
 	 */
 	CheriSealTypeSentryEnabling,

 	/**
 	 * Return sentry that disables interrupts on return
 	 */
 	CheriSealTypeReturnSentryDisabling,

 	/**
 	 * Return sentry that enables interrupts on return
 	 */
 	CheriSealTypeReturnSentryEnabling,

 	/**
 	 * Marker for the first sealing type that's valid for data capabilities.
 	 */
 	CheriSealTypeFirstDataSealingType = 9,

 	/**
 	 * The sealing type used for sealed export table entries.
 	 *
 	 * This is RTOS- and not CHERIoT-specific.
 	 */
 	CheriSealTypeSealedImportTableEntries = CheriSealTypeFirstDataSealingType,

 	/**
 	 * 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.
 	 */
 	CheriSealTypeSealedTrustedStacks,

 	/**
 	 * The allocator has a sealing type for the software sealing mechanism
 	 * with dynamically allocated objects.
 	 *
 	 * This is RTOS- and not CHERIoT-specific.
 	 */
 	CheriSealTypeAllocator,

 	/**
 	 * 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.
 	 */
 	CheriSealTypeStaticToken,

 	/**
 	 * 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.
 	 */
 	CheriSealTypeFirstStaticSoftware = 16,

 	/**
 	 * The first sealing key in the space that the allocator will
 	 * dynamically allocate for sealing types.
 	 *
 	 * This is RTOS- and not CHERIoT-specific.
 	 */
 	CheriSealTypeFirstDynamicSoftware = 0x1000000
 };

 /**
  * 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.
  */
 bool __cheri_libcall check_pointer(const void *ptr,
                                    size_t      space,
                                    uint32_t    rawPermissions,
                                    bool        checkStackNeeded);

 /**
  * Check that the argument is a valid pointer to a `Timeout` structure.  This
  * must have read/write permissions, be unsealed, and must not be a heap
  * address.
  */
 bool __cheri_libcall check_timeout_pointer(const struct Timeout *timeout);
	// Copyright CHERIoT Contributors.
	// SPDX-License-Identifier: MIT

	#pragma once
	#include <compartment-macros.h>
	#include <stddef.h>
	#include <stdint.h>

	struct Timeout;

	/**
	* The complete set of architectural permissions.
	*/
	enum CHERIPermission
	{
	/**
	* Capability refers to global memory (this capability may be stored
	* anywhere).
	*/
	CheriPermissionGlobal = 0,
	/**
	* Global capabilities can be loaded through this capability. Without
	* this permission, any capability loaded via this capability will
	* have `Global` and `LoadGlobal` removed.
	*/
	CheriPermissionLoadGlobal = 1,
	/**
	* Capability may be used to store. Any store via a capability without
	* this permission will trap.
	*/
	CheriPermissionStore = 2,
	/**
	* Capabilities with store permission may be loaded through this
	* capability. Without this, any loaded capability will have
	* `LoadMutable` and `Store` removed.
	*/
	CheriPermissionLoadMutable = 3,
	/**
	* This capability may be used to store capabilities that do not have
	* `Global` permission.
	*/
	CheriPermissionStoreLocal = 4,
	/**
	* This capability can be used to load.
	*/
	CheriPermissionLoad = 5,
	/**
	* Any load and store permissions on this capability convey the right to
	* load or store capabilities in addition to data.
	*/
	CheriPermissionLoadStoreCapability = 6,
	/**
	* If installed as the program counter capability, running code may
	* access privileged system registers.
	*/
	CheriPermissionAccessSystemRegisters = 7,
	/**
	* This capability may be used as a jump target and used to execute
	* instructions.
	*/
	CheriPermissionExecute = 8,
	/**
	* This capability may be used to unseal other capabilities. The
	* 'address' range is in the sealing type namespace and not in the
	* memory namespace.
	*/
	CheriPermissionUnseal = 9,
	/**
	* This capability may be used to seal other capabilities. The
	* 'address' range is in the sealing type namespace and not in the
	* memory namespace.
	*/
	CheriPermissionSeal = 10,
	/**
	* Software defined permission bit, no architectural meaning.
	*/
	CheriPermissionUser0 = 11
	};

	/**
	* The codes used in the cause field of the mtval CSR when the processor
	* takes a CHERI exception.
	*/
	enum CHERICauseCode
	{
	/**
	* No exception. This value is passed to the error handler after a
	* forced unwind in a called compartment.
	*/
	CheriCauseCodeNone = 0,
	/**
	* Attempted to use a capability outside its bounds.
	*/
	CheriCauseCodeBoundsViolation = 1,
	/**
	* Attempted to use an untagged capability to authorize something.
	*/
	CheriCauseCodeTagViolation = 2,
	/**
	* Attempted to use a sealed capability to authorize something.
	*/
	CheriCauseCodeSealViolation = 3,
	/**
	* Attempted to jump to a capability without `Permission::Execute`.
	*/
	CheriCauseCodePermitExecuteViolation = 0x11,
	/**
	* Attempted to load via a capability without `Permission::Load`.
	*/
	CheriCauseCodePermitLoadViolation = 0x12,
	/**
	* Attempted to store via a capability without `Permission::Store`.
	*/
	CheriCauseCodePermitStoreViolation = 0x13,
	/**
	* Attempted to store a tagged capability via a capability without
	* `Permission::LoadStoreCapability`.
	*/
	CheriCauseCodePermitStoreCapabilityViolation = 0x15,
	/**
	* Attempted to store a tagged capability without `Permission::Global`
	* via capability without `Permission::StoreLocal`.
	*/
	CheriCauseCodePermitStoreLocalCapabilityViolation = 0x16,
	/**
	* Attempted to access a restricted CSR or SCR with PCC without
	* `Permission::AccessSystemRegisters`.
	*/
	CheriCauseCodePermitAccessSystemRegistersViolation = 0x18,
	/**
	* Used to represent a value that has no valid meaning in hardware.
	*/
	CheriCauseCodeInvalid = -1
	};

	/**
	* 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).
	*/
	enum CHERIRegisterNumber
	{
	/**
	* The zero register, which always contains the `NULL` capability.
	*/
	CheriRegisterNumberCzr = 0x0,
	/**
	* `$c1` / `$cra` used by the ABI as the return address.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCra = 0x1,
	/**
	* `$c2` / `$csp` used by the ABI as the stack pointer.
	* Preserved across calls.
	*/
	CheriRegisterNumberCsp = 0x2,
	/**
	* `$c3` / `$cgp` used by the ABI as the global pointer.
	* Not allocatable by the compiler, set by the switcher on compartment
	* entry.
	*/
	CheriRegisterNumberCgp = 0x3,
	/**
	* `$c4` / `$ctp` used by the ABI as the thread pointer.
	* Currently unused by the compiler.
	* Not preserved across compartment calls.
	*/
	CheriRegisterNumberCtp = 0x4,
	/**
	* `$c5` / `$ct0` used by the ABI as temporary register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCT0 = 0x5,
	/**
	* `$c6` / `$ct1` used by the ABI as temporary register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCT1 = 0x6,
	/**
	* `$c7` / `$ct2` used by the ABI as temporary register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCT2 = 0x7,
	/**
	* `$c8` / `$cs0` used by the ABI as a callee-saved register.
	* Preserved across calls.
	*/
	CheriRegisterNumberCS0 = 0x8,
	/**
	* `$c9` / `$cs1` used by the ABI as a callee-saved register.
	* Preserved across calls.
	*/
	CheriRegisterNumberCS1 = 0x9,
	/**
	* `$c10` / `$ca0` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA0 = 0xa,
	/**
	* `$c11` / `$ca1` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA1 = 0xb,
	/**
	* `$c12` / `$ca2` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA2 = 0xc,
	/**
	* `$c13` / `$ca3` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA3 = 0xd,
	/**
	* `$c14` / `$ca4` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA4 = 0xe,
	/**
	* `$c15` / `$ca5` used by the ABI as an argument register.
	* Not preserved across calls.
	*/
	CheriRegisterNumberCA5 = 0xf,
	/**
	* 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.
	*/
	CheriRegisterNumberPcc = 0x20,
	/**
	* 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.
	*/
	CheriRegisterNumberMtcc = 0x3c,
	/**
	* 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.
	*/
	CheriRegisterNumberMtdc = 0x3d,
	/**
	* Machine-mode Scratch Capability. Special capabiltiy register that
	* contains the sealing root capability on boot. Only accessible when
	* PCC has the AccessSystemRegisters permission.
	*/
	CheriRegisterNumberMScratchC = 0x3e,
	/**
	* 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.
	*/
	CheriRegisterNumberMepcc = 0x3f,
	/**
	* Indicates a value that is not used by the hardware to refer to a
	* register.
	*/
	CheriRegisterNumberInvalid = -1
	};

	/**
	* Sealing types.
	*/
	enum CHERISealingType
	{
	/**
	* 0 represents unsealed.
	*/
	CheriSealTypeUnsealed = 0,

	/**
	* Sentry that inherits interrupt status.
	*/
	CheriSealTypeSentryInheriting,

	/**
	* Sentry that disables interrupts on calls.
	*/
	CheriSealTypeSentryDisabling,

	/**
	* Sentry that enables interrupts on calls.
	*/
	CheriSealTypeSentryEnabling,

	/**
	* Return sentry that disables interrupts on return
	*/
	CheriSealTypeReturnSentryDisabling,

	/**
	* Return sentry that enables interrupts on return
	*/
	CheriSealTypeReturnSentryEnabling,

	/**
	* Marker for the first sealing type that's valid for data capabilities.
	*/
	CheriSealTypeFirstDataSealingType = 9,

	/**
	* The sealing type used for sealed export table entries.
	*
	* This is RTOS- and not CHERIoT-specific.
	*/
	CheriSealTypeSealedImportTableEntries = CheriSealTypeFirstDataSealingType,

	/**
	* 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.
	*/
	CheriSealTypeSealedTrustedStacks,

	/**
	* The allocator has a sealing type for the software sealing mechanism
	* with dynamically allocated objects.
	*
	* This is RTOS- and not CHERIoT-specific.
	*/
	CheriSealTypeAllocator,

	/**
	* 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.
	*/
	CheriSealTypeStaticToken,

	/**
	* 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.
	*/
	CheriSealTypeFirstStaticSoftware = 16,

	/**
	* The first sealing key in the space that the allocator will
	* dynamically allocate for sealing types.
	*
	* This is RTOS- and not CHERIoT-specific.
	*/
	CheriSealTypeFirstDynamicSoftware = 0x1000000
	};

	/**
	* 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.
	*/
	bool __cheri_libcall check_pointer(const void *ptr,
	size_t space,
	uint32_t rawPermissions,
	bool checkStackNeeded);

	/**
	* Check that the argument is a valid pointer to a `Timeout` structure. This
	* must have read/write permissions, be unsealed, and must not be a heap
	* address.
	*/
	bool __cheri_libcall check_timeout_pointer(const struct Timeout *timeout);