From 5f88077406422bf18d95247598eaa6f21010f2cf Mon Sep 17 00:00:00 2001
From: TheASVigilante <65920585+TheASVigilante@users.noreply.github.com>
Date: Fri, 5 May 2023 20:43:47 +0200
Subject: [PATCH] Add a few comments to the Memory manager

---
 app/src/main/cpp/skyline/kernel/memory.cpp | 10 ++++++----
 app/src/main/cpp/skyline/kernel/memory.h   | 18 ++++++++++++++----
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/app/src/main/cpp/skyline/kernel/memory.cpp b/app/src/main/cpp/skyline/kernel/memory.cpp
index 0eabcb8d..57bf329a 100644
--- a/app/src/main/cpp/skyline/kernel/memory.cpp
+++ b/app/src/main/cpp/skyline/kernel/memory.cpp
@@ -43,7 +43,7 @@ namespace skyline::kernel {
             if ((firstChunk.state == memory::states::Unmapped) != isUnmapping)
                 needsReprotection = true;
 
-            // We edit the chunk's first half
+            // We reduce the size of the first half
             firstChunk.size = static_cast<size_t>(newDesc.first - firstChunkBase->first);
             chunks[firstChunkBase->first] = firstChunk;
 
@@ -69,12 +69,13 @@ namespace skyline::kernel {
 
             bool shouldInsert{true};
 
+            // We check if the new chunk and the first chunk is mergable
             if (firstChunk.IsCompatible(newDesc.second)) {
                 shouldInsert = false;
 
                 firstChunk.size = static_cast<size_t>((newDesc.first + newDesc.second.size) - firstChunkBase->first);
                 chunks[firstChunkBase->first] = firstChunk;
-            } else if ((firstChunkBase->first + firstChunk.size) != newDesc.first) {
+            } else if ((firstChunkBase->first + firstChunk.size) != newDesc.first) { // If it's not mergable check if it needs resizing
                 firstChunk.size = static_cast<size_t>(newDesc.first - firstChunkBase->first);
 
                 chunks[firstChunkBase->first] = firstChunk;
@@ -83,6 +84,7 @@ namespace skyline::kernel {
                     needsReprotection = true;
             }
 
+            // We check if the new chunk and the last chunk is mergable
             if (lastChunk.IsCompatible(newDesc.second)) {
                 u8 *oldBase{lastChunkBase->first};
                 chunks.erase(lastChunkBase);
@@ -97,7 +99,7 @@ namespace skyline::kernel {
                     firstChunk.size = static_cast<size_t>((lastChunk.size + oldBase) - firstChunkBase->first);
                     chunks[firstChunkBase->first] = firstChunk;
                 }
-            } else if ((newDesc.first + newDesc.second.size) != lastChunkBase->first) {
+            } else if ((newDesc.first + newDesc.second.size) != lastChunkBase->first) { // If it's not mergable check if it needs resizing
                 lastChunk.size = static_cast<size_t>((lastChunk.size + lastChunkBase->first) - (newDesc.first + newDesc.second.size));
 
                 chunks.erase(lastChunkBase);
@@ -377,7 +379,7 @@ namespace skyline::kernel {
         if (!addressSpace.contains(addr)) [[unlikely]]
             return std::nullopt;
 
-        auto chunkBase = chunks.lower_bound(addr);
+        auto chunkBase{chunks.lower_bound(addr)};
         if (addr < chunkBase->first)
             --chunkBase;
 
diff --git a/app/src/main/cpp/skyline/kernel/memory.h b/app/src/main/cpp/skyline/kernel/memory.h
index e7e4feba..37d072ba 100644
--- a/app/src/main/cpp/skyline/kernel/memory.h
+++ b/app/src/main/cpp/skyline/kernel/memory.h
@@ -63,7 +63,9 @@ namespace skyline {
          * @url https://switchbrew.org/wiki/SVC#MemoryAttribute
          */
         union MemoryAttribute {
-
+            /**
+             * @brief Initializes all atrributes to false
+             */
             constexpr MemoryAttribute() : value{} {}
 
             constexpr explicit MemoryAttribute(u8 value) : value{value} {}
@@ -259,7 +261,7 @@ namespace skyline {
 
             /**
              * @brief Mirrors a page-aligned mapping in the guest address space to the host address space
-             * @return A span to the host address space mirror mapped as RWX, unmapping it is the responsibility of the caller
+             * @return A span to the host address space mirror mapped as RW, unmapping it is the responsibility of the caller
              * @note The supplied mapping **must** be page-aligned and inside the guest address space
              */
             span<u8> CreateMirror(span<u8> mapping);
@@ -267,7 +269,7 @@ namespace skyline {
             /**
              * @brief Mirrors multiple page-aligned mapping in the guest address space to the host address space
              * @param totalSize The total size of all the regions to be mirrored combined
-             * @return A span to the host address space mirror mapped as RWX, unmapping it is the responsibility of the caller
+             * @return A span to the host address space mirror mapped as RW, unmapping it is the responsibility of the caller
              * @note The supplied mapping **must** be page-aligned and inside the guest address space
              * @note If a single mapping is mirrored, it is recommended to use CreateMirror instead
              */
@@ -294,7 +296,7 @@ namespace skyline {
              */
             std::optional<std::pair<u8 *, ChunkDescriptor>> GetChunk(u8 *addr);
 
-            // Various mapping functions for use by the guest
+            // Various mapping functions for use by the guest, argument validity must be checked by the caller
             void MapCodeMemory(span<u8> memory, memory::Permission permission);
 
             void MapMutableCodeMemory(span<u8> memory);
@@ -322,8 +324,16 @@ namespace skyline {
              */
             void FreeMemory(span<u8> memory);
 
+            /**
+             * Implements the memory manager side functionality of svcMapMemory
+             * @note Argument validity must be checked by the caller
+             */
             void SvcMapMemory(span<u8> source, span<u8> destination);
 
+            /**
+             * Implements the memory manager side functionality of svcUnmapMemory
+             * @note Argument validity must be checked by the caller
+             */
             void SvcUnmapMemory(span<u8> source, span<u8> destination);
 
             /**