kernel/tests: improve documentation

7 files changed, 88 insertions, 10 deletions

diff --git a/kernel/include/kernel/test_support/bump_frame_allocator.hpp b/kernel/include/kernel/test_support/bump_frame_allocator.hpp
index 5203565..6380294 100644
--- a/kernel/include/kernel/test_support/bump_frame_allocator.hpp
+++ b/kernel/include/kernel/test_support/bump_frame_allocator.hpp
@@ -10,10 +10,28 @@
 namespace kernel::tests
 {
 
+  //! A simple bump-based frame allocator used for initial test bootstrap.
+  //!
+  //! We emulate the expected behavior of a platform, in that there is a handover to the kernel PMM that needs to happen
+  //! during boot. The expectation of the PMM initializer is that there is an active (if simple) frame allocator it can
+  //! use to reserve space for it's own metadata.
+  //!
+  //! @see kapi::memory::init_pmm
   struct bump_frame_allocator : kapi::memory::frame_allocator
   {
-    auto mark_used(kapi::memory::frame) -> void override {}
+    //! @copydoc kapi::memory::frame_allocator::mark_used
+    //!
+    //! @note Due to the simple nature of this allocator, all frames up to the given frame will be marked as used as
+    //! well.
+    auto mark_used(kapi::memory::frame frame) -> void override
+    {
+      if (frame.number() >= next_free_frame)
+      {
+        next_free_frame = frame.number() + 1;
+      }
+    }
 
+    //! @copydoc kapi::memory::frame_allocator::allocate_many
     auto allocate_many(std::size_t count) noexcept
         -> std::optional<std::pair<kapi::memory::frame, std::size_t>> override
     {
@@ -22,8 +40,12 @@ namespace kernel::tests
       return std::pair{kapi::memory::frame{start}, count};
     }
 
+    //! @copydoc kapi::memory::frame_allocator::release_many
+    //!
+    //! @note Due to the simple nature of this allocator, frames are never actually released.
     auto release_many(std::pair<kapi::memory::frame, std::size_t>) -> void override {}
 
+    //! The next free frame to be allocated.
     std::size_t next_free_frame{};
   };
 
diff --git a/kernel/include/kernel/test_support/cio.hpp b/kernel/include/kernel/test_support/cio.hpp
index 4b897b5..f7bac2d 100644
--- a/kernel/include/kernel/test_support/cio.hpp
+++ b/kernel/include/kernel/test_support/cio.hpp
@@ -9,20 +9,30 @@
 
 namespace kernel::tests::cio
 {
+
+  //! A simple output device that writes to one of the standard output streams and a log buffer.
   struct output_device : kapi::cio::output_device
   {
-    output_device() = default;
-
+    //! @copydoc kapi::cio::output_device::write
     auto write(kapi::cio::output_stream stream, std::string_view text) -> void override;
 
+    //! Get the log buffer associated with this device.
+    //!
+    //! @return The associated log buffer.
     [[nodiscard]] auto log_buffer() noexcept -> kernel::tests::log_buffer &;
 
   private:
+    //! The log buffer of this device.
     kernel::tests::log_buffer m_log_buffer{};
   };
 
+  //! Deinitialize the CIO subsystem.
   auto deinit() -> void;
 
+  //! Get the log buffer of the currently active output device.
+  //!
+  //! @throws std::runtime_error if no output device has been registered.
+  //! @return The currently active device's log buffer.
   [[nodiscard]] auto log_buffer() -> kernel::tests::log_buffer &;
 }  // namespace kernel::tests::cio
 
diff --git a/kernel/include/kernel/test_support/cpu.hpp b/kernel/include/kernel/test_support/cpu.hpp
index 037b1b2..c99d1a7 100644
--- a/kernel/include/kernel/test_support/cpu.hpp
+++ b/kernel/include/kernel/test_support/cpu.hpp
@@ -6,13 +6,16 @@
 namespace kernel::tests::cpu
 {
 
+  //! Exception thrown when the CPU is halted.
   struct halt : std::runtime_error
   {
+    //! Construct a new halt exception.
     halt()
         : std::runtime_error{"CPU halt requested!"}
     {}
   };
 
+  //! Deinitialize the CPU subsystem.
   auto deinit() -> void;
 
 }  // namespace kernel::tests::cpu
diff --git a/kernel/include/kernel/test_support/memory.hpp b/kernel/include/kernel/test_support/memory.hpp
index b475116..6034a1e 100644
--- a/kernel/include/kernel/test_support/memory.hpp
+++ b/kernel/include/kernel/test_support/memory.hpp
@@ -5,9 +5,18 @@
 
 namespace kernel::tests::memory
 {
+
+  //! Deinitialize the memory subsystem.
   auto deinit() -> void;
 
+  //! Get the virtual base address of the simulated system.
+  //!
+  //! Since we do not have direct access to an actual MMU, we simulate the virtual address space by mapping the
+  //! physical address space starting at some process local virtual address.
+  //!
+  //! @return The virtual base address of the simulated system.
   auto virtual_base() -> kapi::memory::linear_address;
+
 }  // namespace kernel::tests::memory
 
 #endif
\ No newline at end of file
diff --git a/kernel/include/kernel/test_support/page_mapper.hpp b/kernel/include/kernel/test_support/page_mapper.hpp
index 1658455..7ae9a4f 100644
--- a/kernel/include/kernel/test_support/page_mapper.hpp
+++ b/kernel/include/kernel/test_support/page_mapper.hpp
@@ -16,15 +16,31 @@ namespace kernel::tests
 
   struct page_mapper : kapi::memory::page_mapper
   {
+    //! Construct a new page mapper.
+    //!
+    //! @param physical_size The size of the physical memory.
+    //! @param virtual_size The size of the virtual address space.
     page_mapper(kstd::units::bytes physical_size, kstd::units::bytes virtual_size);
 
+    //! @copydoc kapi::memory::page_mapper::map
+    //!
+    //! @throws std::invalid_argument if the page has already been mapped.
+    //! @throws std::runtime_error if the page cannot be mapped.
+    //! @throws std::runtime_error if the underlying simulated memory cannot map the page.
     auto map(kapi::memory::page page, kapi::memory::frame frame, flags) -> std::byte * override;
 
+    //! @copydoc kapi::memory::page_mapper::unmap
+    //!
+    //! @throws std::invalid_argument if the page has not been mapped.
     auto unmap(kapi::memory::page page) -> void override;
 
+    //! @copydoc kapi::memory::page_mapper::try_unmap
     auto try_unmap(kapi::memory::page page) noexcept -> bool override;
 
+    //! The simulated memory.
     kernel::tests::simulated_memory memory;
+
+    //! The simplified page table entries.
     std::unordered_map<std::uint64_t, kapi::memory::frame> page_mappings;
   };
 
diff --git a/kernel/include/kernel/test_support/simulated_memory.hpp b/kernel/include/kernel/test_support/simulated_memory.hpp
index 1619f31..fa78aed 100644
--- a/kernel/include/kernel/test_support/simulated_memory.hpp
+++ b/kernel/include/kernel/test_support/simulated_memory.hpp
@@ -11,23 +11,46 @@
 namespace kernel::tests
 {
 
+  //! A simulated memory device that can be used in tests.
+  //!
+  //! The general idea is to provide a means to simulate the physical and virtual address spaces of the system. This
+  //! implementation provides for a single physical and a single virtual address space.
+  //!
+  //! @note This is not a full-featured MMU. It is a simple simulation that can be used for testing only.
   struct simulated_memory
   {
+    //! Construct a new simulated memory device.
+    //! @param physical_size The size of the physical memory.
+    //! @param virtual_size The size of the virtual address space.
     simulated_memory(kstd::units::bytes physical_size, kstd::units::bytes virtual_size);
 
+    //! Destroy this device
     ~simulated_memory();
 
+    //! Clear the contents of the physical memory of this device.
     auto clear() -> void;
 
+    //! Get the base address of the physical memory of this device.
     [[nodiscard]] auto physical_base() noexcept -> std::byte *;
+
+    //! Get the base address of the physical memory of this device.
     [[nodiscard]] auto physical_base() const noexcept -> std::byte const *;
+
+    //! Get the size of the physical memory of this device.
     [[nodiscard]] auto physical_size() const noexcept -> kstd::units::bytes;
 
+    //! Get the base address of the virtual address space of this device.
     [[nodiscard]] auto virtual_base() const noexcept -> kapi::memory::linear_address;
-    [[nodiscard]] auto virtual_size() const noexcept -> kstd::units::bytes;
 
-    [[nodiscard]] auto descriptor() const noexcept -> int;
+    //! Get the size of the virtual address space of this device.
+    [[nodiscard]] auto virtual_size() const noexcept -> kstd::units::bytes;
 
+    //! Map a region of physical memory to a region of virtual memory.
+    //!
+    //! @param size The size of the region to map.
+    //! @param to The base address of the virtual region.
+    //! @param offset The offset into the physical memory to map.
+    //! @return A pointer to the first byte of the mapped region.
     [[nodiscard]] auto map(kstd::units::bytes size, std::byte * to, off_t offset) -> std::byte *;
 
   private:
diff --git a/kernel/src/test_support/simulated_memory.cpp b/kernel/src/test_support/simulated_memory.cpp
index 0648df2..03dac1d 100644
--- a/kernel/src/test_support/simulated_memory.cpp
+++ b/kernel/src/test_support/simulated_memory.cpp
@@ -90,11 +90,6 @@ namespace kernel::tests
     return m_virtual_size;
   }
 
-  auto simulated_memory::descriptor() const noexcept -> int
-  {
-    return m_descriptor;
-  }
-
   auto simulated_memory::map(kstd::units::bytes size, std::byte * to, off_t offset) -> std::byte *
   {
     auto mapped_ptr = mmap(to, size.value, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_FIXED, m_descriptor, offset);