CHERI_INVOKE(3)

NAME
cheri_invoke - Library interface CHERI capability invocation

LIBRARY
libcheri

SYNOPSIS
#include <machine/cheri.h>
#include <machine/cheric.h>
#include <cheri_invoke.h>
#if __has_feature(capabilities)
register_t
cheri_invoke(__capability void *c1, __capability void *c2, register_t a0, register_t a1, register_t a2, register_t a3, register_t a4, register_t a5, register_t a6, register_t a7, __capability void *c3, __capability void *c4, __capability void *c5, __capability void *c6, __capability void *c7, __capability void *c8, __capability void *c9, __capability void *c10);
#else
register_t
cheri_invoke(register_t a0, register_t a1, register_t a2, register_t a3, register_t a4, register_t a5, register_t a6, register_t a7);
#endif

DESCRIPTION
cheri_invoke() is a C-language wrapper for the CHERI CCall instruction, taking as its arguments code and data capabilities ($c1, $c2), a set of general-purpose argument registers, and a set of capability argument registers. If compiling with a capability-aware compiler, then capability arguments are explicit and the compiler will arrange for the arguments to be placed in the appropriate hardware registers. Without compiler support, explicit assembly instructions must be used to implement the CHERI ABI. By convention, $a0 will contain a method number.

Most programmers will prefer to employ the libcheri(3) sandbox API rather than use cheri_invoke() directly.

RETURN VALUES
cheri_invoke() returns the value returned by the invoked capabilities unless a sandbox fault occurs, in which case -1 will be returned. As a method returning -1 cannot be distinguished from a fault in the caller, use of negative return values for method return values is discouraged.

SEE ALSO
libcheri(3)

AUTHORS
This software and this manual page were written by Robert N. M. Watson, and developed by SRI International and the University of Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) (“CTSRD”), as part of the DARPA CRASH research programme.