From 7a23d95b6e432170d6575f515616e5936d53c85e Mon Sep 17 00:00:00 2001
From: Kimplul <kimi.h.kuparinen@gmail.com>
Date: Wed, 30 Oct 2024 02:32:02 +0200
Subject: bookkeeping

---
 include/arch/proc.h |  7 +++++++
 include/arch/tcb.h  |  6 ++++++
 include/arch/vmem.h | 12 +++++++++++-
 include/kmi/bkl.h   |  5 +++++
 include/kmi/panic.h | 10 ++++++++++
 include/kmi/vmem.h  |  8 ++++++++
 6 files changed, 47 insertions(+), 1 deletion(-)

(limited to 'include')

diff --git a/include/arch/proc.h b/include/arch/proc.h
index 7921e5c..b0f0944 100644
--- a/include/arch/proc.h
+++ b/include/arch/proc.h
@@ -127,6 +127,13 @@ __noreturn void run_init(struct tcb *t, vm_t fdt, vm_t initrd);
  * so I'm not too worried.
  */
 __noreturn void ret_userspace_fast();
+
+/**
+ * Return to userspace, restoring some registers.
+ * Mainly for returning from an ipc_resp, where the user is expected to save
+ * temporary registers on their own.
+ * Same as with \ref ret_userspace_fast(), skips canary checking.
+ */
 __noreturn void ret_userspace_partial();
 
 #endif /* KMI_ARCH_PROC_H */
diff --git a/include/arch/tcb.h b/include/arch/tcb.h
index 8eddb07..18386d3 100644
--- a/include/arch/tcb.h
+++ b/include/arch/tcb.h
@@ -42,6 +42,12 @@ stat_t setup_rpc_stack(struct tcb *t);
  */
 void destroy_rpc_stack(struct tcb *t);
 
+/**
+ * Copy over contents in rpc stack from \p t to \p c.
+ *
+ * @param t 'Source'.
+ * @param c 'Destination'-
+ */
 void copy_rpc_stack(struct tcb *t, struct tcb *c);
 
 /**
diff --git a/include/arch/vmem.h b/include/arch/vmem.h
index 0f06cc5..ad32519 100644
--- a/include/arch/vmem.h
+++ b/include/arch/vmem.h
@@ -167,11 +167,21 @@ struct vmem *create_vmem();
 void use_vmem(struct vmem *b);
 
 /**
- * Destroy virtual memory space.
+ * Completely destroy virtual memory space.
+ * Should only be called for ->proc.vmem, as it is the only one that is sure to
+ * own all nodes.
  *
  * @param b Virtual memory to destroy.
  */
 void destroy_vmem(struct vmem *b);
+
+/**
+ * Destroy 'regular' virtual memory space.
+ * Should be called for ->rpc.vmem, as rpc can have some references that it
+ * doesn't own into ->proc.vmem, and this function is careful not to free those.
+ *
+ * @param b Virtual memory to destroy.
+ */
 void destroy_rpcmem(struct vmem *b);
 
 /**
diff --git a/include/kmi/bkl.h b/include/kmi/bkl.h
index 8a56061..b77b08a 100644
--- a/include/kmi/bkl.h
+++ b/include/kmi/bkl.h
@@ -12,6 +12,11 @@
 
 #include <kmi/lock.h>
 
+/**
+ * Initialize Big Kernel Lock.
+ * In theory, the BKL being statically initialized to 0 should be enough, but
+ * this feels a bit safer.
+ */
 void bkl_init();
 
 /** Lock the Big Kernel Lock. */
diff --git a/include/kmi/panic.h b/include/kmi/panic.h
index 121323c..0cfebc7 100644
--- a/include/kmi/panic.h
+++ b/include/kmi/panic.h
@@ -22,6 +22,16 @@
  */
 __noreturn void kernel_panic(void *pc, void *addr, long cause);
 
+/**
+ * Call on some other, like userspace doing something that we currently can't
+ * deal with. Tries to reboot the system. Failing that, spin.
+ * Ideally registers and kernel state would be printed, but keep things simple
+ * for now.
+ *
+ * @param pc Address where fault occured. Should preferably be in the kernel.
+ * @param addr Possibly associated address.
+ * @param cause Possible error code associated with panic. Page fault, etc.
+ */
 __noreturn void unhandled_panic(void *pc, void *addr, long cause);
 
 #endif /* KMI_PANIC_H */
diff --git a/include/kmi/vmem.h b/include/kmi/vmem.h
index 9424e33..0f1832a 100644
--- a/include/kmi/vmem.h
+++ b/include/kmi/vmem.h
@@ -174,6 +174,14 @@ stat_t copy_uvmem(struct tcb *d, struct tcb *s);
  */
 vmflags_t sanitize_uvflags(vmflags_t flags);
 
+/**
+ * Handle page faults.
+ * If a page fault was to some legal address, the TLB is repopulated and the
+ * access is attempted again. Kind of like COW.
+ * Otherwise, the process gets killed (TODO)
+ *
+ * @param addr Address that caused a page fault.
+ */
 void handle_pagefault(vm_t addr);
 
 #endif /* KMI_VMEM_H */
-- 
cgit v1.3