24 files changed, 181 insertions, 0 deletions
diff --git a/common/bits.c b/common/bits.c
index 698c082..dde39f7 100644
--- a/common/bits.c
+++ b/common/bits.c
@@ -1,3 +1,8 @@
+/**
+ * @file bits.c
+ * Bit manipulation helper implementations, currently just byte swaps.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 #include <apos/bits.h>
diff --git a/common/debug.c b/common/debug.c
index a008a52..15f71dc 100644
--- a/common/debug.c
+++ b/common/debug.c
@@ -1,3 +1,9 @@
+/**
+ * @file debug.c
+ * Handle printing to serial. Note that the serial drivers are only included
+ * when running a debug build to save space in release mode.
+ */
+
 #include <apos/types.h>
 #include <apos/debug.h>
 #include <apos/bits.h>
diff --git a/common/dmem.c b/common/dmem.c
index a116547..1d5608c 100644
--- a/common/dmem.c
+++ b/common/dmem.c
@@ -1,3 +1,10 @@
+/**
+ * @file dmem.c
+ * Handle device memory, i.e. anything outside the physical RAM.
+ *
+ * \todo Handle NUMA.
+ */
+
 #include <apos/dmem.h>
 
 static struct mem_region_root pre_ram = { 0 };
diff --git a/common/elf.c b/common/elf.c
index 9af4f08..e60b21f 100644
--- a/common/elf.c
+++ b/common/elf.c
@@ -1,3 +1,8 @@
+/**
+ * @file elf.c
+ * Handle elf executables, set up requested memory mappings etc.
+ */
+
 #include <apos/elf.h>
 #include <apos/vmem.h>
 #include <apos/bits.h>
diff --git a/common/fdt.c b/common/fdt.c
index 56b9d04..a6368dd 100644
--- a/common/fdt.c
+++ b/common/fdt.c
@@ -1,3 +1,8 @@
+/**
+ * @file fdt.c
+ * Helper functions for handling the global FDT.
+ */
+
 #include <libfdt.h>
 
 struct cell_info get_cellinfo(const void *fdt, const int offset)
diff --git a/common/initrd.c b/common/initrd.c
index 28ddaec..e3e6d94 100644
--- a/common/initrd.c
+++ b/common/initrd.c
@@ -1,3 +1,8 @@
+/**
+ * @file initrd.c
+ * Handle initrd, implement cpio with newc format.
+ */
+
 #include <apos/initrd.h>
 #include <apos/vmem.h>
 #include <apos/string.h>
diff --git a/common/main.c b/common/main.c
index b2928be..9585f3d 100644
--- a/common/main.c
+++ b/common/main.c
@@ -1,3 +1,8 @@
+/**
+ * @file main.c
+ * Entry point for actual kernel setup.
+ */
+
 #include <apos/mem_nodes.h>
 #include <apos/timer.h>
 #include <apos/attrs.h>
diff --git a/common/mem.c b/common/mem.c
index a824c26..51a51af 100644
--- a/common/mem.c
+++ b/common/mem.c
@@ -1,3 +1,8 @@
+/**
+ * @file mem.c
+ * Generic memory handling, used both by physical and virtual memory.
+ */
+
 #include <apos/types.h>
 #include <apos/mem.h>
 #include <apos/vmem.h>
diff --git a/common/mem_nodes.c b/common/mem_nodes.c
index 392fa3e..d4f7d2e 100644
--- a/common/mem_nodes.c
+++ b/common/mem_nodes.c
@@ -1,3 +1,12 @@
+/**
+ * @file mem_nodes.c
+ * Memory node wrapper around the node subsystem, used by \ref
+ * common/mem_regions.c.
+ *
+ * Each region of memory is allocated through a \ref mem_region node, which is
+ * allocated through the node subsystem.
+ */
+
 #include <apos/vmem.h>
 #include <apos/pmem.h>
 #include <apos/mem.h>
diff --git a/common/mem_regions.c b/common/mem_regions.c
index e6c4644..e1eff0d 100644
--- a/common/mem_regions.c
+++ b/common/mem_regions.c
@@ -1,3 +1,9 @@
+/**
+ * @file mem_regions.c
+ * Memory region handling, used by both device memory and user virtual memory
+ * subsystems.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/mem_nodes.h>
 #include <apos/pmem.h>
diff --git a/common/nodes.c b/common/nodes.c
index 0c6f7ce..30d3cfb 100644
--- a/common/nodes.c
+++ b/common/nodes.c
@@ -1,3 +1,28 @@
+/**
+ * @file nodes.c
+ * The node subsystem. Each client has to initialize their own node system,
+ * after which they can request nodes of a size specified at init.
+ *
+ * Node allocation is implemented through a similar system used by jemalloc
+ * (https://github.com/jemalloc/jemalloc), but instead of having a number of
+ * different sized buckets there is only the one size specified by the user.
+ * This cuts down on complexity and improves performance, at a somewhat major
+ * flexibility cost. Still, this kernel generally only allocates nodes of the
+ * same size again and again, and this approach seems sensible.
+ *
+ *
+ * Quick overview of the allocator, all nodes live in memory pages. Each memory
+ * page has a small header at the front, with some metadata about number of free
+ * and used node slots. When a memory page is filled, a new one is allocated by
+ * the physical memory subsystem and the pages are linked together in a common
+ * list. At the same time, a second linked list is maintained which maintains
+ * which pages have empty slots. When a node is freed, the page it belonged to
+ * is added to the free list (if it didn't already exist there) and when a new
+ * node is requested, the free list is looked through first.
+ *
+ * \todo More in-depth documentation about the node algorithm.
+ */
+
 #include <apos/mem.h>
 #include <apos/pmem.h>
 #include <apos/bits.h>
diff --git a/common/pmem.c b/common/pmem.c
index e3e5e5c..5af17ac 100644
--- a/common/pmem.c
+++ b/common/pmem.c
@@ -1,3 +1,25 @@
+/**
+ * @file pmem.c
+ * Physical memory subsystem. Allocates physical memory pages, with support for
+ * different ordered pages, depending on the underlying architecture.
+ *
+ * Quick overview of the physical memory subsystem: Somewhere in RAM there
+ * exists a number of buckets, each with an n-tree representing different order
+ * pages and their status (used/free). When a lower-order memory page (i.e.
+ * smaller) is allocated, it blocks allocation of higher-order pages (i.e.
+ * larger) whose addresses would overlap. This is avoided by marking all
+ * higher-order pages as used in their respective buckets.
+ *
+ * This approach is reasonably efficient at handling the different possible page
+ * sizes, but requires that the caller maintains some data about page sizes, as
+ * the algorithm doesn't keep any of that information. Allocating a region of a
+ * certain page order and freeing it as another could easily be a
+ * source of difficult to track bugs.
+ *
+ * \todo More in depth documentation about the physical memory algorithms,
+ * unfortunately it is quite difficult to follow.
+ */
+
 #include <apos/mem_nodes.h>
 #include <apos/pmem.h>
 #include <apos/dmem.h>
diff --git a/common/proc.c b/common/proc.c
index f4c0899..e88d37d 100644
--- a/common/proc.c
+++ b/common/proc.c
@@ -1,3 +1,8 @@
+/**
+ * @file proc.c
+ * Process handling, might be merged into \ref common/tcb.c.
+ */
+
 #include <apos/elf.h>
 #include <apos/proc.h>
 #include <apos/conf.h>
diff --git a/common/sp_tree.c b/common/sp_tree.c
index 5097757..9003f40 100644
--- a/common/sp_tree.c
+++ b/common/sp_tree.c
@@ -1,3 +1,13 @@
+/**
+ * @file sp_tree.c
+ * Implementation of my sp_trees. An sp_tree is a mix of rb-trees and avl-trees,
+ * with slightly faster insertion but worse tree depth on average.
+ *
+ * See https://github.com/Kimplul/sptree
+ *
+ * \todo Document sp_tree algorithm better.
+ */
+
 #include <apos/sp_tree.h>
 
 static void __sp_turn_left(struct sp_node *n)
diff --git a/common/string.c b/common/string.c
index 15416af..6a56698 100644
--- a/common/string.c
+++ b/common/string.c
@@ -1,3 +1,8 @@
+/**
+ * @file string.c
+ * Implementations of some string.h stdlib functions.
+ */
+
 #include <apos/string.h>
 #include <apos/types.h>
 #include <apos/attrs.h>
diff --git a/common/tcb.c b/common/tcb.c
index 1e8c648..6904208 100644
--- a/common/tcb.c
+++ b/common/tcb.c
@@ -1,3 +1,8 @@
+/**
+ * @file tcb.c
+ * Thread control block handling implementation.
+ */
+
 #include <apos/tcb.h>
 #include <arch/cpu.h>
 #include <apos/mem.h>
diff --git a/common/timer.c b/common/timer.c
index 0442c44..0a11dc8 100644
--- a/common/timer.c
+++ b/common/timer.c
@@ -1,3 +1,17 @@
+/**
+ * @file timer.c
+ * Timer handling implementation. Currently we only expect an architecture to
+ * support a single timer per core.
+ *
+ * By keeping all timers in a binary search
+ * tree ordered by time, we can just set the single timer to interrupt us when
+ * the next timer is due and with thread info call the thread that set the
+ * timer. From what I can tell, this is largely what Linux does.
+ *
+ * \todo Figure out if there are any advantages to having multiple concurrent
+ * timers.
+ */
+
 #include <apos/sp_tree.h>
 #include <apos/string.h>
 #include <apos/nodes.h>
diff --git a/common/uapi/conf.c b/common/uapi/conf.c
index 25677ef..a30333b 100644
--- a/common/uapi/conf.c
+++ b/common/uapi/conf.c
@@ -1,3 +1,10 @@
+/**
+ * @file conf.c
+ * Runtime configuration sycall implementations.
+ *
+ * At the moment there are not runtime configuration parameters.
+ */
+
 #include <apos/power.h>
 #include <apos/sizes.h>
 #include <apos/uapi.h>
diff --git a/common/uapi/dispatch.c b/common/uapi/dispatch.c
index 5e2e788..1e72e77 100644
--- a/common/uapi/dispatch.c
+++ b/common/uapi/dispatch.c
@@ -1,3 +1,8 @@
+/**
+ * @file dispatch.c
+ * Syscall dispatch.
+ */
+
 #include <apos/uapi.h>
 
 static const sys_t syscall_table[] = {
diff --git a/common/uapi/ipc.c b/common/uapi/ipc.c
index 0d2d287..d3cbcd7 100644
--- a/common/uapi/ipc.c
+++ b/common/uapi/ipc.c
@@ -1,3 +1,8 @@
+/**
+ * @file ipc.c
+ * Interprocess communication syscall implementations.
+ */
+
 #include <apos/uapi.h>
 #include <apos/tcb.h>
 
diff --git a/common/uapi/mem.c b/common/uapi/mem.c
index 7526152..83d7289 100644
--- a/common/uapi/mem.c
+++ b/common/uapi/mem.c
@@ -1,3 +1,8 @@
+/**
+ * @file mem.c
+ * Memory handling syscall implementations.
+ */
+
 #include <apos/uapi.h>
 #include <apos/utils.h>
 #include <apos/vmem.h>
diff --git a/common/uapi/proc.c b/common/uapi/proc.c
index 3ce3bcb..43e825d 100644
--- a/common/uapi/proc.c
+++ b/common/uapi/proc.c
@@ -1,3 +1,8 @@
+/**
+ * @file proc.c
+ * Process/thread handling syscall implementations.
+ */
+
 #include <apos/uapi.h>
 
 SYSCALL_DEFINE0(create)()
diff --git a/common/uapi/timers.c b/common/uapi/timers.c
index 97a1d30..ca2443b 100644
--- a/common/uapi/timers.c
+++ b/common/uapi/timers.c
@@ -1,3 +1,8 @@
+/**
+ * @file timers.c
+ * Timer syscall implementations.
+ */
+
 #include <apos/timer.h>
 #include <apos/uapi.h>
 
diff --git a/common/vmem.c b/common/vmem.c
index 7ea83b1..ae40748 100644
--- a/common/vmem.c
+++ b/common/vmem.c
@@ -1,3 +1,8 @@
+/**
+ * @file vmem.c
+ * Virtual memory handling, mainly userspace virtual memory.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/assert.h>
 #include <apos/debug.h>