From fd6ac1cbfbe90fa807dca60657bb80ed43c78aee Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Wed, 25 Mar 2026 07:45:08 +0100
Subject: kapi/cpu: improve documentation

---
 kapi/include/kapi/cpu/exception.hpp | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

(limited to 'kapi')

diff --git a/kapi/include/kapi/cpu/exception.hpp b/kapi/include/kapi/cpu/exception.hpp
index 09e15a7..6d39175 100644
--- a/kapi/include/kapi/cpu/exception.hpp
+++ b/kapi/include/kapi/cpu/exception.hpp
@@ -10,28 +10,40 @@
 namespace kapi::cpu
 {
 
+  //! An exception originating from the CPU directly.
+  //!
+  //! Exception generally model interrupts that are synchronous to the instruction stream. This means that they do not
+  //! originate from external hardware, but rather are a product of program execution.
   struct exception
   {
+    //! The type of the exception, which identifies the reason for it being raised.
     enum class type : std::uint8_t
     {
+      //! The reason for the exception is unknown or platform-specific
       unknown,
+      //! A page fault occurred
       page_fault,
+      //! A memory access (either in the data or instruction stream) violated it's alignment constraints.
       alignment_fault,
+      //! A memory access (either in the data or instruction stream) violated it's permissions.
       memory_access_fault,
-      illegal_instruction,
+      //! The precoditions for the execution of an instruction were not met.
       privilege_violation,
+      //! An arithmetic error occurred.
       arithmetic_error,
+      //! A breakpoint was hit in the instruction stream.
       breakpoint,
+      //! The CPU is single-stepping through the instruction stream.
       single_step,
     };
 
-    //! The type of exception.
+    //! The type of this exception.
     type type{};
 
-    //! The instruction pointer at the time of the exception.
+    //! The value of the instruction pointer at the time this exception was raised.
     kapi::memory::linear_address instruction_pointer{};
 
-    //! The memory address that caused the exception.
+    //! The memory address that caused this exception.
     kapi::memory::linear_address access_address{};
 
     //! Whether the page was present at the time of the exception.
@@ -44,15 +56,26 @@ namespace kapi::cpu
     bool is_user_mode{};
   };
 
+  //! The abstract interface for exception handlers.
+  //!
+  //! The kernel must define an exception handler to be used during execution.
   struct exception_handler
   {
     virtual ~exception_handler() = default;
 
+    //! Handle an exception.
+    //!
+    //! @param context The exception context.
+    //! @return Whether the exception was handled.
     virtual auto handle(exception const & context) -> bool = 0;
   };
 
+  //! @qualifier kernel-defined
+  //! Get the currently active exception handler.
   auto get_exception_handler() -> exception_handler &;
 
+  //! @qualifier kernel-defined
+  //! Set the exception handler.
   auto set_exception_handler(exception_handler & handler) -> void;
 
 }  // namespace kapi::cpu
-- 
cgit v1.2.3