APIs for interacting with the switcher. More...

#include <cdefs.h>
#include <stddef.h>
#include <stdint.h>

Functions
__cheri_libcall _Bool	trusted_stack_has_space (int requiredFrames)
	Returns true if the trusted stack contains at least requiredFrames frames past the current one, false otherwise.
__cheri_libcall void *	switcher_recover_stack (void)
	Recover the stack value that was passed into a compartment on cross-compartment call.
__cheri_libcall void **	switcher_thread_hazard_slots (void)
	Returns a store-only capability to two hazard pointer slots for the current thread.
__cheri_libcall ptraddr_t	stack_lowest_used_address (void)
	Returns the lowest address that has been stored to on the stack in this compartment invocation.
__cheri_libcall uint16_t	switcher_handler_invocation_count_reset (void)
	Resets the switcher's count of invocations.

Detailed Description

APIs for interacting with the switcher.

Definition in file switcher.h.

Function Documentation

◆ switcher_handler_invocation_count_reset()

__cheri_libcall uint16_t switcher_handler_invocation_count_reset ( void )

Resets the switcher's count of invocations.

Switcher place a limit on the number of times a compartment invocation may fault (default 512). This prevents a compartment from getting stuck partially recovering from errors. This function resets the count to zero. It should be called from outer compartments' run loops and from places where the caller is certain that error handling is making forward progress.

Note: If this is called from an error handler that subsequently returns with with install-context, the switcher will subtract one from this and set the switcher error count to -1. Because this is odd, the switcher will detect the next invocation of the error handler as a double fault and will force unwind. Do not call this if you are currently in an error handler unless you are jumping out via some mechanism that does not involve returning to the switcher.

Returns the previous value of the invocation count. The low bit is set if an error handler is currently running, the remaining bits are the count.

Referenced by cleanup_unwind().

◆ switcher_recover_stack()

__cheri_libcall void * switcher_recover_stack ( void )

Recover the stack value that was passed into a compartment on cross-compartment call.

This allows sub-compartment compartmentalization (e.g. running another OS in a compartment) where the monitor in the compartment uses heap-allocated stacks for the nested compartments, while providing a mechanism for the monitor to recover the stack.

◆ switcher_thread_hazard_slots()

__cheri_libcall void ** switcher_thread_hazard_slots ( void )

Returns a store-only capability to two hazard pointer slots for the current thread.

Objects stored here will not be deallocated until (at least) the next cross-compartment call or until they are explicitly overwritten.

◆ trusted_stack_has_space()

__cheri_libcall _Bool trusted_stack_has_space ( int requiredFrames )

Returns true if the trusted stack contains at least requiredFrames frames past the current one, false otherwise.