doc/man: Add paging(9) manpage, giving an introduction to paging and the frame map

diff --git a/doc/man/Makefile b/doc/man/Makefile
new file mode 100644 (file)
index 0000000..0790b40
--- /dev/null
+++ b/doc/man/Makefile
@@ -0,0 +1,12 @@
+HTMLFILES = paging.html
+PHONY =
+
+all: $(HTMLFILES)
+
+clean:
+       rm -f $(HTMLFILES)
+
+.PHONY: $(PHONY)
+
+%.html: %.9
+       groff -mandoc -Thtml $< > $@

diff --git a/doc/man/paging.9 b/doc/man/paging.9
new file mode 100644 (file)
index 0000000..5dd25a6
--- /dev/null
+++ b/doc/man/paging.9
@@ -0,0 +1,52 @@
+.TH PAGING 9 2020-08-22 "0.1" "Corax Kernel Documentation"
+
+.SH INTRODUCTION
+The Corax kernel manages physical memory using the architecture's paging mechanism. The paging
+mechanism is used to create virtual address spaces that are used to protect physical memory and
+prevent parts of the system from interfering with eachother. Each such address space is defined by
+a
+.B struct pagedir
+which contains a pointer to the physical page directory, flags that control the behavior of the
+address space, and pointers to data structures that determine the contents of the address space.
+
+.P
+In Corax, there is one pagedir for the kernel, and one pagedir for each process. The pagedir of
+the kernel contains an identity-mapping of the entire physical memory, allowing the kernel to
+access all memory as if paging were disabled. The pagedir of a process, on the other hand, is not
+identity-mapped. In fact, any two pages in a process pagedir may not even be physically adjacent.
+
+.P
+When a new address space is created, the kernel allocates a new
+.B struct pagedir
+on the kernel heap, allocates the physical page directory by getting an unused page frame (a
+physical page) from the frame map, and then maps all memory regions that are necessary for a
+usable address space, such as the kernel's code segment (which is necessary to handle interrupts
+in user mode).
+
+.SH THE FRAME MAP
+
+The Corax kernel keeps track of all memory using a structure called the frame map. The frame map
+is a bitset that tracks the state (available or occupied) of each frame (a 4KB block of physical
+memory) in the system. Each bit corresponds to a specific physical memory address. For example,
+the first bit refers to the frame at address 0x0, the second bit refers to the frame at address
+0x1000, and so on. During initialization of the kernel, the frame map is initialized to all-ones,
+meaning that there are no available frames. The kernel then queries the memory map provided by the
+bootloader to determine which bits may be cleared, allowing them to be used for page frame
+allocations. Finally, the kernel sets all bits of frames that it occupies itself.
+
+.P
+The frame map is located in physical memory right behind the kernel image and occupies only the
+space that is necessary to manage the usable memory of the system. When the kernel attempts to
+allocate a page frame, it can allocate page frames either from the front or from the back of the
+frame map. Frames from the front of the frame map are used exclusively to grow the kernel heap, as
+the kernel's address space is identity-mapped and its heap starts right after the frame map. For
+all other purposes, page frames are allocated from the back of the map.
+
+
+.SH SEE ALSO
+.ad l
+.nh
+.BR corax (9)
+
+.SH AUTHOR
+Matthias Kruk (m@m10k.eu)