compartment.h

// Copyright Microsoft and CHERIoT Contributors.
// SPDX-License-Identifier: MIT
 
#pragma once
#include <cdefs.h>
#include <compartment-macros.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
#   include <cheri.hh>
#endif
 
/**
 * State for error handlers to use.
 *
 * Note: This structure should have the same layout as the register-save area
 * (that is, the initial sequence of a TrustedStack, up through ca5, inclusive).
 */
struct ErrorState
{
    /**
     * The faulting program counter.  Error handlers may modify this but the
     * result *must* point into the compartment's program counter capability.
     * If it does not then the trusted stack will be unwound forcibly to the
     * caller's compartment.
     *
     * Note: This is passed as an *untagged* capability.  This allows error
     * handlers to inspect the bounds and permissions, but does not convey the
     * rights.
     */
    void *pcc;
 
    /**
     * The register state where the fault occurred.  These may be modified by
     * an error handler.
     */
    void *registers[15];
#ifdef __cplusplus
    /**
     * Templated method to get a reference to value of given
     * CHERI::RegisterNumber.
     *
     * Static asserts that the register is one of the general purpose ones
     * excluding CZR. This doesn't support getting PCC because in that case
     * you can Use ErrorState.pcc directly.
     */
    template<CHERI::RegisterNumber ARegisterNumber>
    [[nodiscard]] void *&get_register_value()
    {
        static_assert(ARegisterNumber > CHERI::RegisterNumber::CZR &&
                        ARegisterNumber <= CHERI::RegisterNumber::CA5,
                      "get_register_value: invalid RegisterNumber");
        return this->registers[static_cast<size_t>(ARegisterNumber) - 1];
    }
 
    /**
     * Returns a pointer to the value of the given CHERI::RegisterNumber from
     * this ErrorState.
     *
     * Will either select the appropriate index into ErrorState.registers
     * accounting for the missing CZR, ErrorState.PCC, or if registerNumber is
     * invalid or not contained in ErrorState then nullptr is returned.
     */
    [[nodiscard]] void **
    get_register_value(CHERI::RegisterNumber registerNumber)
    {
        if (registerNumber > CHERI::RegisterNumber::CZR &&
            registerNumber <= CHERI::RegisterNumber::CA5)
        {
            return &this->registers[static_cast<size_t>(registerNumber) - 1];
        }
        if (registerNumber == CHERI::RegisterNumber::PCC)
        {
            return &this->pcc;
        }
        return nullptr;
    }
#endif
};
 
/**
 * Valid return values from an error handler.
 */
enum ErrorRecoveryBehaviour
{
    /// Install the modified context.
    InstallContext,
    /// Unwind the trusted stack to the caller.
    ForceUnwind
};
 
__BEGIN_DECLS
/**
 * The error handler for the current compartment.  A compartment may choose to
 * implement this.  If not implemented then compartment faults will unwind the
 * trusted stack.
 */
__attribute__((
  section(".compartment_error_handler"))) enum ErrorRecoveryBehaviour
compartment_error_handler(struct ErrorState *frame,
                          size_t             mcause,
                          size_t             mtval);
__END_DECLS