implement trap handler

docs/doxygen/groups.dox

@@ -9,8 +9,8 @@
 @defgroup stdbigos
 	@defgroup sbi
 	@defgroup csr
-	@defgroup trap
 	@defgroup types
 	@defgroup string
 	@defgroup bitutils
+@defgroup trap Interrupt and exception handling
 */

docs/source/pages/api/libs/index.rst

@@ -6,4 +6,5 @@ Bigos Libraries
    :maxdepth: 1
 
    dt
+   trap
    stdbigos/index

docs/source/pages/api/libs/stdbigos/index.rst

@@ -7,7 +7,6 @@ Stdbigos
 
    sbi
    csr
-   trap
    types
    string
    bitutils

docs/source/pages/api/libs/trap.rst

@@ -0,0 +1,5 @@
+===============
+RISC-V trap API
+===============
+
+.. doxygengroup:: trap

include/stdbigos/csr.h

@@ -1,8 +1,15 @@
 #ifndef STDBIGOS_CSR
 #define STDBIGOS_CSR
 
+#include "csr_vals.h"
 #include "types.h"
 
+/**
+ * @addtogroup stdbigos
+ * @addtogroup csr
+ * @{
+ */
+
 #define CSR_SWAP(csr, val)                                                               \
 	({                                                                                   \
 		reg_t _val = (reg_t)(val);                                                       \
@@ -57,24 +64,20 @@
 		__asm__ volatile("csrc " #csr ", %0" : : "rK"(_val) : "memory"); \
 	})
 
-/// @addtogroup stdbigos
-/// @{
-/// @addtogroup csr
-/// @{
-
-static inline u32 hartid() {
-	return CSR_READ_RELAXED(mhartid);
-}
-
 static inline void wfi() {
 	__asm__ volatile("wfi" ::: "memory");
 }
 
 static inline void ebreak() {
 	__asm__ volatile("ebreak" ::: "memory");
 }
+static inline void intr_enable() {
+	CSR_SET(sstatus, CSR_SSTATUS_SIE);
+}
+static inline void intr_disable() {
+	CSR_CLEAR(sstatus, CSR_SSTATUS_SIE);
+}
 
-/// @}
 /// @}
 
 #endif // !STDBIGOS_CSR

include/stdbigos/csr_vals.h

@@ -0,0 +1,22 @@
+#ifndef STDBIGOS_CSR_VALS
+#define STDBIGOS_CSR_VALS
+
+#define CSR_SSTATUS_SIE        (1ul << 1)
+#define CSR_SSTATUS_SPIE       (1ul << 5)
+#define CSR_SSTATUS_UBE        (1ul << 6)
+#define CSR_SSTATUS_SPP        (1ul << 8)
+#define CSR_SSTATUS_VS_OFFSET  9
+#define CSR_SSTATUS_VS_MASK    0b11
+#define CSR_SSTATUS_FS_OFFSET  13
+#define CSR_SSTATUS_FS_MASK    0b11
+#define CSR_SSTATUS_XS_OFFSET  15
+#define CSR_SSTATUS_XS_MASK    0b11
+#define CSR_SSTATUS_SUM        (1ul << 18)
+#define CSR_SSTATUS_MXR        (1ul << 19)
+#define CSR_SSTATUS_SPELP      (1ul << 23)
+#define CSR_SSTATUS_SDT        (1ul << 24)
+#define CSR_SSTATUS_UXL_OFFSET 32
+#define CSR_SSTATUS_UXL_MASK   0b11
+#define CSR_SSTATUS_SD         (1ul << 63)
+
+#endif // !STDBIGOS_CSR_VALS

include/trap/trap.h

@@ -0,0 +1,184 @@
+#ifndef TRAP_H
+#define TRAP_H
+
+#include <stdbigos/error.h>
+#include <stdbigos/types.h>
+
+/**
+ * @addtogroup trap
+ * @{
+ */
+
+/// @brief Encoded interrupt cause values from the RISC-V `scause` CSR.
+typedef enum trap_interrupt_type {
+	TRAP_INT_S_SOFTWARE = 1,
+	TRAP_INT_S_TIMER = 5,
+	TRAP_INT_S_EXTERNAL = 9,
+	TRAP_INT_COUNTER_OVERFLOW = 13,
+	// >=16 are for platform use
+} trap_interrupt_type_t;
+
+/** @brief Encoded exception cause values from the RISC-V `scause` CSR. */
+typedef enum trap_exception_type {
+	TRAP_EXC_INSTR_ADDRESS_MISALIGNED = 0,
+	TRAP_EXC_INSTR_ACCESS_FAULT = 1,
+	TRAP_EXC_ILLEGAL_INSTR = 2,
+	TRAP_EXC_BREAKPOINT = 3,
+	TRAP_EXC_LOAD_ADDRESS_MISALIGNED = 4,
+	TRAP_EXC_LOAD_ACCESS_FAULT = 5,
+	TRAP_EXC_STORE_ADDRESS_MISALIGNED = 6,
+	TRAP_EXC_STORE_ACCESS_FAULT = 7,
+	TRAP_EXC_ENV_CALL_U = 8,
+	TRAP_EXC_ENV_CALL_S = 9,
+	TRAP_EXC_INSTR_PAGE_FAULT = 12,
+	TRAP_EXC_LOAD_PAGE_FAULT = 13,
+	TRAP_EXC_STORE_PAGE_FAULT = 15,
+	TRAP_EXC_SOFTWARE_CHECK = 18,
+	TRAP_EXC_HARDWARE_ERROR = 19,
+	// 24-31 designated for custom use
+	// 48-63 designated for custom use
+	// >=64 reserved
+} trap_exception_type_t;
+
+/**
+ * @brief Saved trap context.
+ *
+ * Structure representing the saved context of a trap, including general-purpose registers and relevant CSRs.
+ * It is also used for state transitions (e.g from S-mode to U-mode) by preparing the structure on the
+ * target stack and performing a trap return (see `trap_utils_prepare_stack_for_transition` and
+ * `trap_restore_with_cleanup`).
+ */
+typedef struct trap_frame {
+	union {
+		/// General-purpose registers
+		reg_t gpr[31];
+		struct {
+			reg_t ra;
+			reg_t sp;
+			reg_t gp;
+			reg_t tp;
+			reg_t t0;
+			reg_t t1;
+			reg_t t2;
+			reg_t s0;
+			reg_t s1;
+			reg_t a0;
+			reg_t a1;
+			reg_t a2;
+			reg_t a3;
+			reg_t a4;
+			reg_t a5;
+			reg_t a6;
+			reg_t a7;
+			reg_t s2;
+			reg_t s3;
+			reg_t s4;
+			reg_t s5;
+			reg_t s6;
+			reg_t s7;
+			reg_t s8;
+			reg_t s9;
+			reg_t s10;
+			reg_t s11;
+			reg_t t3;
+			reg_t t4;
+			reg_t t5;
+			reg_t t6;
+		};
+	};
+	/// value of `sepc` CSR
+	reg_t sepc;
+	/// value of `sstatus` CSR
+	reg_t sstatus;
+	/// value of `stval` CSR
+	reg_t stval;
+	/// value of `scause` CSR
+	reg_t scause;
+} trap_frame_t;
+
+static_assert(sizeof(trap_frame_t) == 35 * sizeof(reg_t));
+
+/**
+ * @brief Trap handler callback executed by the trap trampoline.
+ */
+typedef void (*pfn_trap_handler_t)(trap_frame_t* tf);
+/**
+ * @brief Continuation callback used by stack transition helpers.
+ */
+typedef void (*pfn_continuation_t)(void* user);
+
+/**
+ * @brief Returns `true` if a trap cause corresponds to an interrupt.
+ * @param cause Raw `scause` value.
+ * @return `true` if the cause is an interrupt, `false` if it is an exception.
+ */
+bool trap_is_interrupt(reg_t cause);
+
+/**
+ * @brief Extracts interrupt code from `scause` by clearing the interrupt bit.
+ * @param cause Raw `scause` value.
+ * @return Interrupt code.
+ */
+trap_interrupt_type_t trap_get_interrupt_code(reg_t cause);
+
+/**
+ * @brief Returns exception code from `scause`.
+ * @param cause Raw `scause` value.
+ * @return Exception code.
+ */
+trap_exception_type_t trap_get_exception_code(reg_t cause);
+
+/**
+ * @brief Installs trap entry and sets kernel trap callback.
+ *
+ * @param handler Non-null C trap handler.
+ *
+ * @retval ERR_NONE success
+ */
+[[gnu::nonnull]]
+error_t trap_init(pfn_trap_handler_t handler);
+
+/**
+ * @brief Prepares a stack so trap restore can continue from a supplied frame.
+ *
+ * @param stack In/out top of the kernel stack pointer after the transition. Updated to point to the new top after
+ * pushing the trap frame.
+ * @param tf Trap frame copied onto the target stack.
+ *
+ * @retval ERR_NONE success
+ */
+[[gnu::nonnull]]
+error_t trap_utils_prepare_stack_for_transition(void** stack, const trap_frame_t* tf);
+
+/**
+ * @brief Switches to `stack` and transfers control to `continuation(user)`.
+ *
+ * This is a helper routine for performing stack/context transitions, e.g. when
+ * migrating from the boot stack to a per-hart kernel stack. The `continuation`
+ * callback is executed after the stack switch, and receives a user-provided pointer for context.
+ *
+ * @param stack Top of the kernel stack to switch to.
+ * @param user User-provided pointer passed to the continuation callback.
+ * @param continuation Non-null callback executed after the stack switch.
+ */
+[[noreturn, gnu::nonnull(1, 3)]]
+void trap_utils_jump_with_stack(void* stack, void* user, pfn_continuation_t continuation);
+
+/**
+ * @brief Restores trap context from `stack`, optionally running `cleanup(user)` first on the new stack.
+ *
+ * This is a helper routine for performing trap return with an optional cleanup step. If `cleanup` is non-null,
+ * it is executed on the new stack before performing the trap return to user mode.
+ * The `user` pointer is passed to the cleanup callback for context.
+ *
+ * @param stack Top of the kernel stack containing the trap frame to restore.
+ * @param user User-provided pointer passed to the cleanup callback.
+ * @param cleanup Optional callback executed before trap return. If null, the trap return is performed immediately
+ * without cleanup.
+ */
+[[noreturn, gnu::nonnull(1)]]
+void trap_restore_with_cleanup(void* stack, void* user, pfn_continuation_t cleanup);
+
+/// @}
+
+#endif // !TRAP_H