more docs

1 files changed, 97 insertions, 0 deletions

diff --git a/docs/MEMORY.md b/docs/MEMORY.md
index e69de29..d79d5e2 100644
--- a/docs/MEMORY.md
+++ b/docs/MEMORY.md
@@ -0,0 +1,97 @@
+# Memory
+
+Comus (the kernel) is a x86_64 arch kernel using paging (vitural memory).
+
+## Vitural Memory
+
+Vitural memory works by using vitural address instead of direct physical addresses
+when accessing memory. These vitural address are then translated into
+physical addresses using a set of structures called "page tables".
+
+Comus uses for level paging using the following page structures:
+- PML4 (level 4)
+- PDPT (level 3)
+- PD (level 2)
+- PT (level 1)
+
+Read intel / amd manual for more information.
+
+## Memory Layout
+
+|----------------|----------------|
+| Start Address  | Data           |
+|----------------|----------------|
+| 0MB            | BIOS Reserved  |
+| 1MB            | Kernel Start   |
+| 129MB          | Kernel End     |
+| ...            | User Program   |
+| ...            | User Heap      |
+| 0x7fffffffffff | User Stack Top |
+|----------------|----------------|
+
+## Memory Modules
+
+To be able to map physical memory to vitural addresses, the following modules
+are needed (and used).
+
+### Phyiscal Page Allocator
+
+Marks specific physical pages as in used or free to be used. Paging functions
+request phyiscal pages when allocating memory.
+
+Allocator implemented as a bitmap. Bitmap is a list of uint64_t, where each
+page is marged as a single bit
+  - 0 for free
+  - 1 for in use
+
+Which pages the bitmap points to is initalized using the memory map provided
+by multiboot or UEFI.
+
+## Vitural Address Allocator
+
+When attempting to map memory, its important for vitural addresses to not be
+reused multiple times. This allocate gurenteed this doesnt happend for any
+given memory context.
+
+The allocator is implemented a linked list of free / in use nodes (blocks) of
+vitural addresss. At the start is a single node describing the entire vitural
+address space. To mark an address block as inuse, the node is split, marking
+new new block as in use, and the other new nodes next to it as not in use.
+
+### virtaddr_alloc
+If the kernel wants to map memory at any (random) vitural address, the allocator
+will return the first free contigious vitural address it finds.
+
+### virtaddr_take
+If the kernel wants to map a specific vitural address, this allocator will
+either state that its taken (and cannot be used), or state that it can be used
+marking it as in use in the allocator.
+
+## Bootstrap Page Tables
+To successfully identity map the kernel, some memory needs to be allocated
+inside the kernel. This is because only mapped memory can be written to.
+If its not in the kernel, this memory will not be identity mapped, this making
+it inaccessable.
+
+These bootstrap page tables are used for creating the kernel identiy mapping.
+
+## Paging Page Tables (bad name)
+These page tables (mapped by the bootstrap page tables) are used for mapping
+other page table structures to be accessable. These page tables are inside the
+kernel and are this identity mapped, therefore always accessable. They allow
+mapping any address, but again are primarly used for mapping other page tables.
+
+## Paging Functions
+
+The following functions used to be able to map pages
+- map_pages
+  - maps a set of pages at a phys/virt address pair
+- unmap_pages
+  - the reverse of map_pages
+- mem_map_pages_at
+  - allocate physical pages and map them at a vitural address
+  - used for normal allocations
+- mem_map_addr
+  - map a vitural address (or random one if not provided) to a given physical address
+  - used for accessing memory when provided with a physical address
+    - ACPI tables, ramdisk