more docs

3 files changed, 166 insertions, 0 deletions

diff --git a/docs/HEADERS.md b/docs/HEADERS.md
index e69de29..f904006 100644
--- a/docs/HEADERS.md
+++ b/docs/HEADERS.md
@@ -0,0 +1,43 @@
+
+# Headers
+
+## comus
+
+All kernel headers for the `comus` kernel. Each of these headers map directly
+to c files in the kernel source tree besides the following.
+
+### asm.h
+
+Contains inline functions for calling x64/x86 assembly
+
+### error.h
+
+Kernel error codes
+- Success (0)
+- Failure (1)
+- All other codes are specific failures
+
+### keycodes.h
+
+Kernel keycodes used in input.h
+- ps2 driver uses these keycodes when mapping its scancodes
+
+### limits.h
+
+Maximum limists across multiple components of the kernel.
+- max open files
+- max filesystem disks
+- max number of process
+- etc...
+
+## efi.h
+
+Standard UEFI header. Read UEFI specification online for more information.
+
+## elf.h
+
+Standard ELF header. Read ELF specification online for more information.
+
+## lib
+
+Used for kernel c library code stored in `kernel/lib`
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
diff --git a/docs/MODULES.md b/docs/MODULES.md
index cf452ff..31d3eba 100644
--- a/docs/MODULES.md
+++ b/docs/MODULES.md
@@ -107,3 +107,29 @@ Stores loaded process information and scheduler
     - acessed though syscall_queue[SYS_num]
 
 See PCB.md for pcb information.
+
+# syscall.c
+
+Syscall implentation functions for each syscall
+
+See SYSCALLS.md
+
+# term.c
+
+Manages text terminal. All text printed to standard out or err will be printed
+to this terminal.
+
+- contains a terminal buffer for allowing scrolling of the screen
+- manages redrawing the terminal when scrolling or changing terminal handler
+  - vga text mode v.s. gpu framebuffer
+
+# user.c
+
+Loads user ELF binaries into memory and initalizes them into a PCB.
+
+See PCB.md
+
+- `user_load` - load a user process form the filesystem into memory
+- `user_clone` - clones the user process
+- `user_cleanup` - cleans up a user process
+