From eafbf588760c289b7f54a4771b39af0ccfe8cf59 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Wed, 10 Dec 2025 21:55:42 +0100
Subject: kapi: extract page_mapper interface

---
 kapi/include/kapi/memory.hpp             |  2 +
 kapi/include/kapi/memory/page_mapper.hpp | 82 ++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 kapi/include/kapi/memory/page_mapper.hpp

(limited to 'kapi/include')

diff --git a/kapi/include/kapi/memory.hpp b/kapi/include/kapi/memory.hpp
index 4279274..9ca1267 100644
--- a/kapi/include/kapi/memory.hpp
+++ b/kapi/include/kapi/memory.hpp
@@ -5,10 +5,12 @@
 #include "kapi/memory/frame.hpp"            // IWYU pragma: export
 #include "kapi/memory/frame_allocator.hpp"  // IWYU pragma: export
 #include "kapi/memory/page.hpp"             // IWYU pragma: export
+#include "kapi/memory/page_mapper.hpp"      // IWYU pragma: export
 
 namespace teachos::memory
 {
   auto active_allocator() -> frame_allocator &;
+  auto active_mapper() -> page_mapper &;
   auto init() -> void;
 }  // namespace teachos::memory
 
diff --git a/kapi/include/kapi/memory/page_mapper.hpp b/kapi/include/kapi/memory/page_mapper.hpp
new file mode 100644
index 0000000..aa5cf76
--- /dev/null
+++ b/kapi/include/kapi/memory/page_mapper.hpp
@@ -0,0 +1,82 @@
+#ifndef TEACHOS_KAPI_MEMORY_PAGE_MAPPER_HPP
+#define TEACHOS_KAPI_MEMORY_PAGE_MAPPER_HPP
+
+// IWYU pragma: private, include "kapi/memory.hpp"
+
+#include "kapi/memory/frame.hpp"
+#include "kapi/memory/page.hpp"
+
+#include <kstd/ext/bitfield_enum>
+
+#include <type_traits>
+
+namespace teachos::memory
+{
+
+  // NOLINTNEXTLINE(cppcoreguidelines-special-member-functions)
+  struct page_mapper
+  {
+    enum struct flags : std::uint64_t
+    {
+      empty,
+      writable = 1 << 0,
+      executable = 1 << 1,
+      uncached = 1 << 2,
+      supervisor = 1 << 3,
+    };
+
+    virtual ~page_mapper() = default;
+
+    /**
+     * Map a page into a given frame, applying the given flags.
+     *
+     * @param page The page to map.
+     * @param frame The frame to map the page into.
+     * @param flags The flags to map the page with.
+     * @return A pointer to the first byte of mapped page.
+     */
+    virtual auto map(page page, frame frame, flags flags) -> std::byte * = 0;
+
+    /**
+     * Unmap the given page.
+     *
+     * @warning If the provided page is not mapped, this function will panic.
+     * @param page The page to unmap.
+     */
+    virtual auto unmap(page page) -> void = 0;
+
+    /**
+     * Try to unmap the given page.
+     *
+     * @param page The page to unmap
+     * @return true iff. the page was successfully unmapped, false otherwise.
+     */
+    virtual auto try_unmap(page page) -> bool = 0;
+
+    /**
+     * Map a page into a given frame, applyint the given flags.
+     *
+     * @tparam T The type of data contained in the page.
+     * @param page The page to map.
+     * @param frame The frame to map the page into.
+     * @param flags The flags to map the page with.
+     * @return A pointer to the first T in the page.
+     */
+    template<typename T>
+    [[nodiscard]] auto map_as(page page, frame frame, flags flags) -> T *
+    {
+      return std::bit_cast<T *>(map(page, frame, flags));
+    }
+  };
+
+}  // namespace teachos::memory
+
+namespace kstd::ext
+{
+  template<>
+  struct is_bitfield_enum<teachos::memory::page_mapper::flags> : std::true_type
+  {
+  };
+}  // namespace kstd::ext
+
+#endif
\ No newline at end of file
-- 
cgit v1.2.3