Macros for interacting with the compartmentalisation model in CHERIoT. More...

#include <__compartment-macros.h>

Macros
#define	MMIO_CAPABILITY_WITH_PERMISSIONS(type, name, permitLoad, permitStore, permitLoadStoreCapabilities, permitLoadMutable, permitLoadGlobal)
	Provide a capability of the type volatile type * referring to the MMIO region exported in the linker script with name as its name.
#define	MMIO_CAPABILITY(type, name)
	Provide a capability of the type volatile type * referring to the MMIO region exported in the linker script with name as its name.
#define	SHARED_OBJECT_WITH_PERMISSIONS(type, name, permitLoad, permitStore, permitLoadStoreCapabilities, permitLoadMutable, permitLoadGlobal)
	Provide a capability of the type type * referring to the pre-shared object with name as its name.
#define	SHARED_OBJECT(type, name)
	Provide a capability of the type type * referring to the pre-shared object with name as its name.
#define	SHARED_OBJECT_WITH_DATA_PERMISSIONS( type, name, permitLoad, permitStore)
	Provide a capability of the type type * referring to the pre-shared object with name as its name.
#define	DEVICE_EXISTS(x)
	Macro to test whether a device with a specific name exists in the board definition for the current target.
#define	STATIC_SEALING_TYPE(name)
	Macro that evaluates to a static sealing type that is local to this compartment.
#define	DECLARE_STATIC_SEALED_VALUE_EXPLICIT_TYPE( type, valueType, compartment, keyName, name)
	Forward-declare a static sealed object.
#define	DECLARE_STATIC_SEALED_VALUE(type, compartment, keyName, name)
	Forward-declare a static sealed object.
#define	DEFINE_STATIC_SEALED_VALUE( type, compartment, keyName, name, initialiser, ...)
	Define a static sealed object.
#define	DECLARE_AND_DEFINE_STATIC_SEALED_VALUE_EXPLICIT_TYPE( type, valueType, compartment, keyName, name, initialiser, ...)
	Helper macro that declares and defines a sealed value.
#define	DECLARE_AND_DEFINE_STATIC_SEALED_VALUE( type, compartment, keyName, name, initialiser, ...)
	Helper macro that declares and defines a sealed value.
#define	STATIC_SEALED_VALUE(name)
	Returns a sealed capability to the named object created with DECLARE_STATIC_SEALED_VALUE.
#define	CHERIOT_INITIALISER(function, priority)
	Declare a CHERIoT initialiser function.

Detailed Description

Macros for interacting with the compartmentalisation model in CHERIoT.

Definition in file compartment-macros.h.

Macro Definition Documentation

◆ CHERIOT_INITIALISER

#define CHERIOT_INITIALISER	(		function,
			priority )

Declare a CHERIoT initialiser function.

This macro can be used in place of a prototype for a function called function. Initialiser functions are called in ascending priority order.

Initialiser functions take no arguments and return void.

Definition at line 398 of file compartment-macros.h.

◆ DECLARE_AND_DEFINE_STATIC_SEALED_VALUE

#define DECLARE_AND_DEFINE_STATIC_SEALED_VALUE	(	type,
		compartment,
		keyName,
		name,
		initialiser,
		... )

Helper macro that declares and defines a sealed value.

The arguments for this are the same as DEFINE_STATIC_SEALED_VALUE. Use this version when you do not need a separate forward declaration.

Definition at line 345 of file compartment-macros.h.

◆ DECLARE_AND_DEFINE_STATIC_SEALED_VALUE_EXPLICIT_TYPE

#define DECLARE_AND_DEFINE_STATIC_SEALED_VALUE_EXPLICIT_TYPE	(	type,
		valueType,
		compartment,
		keyName,
		name,
		initialiser,
		... )

Helper macro that declares and defines a sealed value.

Unlike DECLARE_AND_DEFINE_STATIC_SEALED_VALUE, this allows the type that value should be read as to be different to the type used to initialise it. The type of the value in STATIC_SEALED_VALUE will be CHERI_SEALED(valueType*). This is useful for variable length arrays at the end of the structure.

Definition at line 321 of file compartment-macros.h.

◆ DECLARE_STATIC_SEALED_VALUE

#define DECLARE_STATIC_SEALED_VALUE	(	type,
		compartment,
		keyName,
		name )

Forward-declare a static sealed object.

This declares an object of type type that can be referenced with the STATIC_SEALED_VALUE macro using name. The pointer returned by the latter macro will be sealed with the sealing key exported from compartment as keyName with the STATIC_SEALING_TYPE macro.

The object created with this macro can be accessed only by code that has access to the sealing key.

Definition at line 268 of file compartment-macros.h.

◆ DECLARE_STATIC_SEALED_VALUE_EXPLICIT_TYPE

#define DECLARE_STATIC_SEALED_VALUE_EXPLICIT_TYPE	(	type,
		valueType,
		compartment,
		keyName,
		name )

Forward-declare a static sealed object.

This declares an object of type type that can be referenced with the STATIC_SEALED_VALUE macro using name. The pointer returned by the latter macro will be sealed with the sealing key exported from compartment as keyName with the STATIC_SEALING_TYPE macro.

The object created with this macro can be accessed only by code that has access to the sealing key.

Unlike DECLARE_STATIC_SEALED_VALUE, this allows the type that value should be read as to be different to the type used to initialise it. The type of the value in STATIC_SEALED_VALUE will be CHERI_SEALED(valueType*). This is useful for variable length arrays at the end of the structure.

Definition at line 239 of file compartment-macros.h.

◆ DEFINE_STATIC_SEALED_VALUE

#define DEFINE_STATIC_SEALED_VALUE	(	type,
		compartment,
		keyName,
		name,
		initialiser,
		... )

Define a static sealed object.

This creates an object of type type, initialised with initialiser, that can be referenced with the STATIC_SEALED_VALUE macro using name. The pointer returned by the latter macro will be sealed with the sealing key exported from compartment as keyName with the STATIC_SEALING_TYPE macro.

The object created with this macro can be accessed only by code that has access to the sealing key.

If you do not need a separate forward definition, use DECLARE_AND_DEFINE_STATIC_SEALED_VALUE instead.

Definition at line 294 of file compartment-macros.h.

◆ DEVICE_EXISTS

#define DEVICE_EXISTS ( x )

Macro to test whether a device with a specific name exists in the board definition for the current target.

Definition at line 187 of file compartment-macros.h.

◆ MMIO_CAPABILITY

#define MMIO_CAPABILITY	(		type,
			name )

Provide a capability of the type volatile type * referring to the MMIO region exported in the linker script with name as its name.

This macro can be used only in code (it cannot be used to initialise a global).

MMIO capabilities produced by this macro have load and store permissions but cannot hold capabilities. For richer permissions use MMIO_CAPABILITY_WITH_PERMISSIONS.

Definition at line 90 of file compartment-macros.h.

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

◆ MMIO_CAPABILITY_WITH_PERMISSIONS

#define MMIO_CAPABILITY_WITH_PERMISSIONS	(	type,
		name,
		permitLoad,
		permitStore,
		permitLoadStoreCapabilities,
		permitLoadMutable,
		permitLoadGlobal )

Provide a capability of the type volatile type * referring to the MMIO region exported in the linker script with name as its name.

This macro can be used only in code (it cannot be used to initialise a global).

The last arguments specify the set of permissions that this capability holds:

permitLoad if this should have load / read (R) permission.
permitStore if this should have store / write (W) permission.
permitLoadStoreCapabilities if this should have load/store capability permission (C).
permitLoadMutable if this should have load-mutable (m) permission. This permission requires R and C.
permitLoadGlobal if this should have load-global (g) permission. This permission requires R and C.

At least one out of permitLoad and permitStore should be provided.

MMIO capabilities are always global (G) and without store-local (l) permission.

Definition at line 57 of file compartment-macros.h.

◆ SHARED_OBJECT

#define SHARED_OBJECT	(		type,
			name )

Provide a capability of the type type * referring to the pre-shared object with name as its name.

This macro can be used only in code (it cannot be used to initialise a global).

Pre-shared object capabilities produced by this macro have load, store, load-mutable, and load/store-capability permissions. To define a reduced set of permissions use SHARED_OBJECT_WITH_PERMISSIONS.

Definition at line 161 of file compartment-macros.h.

◆ SHARED_OBJECT_WITH_DATA_PERMISSIONS

#define SHARED_OBJECT_WITH_DATA_PERMISSIONS	(	type,
		name,
		permitLoad,
		permitStore )

Provide a capability of the type type * referring to the pre-shared object with name as its name.

This macro can be used only in code (it cannot be used to initialise a global).

Pre-shared object capabilities produced by this macro have the indicated load and store permission, but no load/store-capability permissions (and, therefore, no load-mutable or load-global permissions).

Definition at line 176 of file compartment-macros.h.

◆ SHARED_OBJECT_WITH_PERMISSIONS

#define SHARED_OBJECT_WITH_PERMISSIONS	(	type,
		name,
		permitLoad,
		permitStore,
		permitLoadStoreCapabilities,
		permitLoadMutable,
		permitLoadGlobal )

Provide a capability of the type type * referring to the pre-shared object with name as its name.

This macro can be used only in code (it cannot be used to initialise a global).

The last arguments specify the set of permissions that this capability holds: Load Data (LD), Store Data (SD), Memory Capabilities (MC), Load Mutable (LM), and Load Global (LG).

Capabilities to pre-shared objects are always global (G) and without store-local (l) permission.

Definition at line 128 of file compartment-macros.h.

◆ STATIC_SEALED_VALUE

#define STATIC_SEALED_VALUE ( name )

Returns a sealed capability to the named object created with DECLARE_STATIC_SEALED_VALUE.

Definition at line 360 of file compartment-macros.h.

Referenced by Ibex::HardwareRevoker< WordT, TCMBaseAddr >::init(), Ksz8851Ethernet::Ksz8851Ethernet(), and KunyanEthernet::KunyanEthernet().

◆ STATIC_SEALING_TYPE

#define STATIC_SEALING_TYPE ( name )

Macro that evaluates to a static sealing type that is local to this compartment.

The name is a unique identifier. This matches the keyName passed to DECLARE_STATIC_SEALED_VALUE and related macros and will appear in the audit log when linking the firmware image. Names within a compartment may be unique but two compartments may expose sealing types of the same name without conflicts.

Definition at line 206 of file compartment-macros.h.