continue documentation efforts.

6 files changed, 104 insertions, 25 deletions

diff --git a/arch/riscv64/config.h b/arch/riscv64/config.h
index 33c84a0..bdf31ae 100644
--- a/arch/riscv64/config.h
+++ b/arch/riscv64/config.h
@@ -7,44 +7,74 @@
  * and immutable parameters. Included on the command line by
  * -include.
  *
+ * Assume Sv39, probably wouldn't be too difficult to use runtime parameters
+ * instead. First 4K is reserved for NULL, but I suppose it could be mapped
+ * later if *absolutely* necessary.
+ *
  * @todo Consider separating user-specified and immutable parameters.
+ * @todo Write more thorough documentation, maybe a separate .md file?
  */
 
 #include <apos/sizes.h>
 
 /* --- START ARCH USER CONFIG VALUES --- */
-/* physical address to which the kernel will be loaded */
+/** Physical address to where the OS image will be loaded. */
 #define RAM_BASE      0x80000000
+/* --- END ARCH USER CONFIG VALUES --- */
+
+/* don't touch >:( */
+
+/** Physical address to where the kernel proper will be relocated. */
 #define PM_KERN_BASE  (RAM_BASE + SZ_512K)
+
+/** Maximum size of the kernel proper. Largely arbitrary. */
 #define PM_KERN_SIZE  (SZ_256K)
+
+/** Highest allowed physical address where kernel stuff may lie. */
 #define PM_KERN_TOP   (PM_KERN_BASE + PM_KERN_SIZE)
-/* --- END ARCH USER CONFIG VALUES --- */
 
-/* don't touch >:( */
+/** Physical memory stack base. In this case, right after the kernel. */
+#define PM_STACK_BASE (PM_KERN_BASE + PM_KERN_SIZE)
 
-#define PM_STACK_BASE (PM_KERN_BASE + SZ_256K)
+/** Size of physical memory stack. */
 #define PM_STACK_SIZE (SZ_256K)
+
+/** Top of physical memory stack. */
 #define PM_STACK_TOP  (PM_STACK_BASE + PM_STACK_SIZE)
 
-#if __riscv_xlen == 64
+#if defined(riscv64)
 /* 64bit */
+
+/** Direct map offset. */
 #define VM_DMAP         (0xffffffc000000000) /* testing for now */
+
+/** Virtual address of kernel proper inside direct mapping. */
 #define VM_KERN         (VM_DMAP + SZ_256K)
 
+/** Page reserved for kernel I/O. */
 #define IO_PAGE         511UL
+
+/** Direct mapping starts from this page. */
 #define KSTART_PAGE     256UL
+
+/** The RPC stack page. */
 #define CSTACK_PAGE     255UL
 
-/* assume Sv39, probably wouldn't be too difficult to use runtime parameters
- * instead. First 4K is reserved for NULL, but I suppose it could be mapped
- * later if *absolutely* necessary. */
+/** User virtual memory space start. */
 #define UVMEM_START     (SZ_4K)
+
+/**  User virtual memory space end. */
 #define UVMEM_END       (SZ_256G - SZ_1G)
 
-#define PROC_STACK_TOP  (SZ_256G)
-#define PROC_STACK_BASE (SZ_256G - SZ_1G)
+/** RPC stack top. */
+#define RPC_STACK_TOP  (SZ_256G)
+
+/** RPC stack base. */
+#define RPC_STACK_BASE (SZ_256G - SZ_1G)
+
 #else
 /* 32bit */
+
 /* TODO: figure this stuff out */
 #define VM_DMAP         (0x000000000)
 #define VM_KERN         (VM_DMAP + SZ_256K)
@@ -55,9 +85,6 @@
 #define KSTART_PAGE     512UL
 #define CSTACK_PAGE     511UL
 
-/* assume Sv39, probably wouldn't be too difficult to use runtime parameters
- * instead. First 4K is reserved for NULL, but I suppose it could be mapped
- * later if *absolutely* necessary. */
 #define UVMEM_START     (SZ_4K)
 #define UVMEM_END       (SZ_4G - SZ_8M)
 
diff --git a/arch/riscv64/gen/asm-offsets.c b/arch/riscv64/gen/asm-offsets.c
index fbe2726..71a1c9a 100644
--- a/arch/riscv64/gen/asm-offsets.c
+++ b/arch/riscv64/gen/asm-offsets.c
@@ -7,12 +7,36 @@
 #include <apos/utils.h>
 #include "../kernel/regs.h"
 
-/* largely based on linux */
+/**
+ * Insert assembly comment with calculated value.
+ * Largely based on linux
+ *
+ * @param sym Name of symbol.
+ * @param val Value of symbol.
+ */
 #define DEFINE(sym, val)                                                       \
 	__asm__ volatile ("\n#-> " #sym " %0 " #val "\n" : : "i" (val))
+
+/**
+ * Insert offset of member in structure.
+ *
+ * @param m Member.
+ * @param s Structure.
+ */
 #define OFFSETOF(m, s) DEFINE(offsetof_##m, offsetof(s, m))
+
+/**
+ * Insert size of structure.
+ *
+ * @param n Name of structure.
+ * @param s Structure.
+ */
 #define SIZEOF(n, s)   DEFINE(sizeof_##n, sizeof(s))
 
+/**
+ * Generate assembly with calculated offsets and sizes.
+ * See arch/riscv64/gen/source.mk for how the assembly is used.
+ */
 void asm_offsets()
 {
 	OFFSETOF(ra, struct riscv_regs);
diff --git a/arch/riscv64/include/tcb.h b/arch/riscv64/include/tcb.h
index be6d58a..8cd32ed 100644
--- a/arch/riscv64/include/tcb.h
+++ b/arch/riscv64/include/tcb.h
@@ -6,9 +6,13 @@
  * riscv64 definitions of arch-specific tcb data.
  */
 
+/**
+ * riscv-specific thread handling stuff.
+ *
+ * Empty for now, but should probably be filled with stuff like register
+ * saving of something
+ */
 struct arch_tcbd {
-	/* empty for now, but should probably be filled with stuff like register
-	 * saving of something */
 };
 
 #endif /* ARCH_RISCV_TCB_H */
diff --git a/arch/riscv64/init/init.c b/arch/riscv64/init/init.c
index 5fe463a..db428dd 100644
--- a/arch/riscv64/init/init.c
+++ b/arch/riscv64/init/init.c
@@ -11,13 +11,22 @@
 #include <arch/vmem.h>
 #include "../kernel/csr.h"
 
-/* assume 64 bit for now */
+/** Temporary virtual memory space.
+ * Assume 64bit riscv for now.
+ */
 struct vmem *root_branch;
 
+/**
+ * Create page table entry.
+ * Copy from \ref arch/riscv64/kernel/vmem.c.
+ *
+ * @param a Virtual address.
+ * @param f PTE flags.
+ */
 #define to_pte(a, f) (((a) >> 12) << 10 | (f))
 
-/* assume Sv39 for now */
-void init_bootmem()
+/** Jump into virtual memory. */
+static void init_bootmem()
 {
 	size_t flags = VM_V | VM_X | VM_R | VM_W;
 
@@ -41,7 +50,8 @@ void init_bootmem()
 	csr_write(CSR_SATP, SATP_MODE_Sv39 | ((uintptr_t)root_branch >> 12));
 }
 
-void move_kernel()
+/** Relocate kernel proper. */
+static void move_kernel()
 {
 	extern char *__init_end;
 	extern char *__kernel_size;
@@ -53,6 +63,12 @@ void move_kernel()
 		dst[i] = src[i];
 }
 
+/**
+ * Convert an existing physical address in a register to a virtual address.
+ * There is probably an easier way to do this, but this seems to work alright.
+ *
+ * @param reg Register to modify.
+ */
 #define __va_reg(reg)                                                          \
 	{                                                                      \
 		vm_t reg = 0;                                                  \
@@ -61,6 +77,11 @@ void move_kernel()
 		__asm__ ("mv " QUOTE(reg) ", %0" ::"rK" (reg) :);                \
 	}
 
+/**
+ * Main driver for the init loader.
+ *
+ * @param fdt Global FDT pointer, provided by bootloader.
+ */
 void init(void *fdt)
 {
 	extern char *__init_end;
diff --git a/arch/riscv64/init/start.S b/arch/riscv64/init/start.S
index 7842946..f5ed2fe 100644
--- a/arch/riscv64/init/start.S
+++ b/arch/riscv64/init/start.S
@@ -1,5 +1,6 @@
 .section .init.start
 .global _start
+/* Entry point to the kernel loader. */
 _start:
 li sp, PM_STACK_TOP
 call init
diff --git a/arch/riscv64/kernel/irq.c b/arch/riscv64/kernel/irq.c
index 15fa750..6fdfe85 100644
--- a/arch/riscv64/kernel/irq.c
+++ b/arch/riscv64/kernel/irq.c
@@ -8,7 +8,13 @@
 #include <arch/irq.h>
 #include "csr.h"
 
-extern void handle_irq(void);
+/** Defined in arch/riscv64/kernel/entry.S. */
+extern void handle_irq();
+
+/** Called from arch/riscv64/kernel/entry.S. */
+void handle_sys_irq()
+{
+}
 
 void init_irq(void *fdt)
 {
@@ -20,10 +26,6 @@ void init_irq(void *fdt)
 	info("CSR_SIE: %lx\n", s);
 }
 
-void handle_sys_irq()
-{
-}
-
 /* very simple for now */
 void enable_irq()
 {