formatting and documentation

6 files changed, 55 insertions, 9 deletions

diff --git a/include/arch/vmem.h b/include/arch/vmem.h
index 238b12a..8f94e07 100644
--- a/include/arch/vmem.h
+++ b/include/arch/vmem.h
@@ -140,6 +140,14 @@ struct vmem *init_vmem(void *fdt);
 vm_t setup_kernel_io(struct vmem *b, vm_t paddr);
 #endif
 
+/**
+ * Create a direct mapping, with 1:1 physical addresses in one half of the
+ * address space and the kernel address space in the other.
+ * Called at boot, not allowed to allocate memory.
+ *
+ * @return The vmem node used to build the address space. Probably statically
+ * allocated.
+ */
 struct vmem *direct_mapping();
 
 /**
@@ -173,7 +181,19 @@ stat_t destroy_vmem(struct vmem *b);
  */
 void clone_uvmem(struct vmem * restrict r, struct vmem * restrict b);
 
-__noreturn void to_kernelspace(void *fdt, uintptr_t load_addr,
-                               struct vmem *direct_mapping, pm_t ram_base,
+/**
+ * Jump into kernelspace from a physical address space.
+ * Really only called by main() during boot so the parameters are kind of weird.
+ *
+ * @param fdt Flattened devicetree.
+ * @param load_addr Address where kernel was loaded to.
+ * @param direct_mapping Direct mapping vmem.
+ * @param ram_base Physical base address of ram.
+ * @param dmap \ref VM_DMAP.
+ */
+__noreturn void to_kernelspace(void *fdt,
+                               uintptr_t load_addr,
+                               struct vmem *direct_mapping,
+                               pm_t ram_base,
                                pm_t dmap);
 #endif /* KMI_ARCH_PAGES_H */
diff --git a/include/kmi/initrd.h b/include/kmi/initrd.h
index 58fafd5..87d76ab 100644
--- a/include/kmi/initrd.h
+++ b/include/kmi/initrd.h
@@ -45,6 +45,12 @@ pm_t get_initrdtop(const void *fdt);
  */
 pm_t get_initrdbase(const void *fdt);
 
+/**
+ * Get size of initrd in bytes.
+ *
+ * @param fdt Global FDT pointer.
+ * @return Size of \c initrd.
+ */
 size_t get_initrdsize(const void *fdt);
 
 /**
diff --git a/include/kmi/mem.h b/include/kmi/mem.h
index ec8d2ea..97a85bf 100644
--- a/include/kmi/mem.h
+++ b/include/kmi/mem.h
@@ -204,14 +204,11 @@ extern enum mm_order __mm_max_order;
 enum mm_order nearest_order(size_t size);
 
 /**
- * Initialize memory subsystem data. Populates __mm_* with data given.
+ * Initialize memory subsystem data.
  *
- * @param max_order Maximum order the current system supports.
- * @param shifts Offsets to start of each memory order in address.
- * @param page_shift Width in bits of base page size.
- * \todo Should likely also be stat_t?
+ * @param fdt Pointer to flattened device tree.
  */
-void init_mem(void *mem);
+void init_mem(void *fdt);
 
 /**
  * Set RAM base address for global access.
@@ -221,6 +218,7 @@ void init_mem(void *mem);
  */
 void set_ram_base(pm_t base);
 
+/** @param size Set RAM size. */
 void set_ram_size(size_t size);
 
 /**
@@ -231,9 +229,15 @@ void set_ram_size(size_t size);
  */
 pm_t get_ram_base();
 
+/**
+ * Get RAM size.
+ * Assumes \ref set_ram_size() has been called beforehand.
+ * Does not take into account disjoint RAM regions.
+ *
+ * @return RAM size.
+ */
 size_t get_ram_size();
 
-
 /** Base page size. */
 #define BASE_PAGE_SIZE (order_size(BASE_PAGE))
 
diff --git a/include/kmi/pmem.h b/include/kmi/pmem.h
index 96a4447..966f269 100644
--- a/include/kmi/pmem.h
+++ b/include/kmi/pmem.h
@@ -67,6 +67,8 @@ size_t probe_pmap(pm_t ram_base, size_t ram_size, pm_t cont);
  * Initialize physical memory subsystem.
  *
  * @param fdt Global FDT pointer.
+ * @param load_addr Where kernel was loaded to. Important for making sure that
+ * nothing gets accidentally overwritten.
  */
 void init_pmem(void *fdt, uintptr_t load_addr);
 
diff --git a/include/kmi/proc.h b/include/kmi/proc.h
index 4b8807f..d8692b1 100644
--- a/include/kmi/proc.h
+++ b/include/kmi/proc.h
@@ -29,6 +29,8 @@ stat_t prepare_proc(struct tcb *t, vm_t bin, vm_t interp);
  * Initialize process handling subsystem and setup \c init program.
  *
  * @param fdt Global FDT pointer.
+ * @param proc_fdt Where in memory the FDT was mapped.
+ * @param proc_initrd Where in memory the initrd was mapped.
  * @return \ref ERR_OOMEM when out of memory, \ref ERR_INVAL if loading \c init
  * failed, \ref OK otherwise.
  */
diff --git a/include/kmi/vmem.h b/include/kmi/vmem.h
index 3205e00..6335959 100644
--- a/include/kmi/vmem.h
+++ b/include/kmi/vmem.h
@@ -131,6 +131,18 @@ stat_t init_uvmem(struct tcb *r, vm_t base, vm_t top);
  */
 stat_t destroy_uvmem(struct tcb *r);
 
+/**
+ * Map a fixed physical region (within kernelspace) to somewhere in virtual
+ * memory.
+ *
+ * @param r Thread where memory should be mapped.
+ * @param base Physical base address to map.
+ * @param size Size of region to map.
+ * @param flags Flags to use for mapping.
+ * @return Address of mapping in virtual memory. Though note that it points to
+ * the start of \p base, not necessarily the start of the allocation.
+ * If this should be freed, remember to align down to the base page size.
+ */
 vm_t map_fixed_mem(struct tcb *r, pm_t base, size_t size, vmflags_t flags);
 
 /**