From b9fa2e1d81c3292a29822243935562c6dccea233 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20Lov=C3=A9n?= <thomasloven@gmail.com>
Date: Mon, 17 Jan 2022 14:38:17 +0100
Subject: [PATCH] Documentation

---
 documentation/3 - memory.md | 27 +++++++++++++++++++++++++++
 src/kernel/memory/kbrk.c    |  4 +---
 2 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 documentation/3 - memory.md

diff --git a/documentation/3 - memory.md b/documentation/3 - memory.md
new file mode 100644
index 0000000..f36ef44
--- /dev/null
+++ b/documentation/3 - memory.md	
@@ -0,0 +1,27 @@
+# Mittos memory management
+
+> - [Mittos64 documentation chapter 9](https://github.com/thomasloven/mittos64/blob/master/doc/9_Memory_Management.md)
+
+## Address translation
+
+The upper half of the virtual memory space is reserved for kernel use - i.e everything above `0xFFFFFF8000000000`.
+
+Since the 64 bit address space is many orders or magnitude larger than any physical memory Mittos is likely to ever encounter, all available memory is mapped into this space in a one-to-one translation.
+
+I.e. physical memory at `0x123000` is mapped into `0xFFFFFF8000123000`. This allows the kernel direct access to any page in memory which simplifies all memory operations. See [XXX] for a more detailed explanation of this approach.
+
+The kernel virtual memory manager contains functions for mapping individual pages in a recursive four level page directory.
+
+The memory area above `0xFFFFFFC000000000` is used for dynamic allocation of memory for the kernel. I.e. `0xFFFFFFC000000000` is the kernel `brk`.
+Furthermore `0xFFFFFFC010000000` is set aside for kernel `mmap` calls to facilitate larger allocations by musl malloc.
+
+## Physical memory management
+Physical memory is handled on a page-by-page basis. I.e. only single page blocks can be allocated or freed. When a page is freed it is put on the top of a stack and a pointer to the next page is written to it. Thus the pages themselves form the stack structure.
+
+On boot this stack is filled by pages from the multiboot memory map with some checks to make sure pages that are used by the kernel or boot data is not freed prematurely.
+
+## Relevant files
+- `src/kernel/memory/memory.c`
+- `src/kernel/include/memory.h`
+- `src/kernel/vmm.c`
+- `src/kernel/pmm.c`
\ No newline at end of file
diff --git a/src/kernel/memory/kbrk.c b/src/kernel/memory/kbrk.c
index c3acd1c..653afb3 100644
--- a/src/kernel/memory/kbrk.c
+++ b/src/kernel/memory/kbrk.c
@@ -10,10 +10,8 @@ long k_brk(long brk, long, long, long, long, long) {
             vmm_set_page(kernel_P4, _brk, pmm_alloc(), PAGE_GLOBAL | PAGE_WRITE | PAGE_PRESENT);
             _brk += PAGE_SIZE;
         }
-        return _brk;
-    } else {
-        return _brk;
     }
+    return _brk;
 }
 
 long k_mmap(long addr, long length, long prot, long flags, long fd, long offset) {