kapi: remodel memory API to follow cio API

1 files changed, 41 insertions, 18 deletions

diff --git a/kapi/include/kapi/memory.hpp b/kapi/include/kapi/memory.hpp
index bed8dbc..b51a8a5 100644
--- a/kapi/include/kapi/memory.hpp
+++ b/kapi/include/kapi/memory.hpp
@@ -8,39 +8,62 @@
 #include "kapi/memory/page.hpp"             // IWYU pragma: export
 #include "kapi/memory/page_mapper.hpp"      // IWYU pragma: export
 
+#include <cstddef>
+#include <optional>
+
 namespace teachos::memory
 {
 
   //! @qualifier platform-defined
-  //! Get the currently active frame allocator.
+  //! Initialize the memory subsystem.
   //!
   //! @note This function must be implemented by the target platform.
   //!
-  //! @warning If no allocator has been initialized yet, the behavior of this function is platform implementation
-  //! defined. Implementations are encouraged to terminate execution via a kernel panic.
+  //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page
+  //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered.
+  auto init() -> void;
+
+  //! @qualifier kernel-defined
+  //! Set the currently active frame allocator.
   //!
-  //! @return A reference to the currently active frame allocator.
-  auto active_frame_allocator() -> frame_allocator &;
+  //! @param allocator A new frame allocator.
+  //! @return The previously active frame allocator.
+  auto set_frame_allocator(frame_allocator & allocator) -> std::optional<frame_allocator *>;
 
-  //! @qualifier platform-defined
-  //! Get the currently active page mapper.
+  //! @qualifier kernel-defined
+  //! Set the currently active page mapper.
   //!
-  //! @note This function must be implemented by the target platform.
+  //! @param mapper A new page mapper.
+  //! @return The previously active page mapper.
+  auto set_page_mapper(page_mapper & mapper) -> std::optional<page_mapper *>;
+
+  //! @qualifier kernel-defined
+  //! Allocate a new frame of physical memory
   //!
-  //! @warning If no mapper has been initialized yet, the behavior of this function is platform implementation
-  //! defined. Implementations are encouraged to terminate execution via a kernel panic.
+  //! @warning This function will panic if no frame allocator has been registered.
   //!
-  //! @return A reference to the currently active page mapper.
-  auto active_page_mapper() -> page_mapper &;
+  //! @return An engaged std::optional iff. a frame could be allocated, std::nullopt otherwise.
+  auto allocate_frame() -> std::optional<frame>;
 
-  //! @qualifier platform-defined
-  //! Initialize the memory subsystem.
+  //! @qualifier kernel-defined
+  //! Map a page onto a frame.
   //!
-  //! @note This function must be implemented by the target platform.
+  //! @warning This function will panic if no page mapper has been registered, or the page has already been mapped.
+  //! This function will not ensure that the frame is not already in use.
   //!
-  //! This function initializes the memory subsystem and activates the platform-specific frame allocator and page
-  //! mapper. When this function returns, a valid frame allocator and page mapper are expected to have been registered.
-  auto init() -> void;
+  //! @param page The page to map.
+  //! @param frame The frame to map the page into.
+  //! @return A pointer to the first byte of the mapped page.
+  auto map(page page, frame frame) -> std::byte *;
+
+  //! @qualifier kernel-defined
+  //! Unmap a page.
+  //!
+  //! @warning This function will panic if no page mapper has been registered, or the page has already been mapped.
+  //! This function will not ensure that the frame is not already in use.
+  //!
+  //! @param page The page to unmap
+  auto unmap(page page) -> void;
 
 }  // namespace teachos::memory