add @file info to all files

+ Next step, start documenting contents of each file.

28 files changed, 169 insertions, 6 deletions

diff --git a/include/apos/assert.h b/include/apos/assert.h
index f3d9a4d..eed521c 100644
--- a/include/apos/assert.h
+++ b/include/apos/assert.h
@@ -1,6 +1,20 @@
 #ifndef APOS_ASSERT_H
 #define APOS_ASSERT_H
 
+/**
+ * @file assert.h
+ * Assertions. Note that contrary to how assertios usually function, apos has
+ * three different levels of assertions: Catastrophic, hard and soft.
+ *
+ * Soft assertions merely warn about something that might cause issues, but let
+ * the execution continue normally.
+ *
+ * Hard assertions warn about the assertion not holding and returns from the
+ * function.
+ *
+ * Catastrophic assertions warn about the assertion and crash the kernel.
+ */
+
 #include <apos/debug.h>
 #include <apos/utils.h>
 
diff --git a/include/apos/atomic.h b/include/apos/atomic.h
index e6dafc8..4026b1f 100644
--- a/include/apos/atomic.h
+++ b/include/apos/atomic.h
@@ -1,6 +1,12 @@
 #ifndef ATOMIC_H
 #define ATOMIC_H
 
+/**
+ * @file atomic.h
+ * Atomics, closely modeled after C17 stdatomic.h. Largely dependent on the
+ * compiler at the moment.
+ */
+
 #include <apos/utils.h> /* GLUE */
 
 typedef enum {
diff --git a/include/apos/attrs.h b/include/apos/attrs.h
index 094ae54..dd28b65 100644
--- a/include/apos/attrs.h
+++ b/include/apos/attrs.h
@@ -1,4 +1,10 @@
 #ifndef APOS_COMPILER_ATTRIBUTES_H
+#define APOS_COMPILER_ATTRIBUTES_H
+
+/**
+ * @file attrs.h
+ * Attribute shorthands.
+ */
 
 #define __section(section) __attribute__((__section__(section)))
 #define __fmt(x, y)        __attribute__((format(__printf__, x, y)))
diff --git a/include/apos/bits.h b/include/apos/bits.h
index ca25007..66a495c 100644
--- a/include/apos/bits.h
+++ b/include/apos/bits.h
@@ -1,6 +1,11 @@
 #ifndef APOS_BITS_H
 #define APOS_BITS_H
 
+/**
+ * @file bits.h
+ * Bit manipulations.
+ */
+
 #include <apos/types.h>
 #include <apos/builtin.h>
 
diff --git a/include/apos/builtin.h b/include/apos/builtin.h
index 52a3fa2..b6ce0e0 100644
--- a/include/apos/builtin.h
+++ b/include/apos/builtin.h
@@ -1,6 +1,15 @@
 #ifndef APOS_BUILTIN_H
 #define APOS_BUILTIN_H
 
+/**
+ * @file builtin.h
+ * Defines __has_builtin, if the compiler doesn't support it.
+ *
+ * Technically we only support clang and gcc at the moment, and they both
+ * support __has_builtin, but if some interesting compiler comes along then
+ * we'll be golden.
+ */
+
 #ifndef __has_builtin
 #define __has_builtin(x) (0)
 #endif
diff --git a/include/apos/conf.h b/include/apos/conf.h
index 844ce37..2b861dc 100644
--- a/include/apos/conf.h
+++ b/include/apos/conf.h
@@ -1,6 +1,12 @@
 #ifndef APOS_CONF_H
 #define APOS_CONF_H
 
+/**
+ * @file conf.h
+ * Global configuration file, gives extern access to runtime configuration
+ * parameters when they're implemented.
+ */
+
 #include <apos/types.h>
 
 extern size_t __proc_stack_size;
diff --git a/include/apos/debug.h b/include/apos/debug.h
index 8df7342..6d49f12 100644
--- a/include/apos/debug.h
+++ b/include/apos/debug.h
@@ -1,6 +1,11 @@
 #ifndef APOS_DEBUG_H
 #define APOS_DEBUG_H
 
+/**
+ * @file debug.h
+ * Debug printing.
+ */
+
 #include <apos/attrs.h>
 #include <apos/pmem.h>
 #include <arch/vmem.h>
diff --git a/include/apos/dmem.h b/include/apos/dmem.h
index 59083cb..38476ec 100644
--- a/include/apos/dmem.h
+++ b/include/apos/dmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_DEV_H
 #define APOS_DEV_H
 
+/**
+ * @file dmem.h
+ * Device memory handling, i.e. anything outside of RAM.
+ */
+
 #include <apos/types.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/elf.h b/include/apos/elf.h
index 7d0004a..cea504e 100644
--- a/include/apos/elf.h
+++ b/include/apos/elf.h
@@ -1,6 +1,13 @@
 #ifndef APOS_ELF_H
 #define APOS_ELF_H
 
+/**
+ * @file elf.h
+ * ELF file handling.
+ *
+ * \todo Other file formats?
+ */
+
 #include <apos/attrs.h>
 #include <apos/types.h>
 #include <apos/vmem.h>
diff --git a/include/apos/initrd.h b/include/apos/initrd.h
index 17ed94c..5644106 100644
--- a/include/apos/initrd.h
+++ b/include/apos/initrd.h
@@ -1,6 +1,11 @@
 #ifndef APOS_INITRD_H
 #define APOS_INITRD_H
 
+/**
+ * @file initrd.h
+ * Initrd handling.
+ */
+
 #include <apos/types.h>
 #include <apos/pmem.h>
 #include <apos/vmem.h>
diff --git a/include/apos/lock.h b/include/apos/lock.h
index 178140b..2fac160 100644
--- a/include/apos/lock.h
+++ b/include/apos/lock.h
@@ -1,5 +1,11 @@
-#ifndef LOCK_H
-#define LOCK_H
+#ifndef APOS_LOCK_H
+#define APOS_LOCK_H
+
+/**
+ * @file lock.h
+ * Atomic locks, currently only \ref spin_lock and \ref spin_unlock. Mutex is
+ * probably overkill for this project.
+ */
 
 #include <apos/atomic.h>
 #include <apos/irq.h>
@@ -23,4 +29,4 @@ static inline void spin_unlock(spinlock_t *lck)
 	enable_irq();
 }
 
-#endif /* LOCK_H */
+#endif /* APOS_LOCK_H */
diff --git a/include/apos/mem.h b/include/apos/mem.h
index f3eded7..bbe7532 100644
--- a/include/apos/mem.h
+++ b/include/apos/mem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_MEM_H
 #define APOS_MEM_H
 
+/**
+ * @file mem.h
+ * Generic memory, common to both physical and virtual memory.
+ */
+
 #include <apos/utils.h>
 #include <apos/types.h>
 
diff --git a/include/apos/mem_nodes.h b/include/apos/mem_nodes.h
index 50f280d..5a67f08 100644
--- a/include/apos/mem_nodes.h
+++ b/include/apos/mem_nodes.h
@@ -1,5 +1,10 @@
-#ifndef MM_NODES_H
-#define MM_NODES_H
+#ifndef APOS_MM_NODES_H
+#define APOS_MM_NODES_H
+
+/**
+ * @file mem_nodes.
+ * Memory node subsystem. Used by the memory region subsystem.
+ */
 
 #include <apos/vmem.h>
 #include <apos/nodes.h>
@@ -10,4 +15,4 @@ void destroy_mem_blocks();
 struct mem_region *get_mem_node();
 void free_mem_node(struct mem_region *m);
 
-#endif /* MM_NODES_H */
+#endif /* APOS_MM_NODES_H */
diff --git a/include/apos/mem_regions.h b/include/apos/mem_regions.h
index 2d777a9..8e9125f 100644
--- a/include/apos/mem_regions.h
+++ b/include/apos/mem_regions.h
@@ -1,6 +1,12 @@
 #ifndef APOS_MEM_REGIONS_H
 #define APOS_MEM_REGIONS_H
 
+/**
+ * @file mem_regions.h
+ * Memory region subsytem. Mainly used by the virtual memory subsytems, i.e. device and
+ * user memory.
+ */
+
 #include <apos/mem.h>
 #include <apos/types.h>
 #include <apos/sp_tree.h>
diff --git a/include/apos/nodes.h b/include/apos/nodes.h
index 9cf6728..3fefc4c 100644
--- a/include/apos/nodes.h
+++ b/include/apos/nodes.h
@@ -1,6 +1,12 @@
 #ifndef APOS_NODES_H
 #define APOS_NODES_H
 
+/**
+ * @file nodes.h
+ * Node subsystem. Used by a number of subsystems for allocating specific sizes
+ * of memory nodes smaller than memory pages.
+ */
+
 #include <apos/types.h>
 
 enum node_status { FREE = 0, USED = 1 };
diff --git a/include/apos/pmem.h b/include/apos/pmem.h
index 2ff817d..0b11555 100644
--- a/include/apos/pmem.h
+++ b/include/apos/pmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_PMEM_H
 #define APOS_PMEM_H
 
+/**
+ * @file pmem.h
+ * Physical memory subsystem. Used to allocate and free physical memory pages.
+ */
+
 #include <apos/mem.h>
 #include <apos/types.h>
 #include <arch/pmem.h>
diff --git a/include/apos/power.h b/include/apos/power.h
index 31f199d..640f056 100644
--- a/include/apos/power.h
+++ b/include/apos/power.h
@@ -1,6 +1,12 @@
 #ifndef APOS_POWER_H
 #define APOS_POWER_H
 
+/**
+ * @file power.h
+ * Power subsystem. Will hopefully eventually be used to restart and shutdown
+ * host machines.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 
diff --git a/include/apos/proc.h b/include/apos/proc.h
index 238e0f6..6b4044d 100644
--- a/include/apos/proc.h
+++ b/include/apos/proc.h
@@ -1,6 +1,12 @@
 #ifndef APOS_PROC_H
 #define APOS_PROC_H
 
+/**
+ * @file proc.h
+ * Process handling subsystem, should likely be merged into \ref
+ * include/apos/tcb.h.
+ */
+
 #include <apos/tcb.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/sizes.h b/include/apos/sizes.h
index 1a34d48..2ac48c7 100644
--- a/include/apos/sizes.h
+++ b/include/apos/sizes.h
@@ -1,6 +1,11 @@
 #ifndef APOS_SIZES_H
 #define APOS_SIZES_H
 
+/**
+ * @file sizes.h
+ * Shorthands for some power-of-two sizes.
+ */
+
 #if defined(__ASSEMBLER__)
 
 #define SZ_1    0x000000000001
diff --git a/include/apos/sp_tree.h b/include/apos/sp_tree.h
index 65e4e89..1df781b 100644
--- a/include/apos/sp_tree.h
+++ b/include/apos/sp_tree.h
@@ -1,6 +1,11 @@
 #ifndef SP_TREE_H
 #define SP_TREE_H
 
+/**
+ * @file sp_tree.h
+ * sp_trees, a type of binary search trees.
+ */
+
 #include <apos/types.h>
 
 #define sp_root(r)       ((r)->sp_r)
diff --git a/include/apos/string.h b/include/apos/string.h
index 8a3c737..e220800 100644
--- a/include/apos/string.h
+++ b/include/apos/string.h
@@ -1,6 +1,11 @@
 #ifndef APOS_STRING_H
 #define APOS_STRING_H
 
+/**
+ * @file string.h
+ * String handling, similar to cstdlib's string.h.
+ */
+
 #include <apos/types.h>
 #include <apos/builtin.h>
 
diff --git a/include/apos/syscalls.h b/include/apos/syscalls.h
index e7b1cd5..19e27ea 100644
--- a/include/apos/syscalls.h
+++ b/include/apos/syscalls.h
@@ -1,6 +1,11 @@
 #ifndef APOS_SYSCALLS_H
 #define APOS_SYSCALLS_H
 
+/**
+ * @file syscalls.h
+ * Table of system calls.
+ */
+
 /* enum for now, possibly macros in the future once I get an approximate idea of
  * which syscalls are necessary etc. */
 enum {
diff --git a/include/apos/tcb.h b/include/apos/tcb.h
index 439a3c9..89b594d 100644
--- a/include/apos/tcb.h
+++ b/include/apos/tcb.h
@@ -1,6 +1,11 @@
 #ifndef APOS_TCB_H
 #define APOS_TCB_H
 
+/**
+ * @file tcb.h
+ * Process/thread handling.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/types.h>
 #include <tcb.h> /* arch-specific data */
diff --git a/include/apos/types.h b/include/apos/types.h
index 2f45857..45526d7 100644
--- a/include/apos/types.h
+++ b/include/apos/types.h
@@ -1,6 +1,11 @@
 #ifndef APOS_TYPES_H
 #define APOS_TYPES_H
 
+/**
+ * @file types.h
+ * Shorthands for types, similar to stdint.h.
+ */
+
 typedef _Bool bool;
 #define true 1
 #define false 0
diff --git a/include/apos/uapi.h b/include/apos/uapi.h
index b3d345f..d33a855 100644
--- a/include/apos/uapi.h
+++ b/include/apos/uapi.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UAPI_H
 #define APOS_UAPI_H
 
+/**
+ * @file uapi.h
+ * Userspace api, syscall declarations.
+ */
+
 #include <apos/syscalls.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/unaligned.h b/include/apos/unaligned.h
index 1dbd253..94439ca 100644
--- a/include/apos/unaligned.h
+++ b/include/apos/unaligned.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UNALIGNED_H
 #define APOS_UNALIGNED_H
 
+/**
+ * @file unaligned.h
+ * Helpers for unaligned memory accesses. Largely lifted from Linux.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 
diff --git a/include/apos/utils.h b/include/apos/utils.h
index e09a35f..25f10b0 100644
--- a/include/apos/utils.h
+++ b/include/apos/utils.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UTILS_H
 #define APOS_UTILS_H
 
+/**
+ * @file utils.
+ * Misc utils and helpers.
+ */
+
 #define ABS(a)        (a < 0 ? -a : a)
 
 #define MAX(a, b)     ((a) >= (b) ? (a) : (b))
diff --git a/include/apos/vmem.h b/include/apos/vmem.h
index d55e249..663b2ab 100644
--- a/include/apos/vmem.h
+++ b/include/apos/vmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_VMEM_H
 #define APOS_VMEM_H
 
+/**
+ * @file vmem.h
+ * Virtual memory handling.
+ */
+
 #include <apos/tcb.h>
 #include <apos/mem.h>
 #include <apos/pmem.h>