formatting and documentation

6 files changed, 78 insertions, 8 deletions

diff --git a/src/main.c b/src/main.c
index 19d52a2..506d7fe 100644
--- a/src/main.c
+++ b/src/main.c
@@ -19,6 +19,10 @@
 #include <arch/smp.h>
 #include <libfdt.h>
 
+/**
+ * @param fdt Flattened devicetree.
+ * @return Base address of RAM. Does not take into account disjoint RAM.
+ */
 static pm_t __fdt_ram_base(void *fdt)
 {
 	int mem_offset = fdt_path_offset(fdt, "/memory");
@@ -28,6 +32,10 @@ static pm_t __fdt_ram_base(void *fdt)
 	return (pm_t)fdt_load_reg_addr(ci, mem_reg, 0);
 }
 
+/**
+ * @param fdt Flattened devicetree.
+ * @return RAM size. Does not take into account disjoint RAM.
+ */
 static pm_t __fdt_ram_size(void *fdt)
 {
 	int mem_offset = fdt_path_offset(fdt, "/memory");
@@ -39,8 +47,17 @@ static pm_t __fdt_ram_size(void *fdt)
 	return (pm_t)fdt_load_reg_size(ci, mem_reg, 0);
 }
 
-void kernel(void *fdt, uintptr_t load_addr, struct vmem *d)
+/**
+ * 'Actual' kernel, runs in kernelspace and does the heavy lifting during
+ * booting.
+ *
+ * @param fdt Flattened device tree.
+ * @param load_addr Where in memory the kernel blob was loaded to.
+ * @param d Direct mapping to use during booting.
+ */
+__noreturn void kernel(void *fdt, uintptr_t load_addr, struct vmem *d)
 {
+	/* we should be in kernelspace, so use the virtual address of our FDT. */
 	fdt = __va(fdt);
 
 	/* dbg uses direct mapping at this point */
@@ -73,11 +90,12 @@ void kernel(void *fdt, uintptr_t load_addr, struct vmem *d)
  * Sets up all kernel subsystems and jumps into \c init program, does not
  * return.
  *
+ * @param hart Hart ID. Technically unused, but makes the signature more fitting
+ * for booting with different systems, like OpenSBI and u-boot.
  * @param fdt Global FDT pointer in physical memory.
- * @param ram_base RAM base.
- * @return Should not.
+ * @param load_addr To which (physical) address in RAM kernel was loaded to.
  */
-void main(unsigned long hart, void *fdt, uintptr_t load_addr)
+__noreturn void main(unsigned long hart, void *fdt, uintptr_t load_addr)
 {
 	/* we have our own ways to get the current hart when we need it, but we
 	 * have to get the function signature right */
diff --git a/src/mem.c b/src/mem.c
index 68d323f..4fb9d5a 100644
--- a/src/mem.c
+++ b/src/mem.c
@@ -22,6 +22,8 @@ enum mm_order __mm_max_order;
  * like __mm_*.
  */
 pm_t ram_base;
+
+/** RAM size. */
 size_t ram_size;
 
 enum mm_order nearest_order(size_t size)
diff --git a/src/pmem.c b/src/pmem.c
index bddefa8..dd10768 100644
--- a/src/pmem.c
+++ b/src/pmem.c
@@ -436,11 +436,23 @@ static void __mark_area_used(pm_t base, pm_t top)
 		mark_used(BASE_PAGE, runner);
 }
 
+/** Helper for keeping track of which memory regions to avoid placing data into. */
 struct avoid_region {
+	/** Base address of region. */
 	pm_t base;
+
+	/** Size of region. */
 	pm_t size;
 };
 
+/**
+ * @param base1
+ * @param size1
+ * @param base2
+ * @param size2
+ * @return \ref true if the memory regions indicated have some overlap,
+ * \ref false otherwise.
+ */
 static bool overlaps(pm_t base1, pm_t size1, pm_t base2, pm_t size2)
 {
 	bool b = base1 >= base2 && base1 < base2 + size2;
@@ -451,7 +463,11 @@ static bool overlaps(pm_t base1, pm_t size1, pm_t base2, pm_t size2)
 /**
  * Mark reserved memory region used, to avoid it getting accidentally allocated.
  *
- * @param fdt Global FDT pointer.
+ * @param ram_base RAM base address in kernelspace.
+ * @param ram_size RAM size.
+ * @param avoid_count How many regions to avoid.
+ * @param avoid Regions to avoid. Should all be in kernelspace, everything
+ * outside RAM is ignored.
  */
 static void __mark_reserved(pm_t ram_base, pm_t ram_size, size_t avoid_count,
                             struct avoid_region avoid[64])
@@ -469,6 +485,15 @@ static void __mark_reserved(pm_t ram_base, pm_t ram_size, size_t avoid_count,
 	}
 }
 
+/**
+ * Figure out what if any regions of RAM are reserved and append them to \p
+ * avoid.
+ *
+ * @param exists How many elements are currently in \p avoid.
+ * @param avoid Array of regions to avoid, must not be sparse.
+ * @param fdt Flattened device tree.
+ * @return Total number of regions avoid.
+ */
 static size_t build_reserved_map(size_t exists, struct avoid_region avoid[64],
                                  void *fdt)
 {
@@ -490,6 +515,19 @@ static size_t build_reserved_map(size_t exists, struct avoid_region avoid[64],
 	return exists;
 }
 
+/**
+ * Selects a fitting base address for a block of memory of size \p size, while
+ * avoiding overwriting anything in \p avoid.
+ * Addresses to be avoided are allowed to be outside of RAM,
+ * for example in ROM, in which case they are just ignored.
+ *
+ * @param ram_base Base address of RAM.
+ * @param ram_size Size of RAM.
+ * @param size Size of block to find.
+ * @param avoid_count How many elements in the \p avoid array.
+ * @param avoid Which memory regions to avoid.
+ * @return A suitable base address, aligned on a word boundary.
+ */
 static pm_t select_base(pm_t ram_base, pm_t ram_size, pm_t size,
                         pm_t avoid_count,
                         struct avoid_region avoid[64])
diff --git a/src/proc.c b/src/proc.c
index f2d418f..61dd125 100644
--- a/src/proc.c
+++ b/src/proc.c
@@ -70,7 +70,7 @@ stat_t init_proc(void *fdt, vm_t *proc_fdt, vm_t *proc_initrd)
 	                             initrd, get_initrdsize(fdt),
 	                             VM_V | VM_R | VM_U);
 
-	info("mapped fdt at %p\n", (void *)*proc_fdt);
-	info("mapped initrd at %p\n", (void *)*proc_initrd);
+	info("mapped fdt at %lx\n", *proc_fdt);
+	info("mapped initrd at %lx\n", *proc_initrd);
 	return OK;
 }
diff --git a/src/string.c b/src/string.c
index 4eaaf68..743fd98 100644
--- a/src/string.c
+++ b/src/string.c
@@ -259,7 +259,7 @@ __weak size_t strnlen(const char *str, size_t num)
 }
 
 #undef memset
-__weak void *memset(void *ptr, int value, size_t num)
+__weak __used void *memset(void *ptr, int value, size_t num)
 {
 	char *p = ptr;
 	char c = value;
diff --git a/src/vmem.c b/src/vmem.c
index d041c80..f1841e4 100644
--- a/src/vmem.c
+++ b/src/vmem.c
@@ -232,6 +232,18 @@ vm_t alloc_fixed_uvmem(struct tcb *t, vm_t start, size_t size, vmflags_t flags)
 	return w;
 }
 
+/**
+ * Helper for \ref map_fixed_mem().
+ * Maps some contiguous bit of physical memory to an allocated virtual memory region.
+ *
+ * @param b Virtual memory to work in.
+ * @param v Start of virtual memory region.
+ * @param p Start of physical memory region.
+ * @param size Size of virtual memory region.
+ * @param flags Flags to use for mappings.
+ * @param status Is written to with the status of this function.
+ * @return The start of the virtual address mapping.
+ */
 static vm_t map_fixed_region(struct vmem *b, vm_t v, pm_t p, size_t size,
                              vmflags_t flags, stat_t *status)
 {