6 files changed, 386 insertions, 10 deletions

diff --git a/include/apos/initrd.h b/include/apos/initrd.h
index d38e669..3a4f3c5 100644
--- a/include/apos/initrd.h
+++ b/include/apos/initrd.h
@@ -42,4 +42,13 @@ pm_t get_initrdtop(const void *fdt);
  */
 pm_t get_initrdbase(const void *fdt);
 
+/**
+ * Move \c init program to some other region in memory.
+ *
+ * @param fdt Global FDT pointer.
+ * @param target Where to move to.
+ * @return OK on success.
+ */
+stat_t move_init(const void *fdt, void *target);
+
 #endif /* APOS_INITRD_H */
diff --git a/include/apos/pmem.h b/include/apos/pmem.h
index 0b11555..03f4f87 100644
--- a/include/apos/pmem.h
+++ b/include/apos/pmem.h
@@ -10,14 +10,61 @@
 #include <apos/types.h>
 #include <arch/pmem.h>
 
-void update_pmap(pm_t offset);
+/**
+ * Free physical page.
+ *
+ * @param order Order of page to free.
+ * @param paddr Physical address of page.
+ */
 void free_page(enum mm_order order, pm_t paddr);
+
+/**
+ * Mark page used.
+ *
+ * @param order Order of page to mark.
+ * @param paddr Physical address of page.
+ */
 void mark_used(enum mm_order order, pm_t paddr);
+
+/**
+ * Allocate physical page.
+ * Allows the user to specify a hint as to which address to start looking for.
+ * Useful for allocating many pages for one virtual allocation, for example, and
+ * allows us to skip already checked pages when allocating a second page.
+ *
+ * @param order Order of page to allocate.
+ * @param offset Hint as to which address to start looking from.
+ * @return pm_t Physical address of page when succesful, else \c NULL.
+ */
 pm_t alloc_page(enum mm_order order, pm_t offset);
 
+/**
+ * Populate physical RAM usage map.
+ * In theory we could easily implement NUMA nodes by just using different orders
+ * of usage maps, but for now we assume all RAM is contiguous.
+ *
+ * @param ram_base Base physical address of RAM.
+ * @param ram_size Size of phsyical RAM.
+ * @param cont Physical address where to place the map.
+ * @return Size of physical map. Check that is matches with \ref probe_pmap().
+ */
 pm_t populate_pmap(pm_t ram_base, size_t ram_size, pm_t cont);
+
+/**
+ * Probe size of RAM usage map.
+ *
+ * @param ram_base Base physical address of RAM.
+ * @param ram_size Size of physical RAM.
+ * @return Size of physical map. Check that it matches with \ref
+ * populate_pmap().
+ */
 pm_t probe_pmap(pm_t ram_base, size_t ram_size);
 
+/**
+ * Initialize physical memory subsystem.
+ *
+ * @param fdt Global FDT pointer.
+ */
 void init_pmem(void *fdt);
 
 #endif /* APOS_PMEM_H */
diff --git a/include/apos/power.h b/include/apos/power.h
index 640f056..ed7e29c 100644
--- a/include/apos/power.h
+++ b/include/apos/power.h
@@ -10,7 +10,26 @@
 #include <apos/types.h>
 #include <apos/attrs.h>
 
-enum poweroff_type { SHUTDOWN, COLD_REBOOT, WARM_REBOOT };
+/** Types of powering off. Still unclear what difference there is between warm
+ * and cold reboot. */
+enum poweroff_type {
+	/** Shut down. */
+	SHUTDOWN,
+
+	/** Cold or complete reboot. */
+	COLD_REBOOT,
+
+	/** Warm or partial reboot. */
+	WARM_REBOOT
+};
+
+/**
+ * Power off the system.
+ *
+ * @param type Type of powering off. \see poweroff_type.
+ * @return Nothing on success (system shuts down), \ref ERR_INVAL on invalid
+ * poweroff type or ERR_MISC if studown was not succesful.
+ */
 stat_t poweroff(enum poweroff_type type);
 
 #endif
diff --git a/include/apos/proc.h b/include/apos/proc.h
index 182ae16..8eaa647 100644
--- a/include/apos/proc.h
+++ b/include/apos/proc.h
@@ -10,7 +10,25 @@
 #include <apos/tcb.h>
 #include <apos/vmem.h>
 
+/**
+ * Set up binary. Currently only supports ELF, not sure if other formats should
+ * be supported.
+ *
+ * @param t Thread space to set up process in.
+ * @param bin Address of binary to load.
+ * @param interp Optional interpreter, mainly for PIE ELF binaries.
+ * @return \ref OK on success, \ref ERR_INVAL if loading binary failed.
+ * @todo Handle out of memory better?
+ */
 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.
+ * @return \ref ERR_OOMEM when out of memory, \ref ERR_INVAL if loading \c init
+ * failed, \ref OK otherwise.
+ */
 stat_t init_proc(void *fdt);
 
 #endif /* APOS_PROC_H */
diff --git a/include/apos/sp_tree.h b/include/apos/sp_tree.h
index 22b67cf..a5fa2f8 100644
--- a/include/apos/sp_tree.h
+++ b/include/apos/sp_tree.h
@@ -8,34 +8,146 @@
 
 #include <apos/types.h>
 
+/**
+ * Get root of tree from \ref sp_root.
+ *
+ * @param r Instance of \ref sp_root.
+ * @return Actual root of tree.
+ */
 #define sp_root(r) ((r)->sp_r)
+
+/**
+ * Get left node.
+ *
+ * @param n Node to read.
+ * @return Left node of read node.
+ * @see sp_right().
+ */
 #define sp_left(n) ((n)->left)
+
+/**
+ * Get right node.
+ *
+ * @param n Node to read.
+ * @return Right node of read node.
+ * @see sp_left().
+ */
 #define sp_right(n) ((n)->right)
+
+/**
+ * Get parent of right node.
+ * In most situations should point back towards the node it started from, but
+ * when in the middle of updating the tree it might temporarily point somewhere else.
+ *
+ * @param n Node to read.
+ * @return Parent of right node of read node.
+ * @see sp_lparen().
+ */
 #define sp_rparen(n) (sp_right(n)->parent)
+
+/**
+ * Get parent of left node.
+ *
+ * @param n Node to read.
+ * @return Parent of left node of read node.
+ * @see sp_rparen().
+ */
 #define sp_lparen(n) (sp_left(n)->parent)
+
+/**
+ * Get parent of node.
+ *
+ * @param n Node to read.
+ * @return Parent of read node.
+ */
 #define sp_paren(n) ((n)->parent)
+
+/**
+ * Get grandparent (parent of parent) of node.
+ *
+ * @param n Node to read.
+ * @return Grandparent of read node.
+ * @see sp_has_gparen().
+ */
 #define sp_gparen(n) ((n)->parent->parent)
+
+/** Check if node has grandparent.
+ *
+ * @param n Node to read.
+ * @return Non-zero if node has grandparent, \c 0 otherwise.
+ * @see sp_gparen().
+ */
 #define sp_has_gparen(n) (sp_paren(n) && sp_gparen(n))
 
+/** Tree node.
+ * Embed this structure in structures you want to build a tree of.
+ * \see common/mem_region.c, for example.
+ */
 struct sp_node {
+	/** Hint. Approximate maximum tree height up to the current node. */
 	int_fast16_t hint;
+
+	/** Lefthand node. */
 	struct sp_node *left;
+
+	/** Righthand node. */
 	struct sp_node *right;
+
+	/** Parent node. Technically speaking not necessary, but in this case I
+	 * went with time over space. */
 	struct sp_node *parent;
 };
 
+/** Convenience structure for trees. */
 struct sp_root {
+	/** Pointer to actual root of tree. */
 	struct sp_node *sp_r;
 };
 
-enum sp_dir { LEFT, RIGHT };
+/** Which side of the parent node a new node should be inserted to. */
+enum sp_dir {
+	/** Left side. */
+	LEFT,
+
+	/** Right side. */
+	RIGHT
+};
 
+/**
+ * Get first, leftmost node under specified node.
+ *
+ * @param n Node to start with.
+ * @return Leftmost node under \c n, or \c n if there are none.
+ */
 struct sp_node *sp_first(struct sp_node *n);
+
+/**
+ * Get last, rightmost node under specified node.
+ *
+ * @param n Node to start with.
+ * @return Rightmost node under \c n, or \c n if there are none.
+ */
 struct sp_node *sp_last(struct sp_node *n);
 
+/**
+ * Insert new node into tree.
+ * Does not allocate any memory.
+ *
+ * @param root Root of tree.
+ * @param p Parent of new node.
+ * @param n New node.
+ * @param d Which side of the parent node the new node should be on.
+ */
 void sp_insert(struct sp_node **root, struct sp_node *p, struct sp_node *n,
                enum sp_dir d);
 
+/**
+ * Remove node from tree.
+ * Does not free any memory.
+ *
+ * @param root Root of tree.
+ * @param n Node to remove.
+ */
 void sp_remove(struct sp_node **root, struct sp_node *n);
 
 #endif /* SP_TREE_H */
diff --git a/include/apos/string.h b/include/apos/string.h
index e220800..62a31bf 100644
--- a/include/apos/string.h
+++ b/include/apos/string.h
@@ -11,34 +11,205 @@
 
 /* follow C library functions, drop location and error functions */
 
-char *strcpy(char *dst, const char *src);
-char *strncpy(char *dst, const char *src, size_t num);
+/**
+ * Copy \c NULL -terminated string.
+ * \c dst may not overlap \c src.
+ *
+ * @param dst Destination of copy.
+ * @param src Source of copy.
+ * @return \c dst.
+ */
+char *strcpy(char * restrict dst, const char * restrict src);
+
+/**
+ * Copy \c NULL -terminated string, or first \c num characters.
+ * \c dst may not overlap \c src.
+ *
+ * @param dst Destination of copy.
+ * @param src Source of copy.
+ * @param num Maximum number of bytes to copy.
+ * @return \c dst.
+ */
+char *strncpy(char * restrict dst, const char * restrict src, size_t num);
+
+/**
+ * Concatenate \c NULL -terminated strings, placing \c src after \c dst.
+ * \c dst may not overlap \c src.
+ *
+ * @param dst Destination of concatenation.
+ * @param src String to append to \c dst.
+ * @return \c dst.
+ */
+char *strcat(char * restrict dst, const char * restrict src);
 
-char *strcat(char *dst, const char *src);
-char *strncat(char *dst, const char *src, size_t num);
+/**
+ * Concatenate \c NULL -terminated strings, max \c num characters, placing \c
+ * src after \c dst.
+ * \c dst may not overlap \c src.
+ *
+ * @param dst Destination of concatenation.
+ * @param src String to append to \c dst.
+ * @param num Max number of characters to concatenate.
+ * @return \c dst.
+ */
+char *strncat(char * restrict dst, const char * restrict src, size_t num);
 
+/**
+ * Compare two \c NULL -terminated strings.
+ *
+ * @param str1 First string to compare.
+ * @param str2 Second string to compare.
+ * @return \c 0 if strings are equal, else \code str1[i] - str2[i] \endcode for
+ * first differing character.
+ */
 int strcmp(const char *str1, const char *str2);
+
+/**
+ * Compare two \c NULL -terminated strings, max \c num characters.
+ *
+ * @param str1 First string to compare.
+ * @param str2 Second string to compare.
+ * @param num Maximum number of characters to compare.
+ * @return \c 0 if strings are equal, else \code str[i] - str2[i] \endcode for
+ * first differint character.
+ */
 int strncmp(const char *str1, const char *str2, size_t num);
 
+/**
+ * Find first character occurence of \c chr in \c str.
+ *
+ * @param str String to look in.
+ * @param chr Character to look for.
+ * @return Pointer to first \c chr in \c str, else \c 0.
+ */
 char *strchr(const char *str, int chr);
-char *strtok(char *str, const char *delims);
+
+/**
+ * Tokenize string at delimiters. Each stop character is replaced with a \c
+ * NULL. Each following call after the initial found should be a \c NULL. Note
+ * that this kernel's implementation is not thread safe.
+ *
+ * @param str String to look in.
+ * @param delims String of characters to stop on.
+ * @return Start of found token, \c NULL otherwise.
+ */
+char *strtok(char * restrict str, const char * restrict delims);
+
+/**
+ * Find first occurence of \c str2 in \c str1.
+ *
+ * @param str1 String to look in.
+ * @param str2 String to look for.
+ * @return Pointer to start of first occurence, \c NULL otherwise.
+ */
 char *strstr(const char *str1, const char *str2);
 
+/**
+ * Find last occurence of \c chr in \c str.
+ *
+ * @param str String to look in.
+ * @param chr Character to look for.
+ * @return Pointer to last occurence.
+ */
 char *strrchr(const char *str, int chr);
+
+/**
+ * Find first occurence in \c str1 of any of characters in \c str2.
+ *
+ * @param str1 String to look in.
+ * @param str2 String of characters to look for.
+ * @return Pointer to first occurence.
+ */
 char *strpbrk(const char *str1, const char *str2);
 
+/**
+ * Get span of characters in \c str2 in \c str1.
+ *
+ * @param str1 String to look in.
+ * @param str2 String of characters to look for.
+ * @return Number of characters at start of \c str1 that are also in \c str2.
+ */
 size_t strspn(const char *str1, const char *str2);
+
+/**
+ * Get span of characters not in \c str2 in \c str1.
+ *
+ * @param str1 String to look in.
+ * @param str2 String of characters to look out for.
+ * @return Number of characters at start of \c str1 that are not in \c str2.
+ */
 size_t strcspn(const char *str1, const char *str2);
 
+/**
+ * Length of \c NULL-terminated string.
+ *
+ * @param str String.
+ * @return Length of \c str.
+ */
 size_t strlen(const char *str);
-/* only addition on top of libc */
+/**
+ * Length of \c NULL-terminated string, max \c num.
+ * Only addition on top of functions found in libc.
+ *
+ * @param str String.
+ * @param num Max number of characters to count.
+ * @return Length of \c str or \c num.
+ */
 size_t strnlen(const char *str, size_t num);
 
+/**
+ * Initialize memory to some value.
+ *
+ * @param ptr Pointer to memory to initialize.
+ * @param value Value to initialize to. \note Will be truncated to byte.
+ * @param num Number of bytes to initialize.
+ * @return \c ptr.
+ */
 void *memset(void *ptr, int value, size_t num);
+
+/**
+ * Look for value in memory.
+ *
+ * @param ptr Pointer to memory to look in.
+ * @param val Value to look for. \note Will be truncated to byte.
+ * @param num Number of bytes to look.
+ * @return Pointer to first occurence of \c val.
+ */
 void *memchr(const void *ptr, int val, size_t num);
-void *memcpy(void *dst, const void *src, size_t num);
+
+/**
+ * Copy memory byte for byte.
+ * \c dst may not overlap \c src.
+ *
+ * @param dst Destination of copy.
+ * @param src Source of copy.
+ * @param num Number of bytes to copy.
+ * @return \c dst.
+ */
+void *memcpy(void * restrict dst, const void * restrict src, size_t num);
+
+/**
+ * Move memory byte by byte.
+ * \note Essentially identical to \ref memcpy(), but the memory regions may
+ * overlap.
+ *
+ * @param dst Destination of move.
+ * @param src Source of move.
+ * @param num Number of bytes to move.
+ * @return \c dst.
+ */
 void *memmove(void *dst, const void *src, size_t num);
 
+/**
+ * Compare memory byte by byte.
+ *
+ * @param ptr1 Memory to compare 1.
+ * @param ptr2 Memory to compare 2.
+ * @param num Bytes to compare.
+ * @return \c 0 when equal, else
+ * \code (unsigned char *)ptr1[i] - (unsigned char *)ptr2[i] \endcode
+ * at first differing byte.
+ */
 int memcmp(const void *ptr1, const void *ptr2, size_t num);
 
 /* Honorable mentions: