continue documentation

3 files changed, 111 insertions, 19 deletions

diff --git a/common/initrd.c b/common/initrd.c
index e3e6d94..2a254f1 100644
--- a/common/initrd.c
+++ b/common/initrd.c
@@ -10,24 +10,58 @@
 #include <apos/attrs.h>
 #include <libfdt.h>
 
-/* GNU cpio, use POSIX 'newc' format */
+/** GNU cpio, POSIX 'newc' format header. */
 struct __packed cpio_header {
+	/** Magic bytes. */
 	char c_magic[6];
+
+	/** File inode. */
 	char c_ino[8];
+
+	/** File type and permissions. */
 	char c_mode[8];
+
+	/** User ID. */
 	char c_uid[8];
+
+	/** Group ID. */
 	char c_gid[8];
+
+	/** Number of links to this file. */
 	char c_nlink[8];
+
+	/** Modification time. */
 	char c_mtime[8];
+
+	/** Size of file. */
 	char c_filesize[8];
+
+	/** Device major. */
 	char c_devmajor[8];
+
+	/** Device minor. */
 	char c_devminor[8];
+
+	/** Block device major. */
 	char c_rdevmajor[8];
+
+	/** Block device minor. */
 	char c_rdevminor[8];
+
+	/** Length of filename. */
 	char c_namesize[8];
+
+	/** CRC check. */
 	char c_check[8];
 };
 
+/**
+ * Get next file in archive.
+ * Does not check for out of bounds.
+ *
+ * @param cp Pointer to current file header.
+ * @return Pointer to next file header.
+ */
 static struct cpio_header *__next_entry(struct cpio_header *cp)
 {
 	size_t blen = align_up(
@@ -37,6 +71,14 @@ static struct cpio_header *__next_entry(struct cpio_header *cp)
 	return (struct cpio_header *)(((char *)cp) + blen + tlen);
 }
 
+/**
+ * Get file with name in archive.
+ *
+ * @param c Pointer to initrd.
+ * @param fname Filename to look for.
+ * @param fname_len Length of filename.
+ * @return Pointer to corresponding file header if found, \c NULL otherwise.
+ */
 static struct cpio_header *__find_file(const char *c, const char *fname,
                                        size_t fname_len)
 {
@@ -44,7 +86,7 @@ static struct cpio_header *__find_file(const char *c, const char *fname,
 	for (; cp; cp = __next_entry(cp)) {
 		size_t namelen = convnum(cp->c_namesize, 8, 16);
 		if (namelen == 0)
-			return 0;
+			return NULL;
 
 		if (namelen < fname_len)
 			continue;
@@ -57,9 +99,15 @@ static struct cpio_header *__find_file(const char *c, const char *fname,
 			return cp;
 	}
 
-	return 0;
+	return NULL;
 }
 
+/** Name of \c init program. */
+static char init_n[] = "init";
+
+/** Length of \c init name. */
+static size_t init_nlen = ARRAY_SIZE(init_n) - 1; /* ignore trailing NULL */
+
 pm_t get_initrdtop(const void *fdt)
 {
 	int chosen_offset = fdt_path_offset(fdt, "/chosen");
@@ -83,8 +131,6 @@ pm_t get_initrdbase(const void *fdt)
 	return (pm_t)__va(fdt_load_int_ptr(ci.addr_cells, initrd_base_ptr));
 }
 
-static char init_n[] = "init";
-static size_t init_nlen = ARRAY_SIZE(init_n) - 1; /* ignore trailing NULL */
 
 size_t get_init_size(const void *fdt)
 {
@@ -101,7 +147,7 @@ vm_t get_init_base(const void *fdt)
 	return ((vm_t)cp) + align_up(sizeof(struct cpio_header) + name_len, 4);
 }
 
-void move_init(const void *fdt, void *target)
+stat_t move_init(const void *fdt, void *target)
 {
 	const char *c = (const char *)get_initrdbase(fdt);
 
@@ -113,4 +159,5 @@ void move_init(const void *fdt, void *target)
 	fp += align_up(sizeof(struct cpio_header) + name_len, 4);
 
 	memmove(target, fp, file_len);
+	return OK;
 }
diff --git a/common/sp_tree.c b/common/sp_tree.c
index 9003f40..04b14c0 100644
--- a/common/sp_tree.c
+++ b/common/sp_tree.c
@@ -10,6 +10,13 @@
 
 #include <apos/sp_tree.h>
 
+/**
+ * Basic BST left turn.
+ * Drop node \c n down to the left side of the right node, letting it take
+ * the place of \c n.
+ *
+ * @param n Node to turn left.
+ */
 static void __sp_turn_left(struct sp_node *n)
 {
 	struct sp_node *l = sp_left(n);
@@ -29,6 +36,15 @@ static void __sp_turn_left(struct sp_node *n)
 		sp_lparen(n) = n;
 }
 
+/**
+ * Basic BST right turn.
+ * Drop node \c n down to the right side of the left node, letting it take the
+ * place of \c n.
+ *
+ * Does not check if right node exists.
+ *
+ * @param n Node to turn right.
+ */
 static void __sp_turn_right(struct sp_node *n)
 {
 	struct sp_node *r = sp_right(n);
@@ -48,10 +64,16 @@ static void __sp_turn_right(struct sp_node *n)
 		sp_rparen(n) = n;
 }
 
-static int __sp_balance(struct sp_node *n)
+/**
+ * Calculate approximate balance of node, based on height hints.
+ *
+ * @param n Node to calculate balance for.
+ * @return Balance of node.
+ */
+static int_fast16_t __sp_balance(struct sp_node *n)
 {
-	int l = 0;
-	int r = 0;
+	int_fast16_t l = 0;
+	int_fast16_t r = 0;
 
 	if (sp_left(n))
 		l = sp_left(n)->hint + 1;
@@ -62,10 +84,16 @@ static int __sp_balance(struct sp_node *n)
 	return l - r;
 }
 
-static int __sp_max_hint(struct sp_node *n)
+/**
+ * Get highest hint.
+ * 
+ * @param n Node to calculate highest hint for.
+ * @return Highest hint.
+ */
+static int_fast16_t __sp_max_hint(struct sp_node *n)
 {
-	int l = 0;
-	int r = 0;
+	int_fast16_t l = 0;
+	int_fast16_t r = 0;
 
 	if (sp_left(n))
 		l = sp_left(n)->hint + 1;
@@ -79,6 +107,12 @@ static int __sp_max_hint(struct sp_node *n)
 		return r;
 }
 
+/**
+ * Balance tree, moving up from c n.
+ *
+ * @param root Root of tree.
+ * @param n Node to start balancing operation from.
+ */
 static void __sp_update(struct sp_node **root, struct sp_node *n)
 {
 	while (n) {
@@ -127,6 +161,12 @@ void sp_insert(struct sp_node **root, struct sp_node *p, struct sp_node *n,
 	__sp_update(root, n);
 }
 
+/**
+ * Replace node \c n with \c l, pulling of the righthand side of \n.
+ *
+ * @param n Node to replace.
+ * @param r Node to replace with.
+ */
 static void __sp_replace_right(struct sp_node *n, struct sp_node *r)
 {
 	struct sp_node *p = sp_paren(n);
@@ -158,6 +198,12 @@ static void __sp_replace_right(struct sp_node *n, struct sp_node *r)
 		sp_lparen(n) = r;
 }
 
+/**
+ * Replace node \c n with node \c l, pulling up the lefthand side of \c n.
+ *
+ * @param n Node to replace.
+ * @param l Node to replace with.
+ */
 static void __sp_replace_left(struct sp_node *n, struct sp_node *l)
 {
 	struct sp_node *p = sp_paren(n);
@@ -189,7 +235,6 @@ static void __sp_replace_left(struct sp_node *n, struct sp_node *l)
 		sp_rparen(n) = l;
 }
 
-/* TODO: handle root better */
 void sp_remove(struct sp_node **root, struct sp_node *del)
 {
 	if (sp_right(del)) {
diff --git a/common/string.c b/common/string.c
index 6a56698..156f7f8 100644
--- a/common/string.c
+++ b/common/string.c
@@ -9,7 +9,7 @@
 
 /* we need to undef the macros in string.h, otherwise the names get mangled */
 #undef strcpy
-__weak char *strcpy(char *dst, const char *src)
+__weak char *strcpy(char * restrict dst, const char * restrict src)
 {
 	const char *s1 = src;
 	char *s2 = dst;
@@ -21,7 +21,7 @@ __weak char *strcpy(char *dst, const char *src)
 }
 
 #undef strncpy
-__weak char *strncpy(char *dst, const char *src, size_t num)
+__weak char *strncpy(char * restrict dst, const char * restrict src, size_t num)
 {
 	const char *s1 = src;
 	char *s2 = dst;
@@ -41,7 +41,7 @@ __weak char *strncpy(char *dst, const char *src, size_t num)
 }
 
 #undef strcat
-__weak char *strcat(char *dst, const char *src)
+__weak char *strcat(char * restrict dst, const char * restrict src)
 {
 	const char *s1 = src;
 	size_t l1 = strlen(s1);
@@ -57,7 +57,7 @@ __weak char *strcat(char *dst, const char *src)
 }
 
 #undef strncat
-__weak char *strncat(char *dst, const char *src, size_t num)
+__weak char *strncat(char * restrict dst, const char * restrict src, size_t num)
 {
 	const char *s1 = src;
 	size_t l1 = strlen(s1);
@@ -112,7 +112,7 @@ __weak char *strchr(const char *str, int chr)
 }
 
 #undef strtok
-__weak char *strtok(char *str, const char *delims)
+__weak char *strtok(char * restrict str, const char * restrict delims)
 {
 	static char *cont = 0;
 	const char *s1 = str;
@@ -284,7 +284,7 @@ __weak void *memchr(const void *ptr, int val, size_t num)
 }
 
 #undef memcpy
-__weak void *memcpy(void *dst, const void *src, size_t num)
+__weak void *memcpy(void * restrict dst, const void * restrict src, size_t num)
 {
 	const char *m1 = (const char *)src;
 	char *m2 = (char *)dst;