CHERIoT RTOS heap allocator interface. More...

#include <cdefs.h>
#include <riscvreg.h>
#include <stddef.h>
#include <timeout.h>
#include <token.h>

Enumerations
enum	AllocatorPermission { AllocatorPermitNone = 0 , AllocatorPermitAllocate = (1 << 0) , AllocatorPermitFreeAll = (1 << 1) , AllocatorPermitUnused = (1 << 2) , AllocatorPermitFull }
	Permission bits for allocator capabilities. More...

Functions
typedef	CHERI_SEALED (struct AllocatorCapabilityState *) AllocatorCapability
static int	allocator_permissions (AllocatorCapability heapCapability)
	Returns the permissions held by this allocator capability.
static AllocatorCapability	allocator_permissions_and (AllocatorCapability heapCapability, int permissions)
	Returns a copy of heapCapability with a subset of permissions.
ssize_t	heap_claim (AllocatorCapability heapCapability, void *pointer)
	Add a claim to an allocation.
int __cheri_libcall	heap_claim_ephemeral (TimeoutArgument timeout, const void ptr, const void ptr2)
	Interface to the ephemeral claims mechanism.
static int	heap_claim_fast (TimeoutArgument timeout, const void ptr, const void ptr2)
ssize_t	heap_free_all (AllocatorCapability heapCapability)
	Free all allocations owned by this capability.
int	heap_can_free (AllocatorCapability heapCapability, void *ptr)
	Returns 0 if the allocation can be freed with the given capability, -EPERM if heapCapability is not valid or it cannot free the provided allocation (such as when heapCapability does not own the allocation, and holds no claim on it), and -EINVAL if ptr is not a valid pointer into a live heap allocation.
ssize_t	heap_quota_remaining (AllocatorCapability heapCapability)
	Returns the space available in the given quota.
int	heap_quarantine_flush (TimeoutArgument timeout)
	Try to empty the quarantine and defragment the heap.
static int	heap_quarantine_empty ()
	Run heap_quarantine_flush with unlimited timeout.
int	heap_render ()
	Dump a textual rendering of the heap's structure to the debug console.
size_t	heap_available (void)
	Returns the total available space in the heap.

Detailed Description

CHERIoT RTOS heap allocator interface.

Definition in file allocator.h.

Enumeration Type Documentation

◆ AllocatorPermission

enum AllocatorPermission

Permission bits for allocator capabilities.

Permission to free is implicit, and cannot be restricted.

Enumerator
AllocatorPermitNone	This allocator capability is fully de-permissioned. Note that this capability can still be used to free.
AllocatorPermitAllocate	This allocator capability may be used to perform allocations and make claims using its quota.
AllocatorPermitFreeAll	This allocator capability may be used to free all allocations made using its quota via heap_free_all.
AllocatorPermitUnused	Unused permissions bit.
AllocatorPermitFull	This allocator capability is fully permissioned. It can be used to allocate and free all.

Definition at line 27 of file allocator.h.

Function Documentation

◆ allocator_permissions()

int allocator_permissions ( AllocatorCapability heapCapability )

inlinestatic

Returns the permissions held by this allocator capability.

This is a bitmask of AllocatorPermission values.

Definition at line 60 of file allocator.h.

References token_permissions_get().

◆ allocator_permissions_and()

AllocatorCapability allocator_permissions_and	(	AllocatorCapability	heapCapability,
		int	permissions )

inlinestatic

Returns a copy of heapCapability with a subset of permissions.

The permissions argument is a bitmask of AllocatorPermission values. The returned allocator capability has only the permissions that are both already present on heapCapability and enumerated in permissions.

Definition at line 72 of file allocator.h.

References token_permissions_and().

◆ heap_available()

size_t heap_available ( void )

Returns the total available space in the heap.

This counts free space but does not account for quota restrictions.

References heap_available().

Referenced by heap_available().

◆ heap_claim()

ssize_t heap_claim	(	AllocatorCapability	heapCapability,
		void *	pointer )

Add a claim to an allocation.

The object will be counted against the quota provided by the first argument until a corresponding call to heap_free. Note that this can be used with interior pointers.

This will return the size of the allocation claimed on success (which may be larger than the size requested in the original heap_allocate call; see its documentation for more information).

Returns -EPERM if heapCapability does not have permission to perform this claim, -ENOMEM if the provided quota is too small to accomodate the claim, and -EINVAL if pointer is not a valid pointer into a live heap allocation.

Similarly to heap_allocate, -ENOTENOUGHSTACK may be returned if the stack is insufficiently large to run the function. See heap_allocate.

References heap_claim().

Referenced by heap_claim().

◆ heap_claim_ephemeral()

int __cheri_libcall heap_claim_ephemeral	(	TimeoutArgument	timeout,
		const void *	ptr,
		const void *	ptr2 )

Interface to the ephemeral claims mechanism.

This claims two pointers using the hazard-pointer-inspired lightweight claims mechanism. If this function returns zero then the heap pointers are guaranteed not to become invalid until either the next cross-compartment call or the next call to this function.

A null pointer can be used as a not-present value. This function will treat operations on null pointers as unconditionally successful. It returns -ETIMEDOUT if it failed to claim before the timeout expired, or -EINVAL if one or more of the arguments is neither null nor a valid pointer at the end.

In the case of failure, neither pointer will have been claimed.

This function is provided by the compartment_helpers library, which must be linked for it to be available.

References heap_claim_ephemeral().

Referenced by heap_claim_ephemeral(), Ksz8851Ethernet::send_frame(), and KunyanEthernet::send_frame().

◆ heap_claim_fast()

int heap_claim_fast	(	TimeoutArgument	timeout,
		const void *	ptr,
		const void *	ptr2 )

static

Definition at line 122 of file allocator.h.

◆ heap_free_all()

ssize_t heap_free_all ( AllocatorCapability heapCapability )

Free all allocations owned by this capability.

Returns the number of bytes freed, -EPERM if this heap capability does not have permission to perform this action, or -ENOTENOUGHSTACK if the stack size is insufficiently large to safely run the function.

References heap_free_all().

Referenced by heap_free_all().

◆ heap_quarantine_empty()

int heap_quarantine_empty ( )

static

Run heap_quarantine_flush with unlimited timeout.

This is guaranteed to terminate (barring bugs), but, as with most unlimited-timeout operation, should be confined to debug or test code.

Definition at line 191 of file allocator.h.

References heap_quarantine_empty(), heap_quarantine_flush(), and TimeoutWaitForever.

Referenced by heap_quarantine_empty().

◆ heap_quarantine_flush()

int heap_quarantine_flush ( TimeoutArgument timeout )

Try to empty the quarantine and defragment the heap.

This will (finish and then) run a revocation sweep and try to empty the quarantine. In normal operation, the allocator will remove a small number of allocations from quarantine on each allocation. Allocations are not coalesced until they are moved from quarantine, so this can cause fragmentation. If you have just freed a lot of memory (for example, after resetting a compartment and calling heap_free_all), especially if you have freed a lot of small allocations, then calling this function will likely reduce fragmentation.

Calling this function will ensure that all objects freed before the call are out of quarantine (unless a timeout occurs). Objects freed concurrently (by another thread) may remain in quarantine, so this does not guarantee that the quarantine is empty, only that everything freed by this thread is removed from quarantine.

Returns 0 on success, a compartment invocation failure indication (-ENOTENOUGHSTACK, -ENOTENOUGHTRUSTEDSTACK) if it cannot be invoked, or possibly -ECOMPARTMENTFAIL if the allocator compartment is damaged.

Returns -ETIMEDOUT if the timeout expires or -EINVAL if the timeout is not valid.

References heap_quarantine_flush().

Referenced by heap_quarantine_empty(), and heap_quarantine_flush().