From cf500b301ee3f518ea391ea21e39853b7e7a37c8 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Sun, 26 Jul 2026 20:33:10 +0200
Subject: kapi: implement a simple, tracked mutex

---
 kapi/kapi/cpu.hpp           | 26 ++++++++++++++++++++++++
 kapi/kapi/tracked_mutex.hpp | 48 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 kapi/kapi/tracked_mutex.hpp

(limited to 'kapi')

diff --git a/kapi/kapi/cpu.hpp b/kapi/kapi/cpu.hpp
index 41e00e40..9a50f67e 100644
--- a/kapi/kapi/cpu.hpp
+++ b/kapi/kapi/cpu.hpp
@@ -7,6 +7,7 @@
 #include <kstd/memory.hpp>
 
 #include <cstdint>
+#include <limits>
 
 namespace kapi::cpu
 {
@@ -62,6 +63,17 @@ namespace kapi::cpu
     bool is_user_mode{};
   };
 
+  //! A stable id for a single logical CPU core.
+  struct id
+  {
+    constexpr auto friend operator==(id const &, id const &) noexcept -> bool = default;
+
+    std::uint64_t value{};
+  };
+
+  //! The invalid CPU id.
+  constexpr auto static invalid_id = id{std::numeric_limits<std::uint64_t>::max()};
+
   //! @}
 
   //! @addtogroup kapi-cpu-kernel-defined
@@ -94,6 +106,11 @@ namespace kapi::cpu
   //! @return true iff. the CPU topology was discovered successfully, false otherwise.
   auto discover_topology() -> bool;
 
+  //! Get the current CPU id.
+  //!
+  //! @return The id of the CPU core currently executing the call to this function.
+  [[nodiscard]] auto current_id() -> id;
+
   //! @}
 
 }  // namespace kapi::cpu
@@ -132,4 +149,13 @@ struct kstd::formatter<enum kapi::cpu::exception::type>
   }
 };
 
+template<>
+struct kstd::formatter<kapi::cpu::id> : kstd::formatter<std::uint64_t>
+{
+  constexpr auto format(kapi::cpu::id const & id, kstd::format_context & ctx) const -> void
+  {
+    kstd::formatter<std::uint64_t>::format(id.value, ctx);
+  }
+};
+
 #endif
diff --git a/kapi/kapi/tracked_mutex.hpp b/kapi/kapi/tracked_mutex.hpp
new file mode 100644
index 00000000..11b99e12
--- /dev/null
+++ b/kapi/kapi/tracked_mutex.hpp
@@ -0,0 +1,48 @@
+#ifndef TEACHOS_KAPI_TRACKED_MUTEX_HPP
+#define TEACHOS_KAPI_TRACKED_MUTEX_HPP
+
+#include <kapi/cpu.hpp>
+
+#include <atomic>
+
+namespace kapi
+{
+
+  //! @addtogroup kapi-kernel-defined
+  //! @{
+
+  struct tracked_mutex
+  {
+    constexpr tracked_mutex() = default;
+    tracked_mutex(tracked_mutex const &) = delete;
+    tracked_mutex(tracked_mutex &&) = delete;
+    auto operator=(tracked_mutex const &) -> tracked_mutex & = delete;
+    auto operator=(tracked_mutex &&) -> tracked_mutex & = delete;
+
+    //! Lock this mutex, potentially blocking if it already locked.
+    //!
+    //! @warning This function will panic if a recursive lock on a single core is detected!
+    auto lock() -> void;
+
+    //! Try to lock this mutex.
+    //!
+    //! @note This function will not panic if a recursive lock on a single core is detected, but rather it will return
+    //! false.
+    //!
+    //! @return true iff. the mutex was locked, false otherwise.
+    [[nodiscard]] auto try_lock() -> bool;
+
+    //! Unlock this mutex.
+    //!
+    //! @warning This function will panic if the core executing the call does not own the lock on this mutex!
+    auto unlock() -> void;
+
+  private:
+    std::atomic<kapi::cpu::id> m_owner{kapi::cpu::invalid_id};
+  };
+
+  //! @}
+
+}  // namespace kapi
+
+#endif
\ No newline at end of file
-- 
cgit v1.2.3