continue documentation

3 files changed, 150 insertions, 5 deletions

diff --git a/include/arch/arch.h b/include/arch/arch.h
index c19b039..c4f2d28 100644
--- a/include/arch/arch.h
+++ b/include/arch/arch.h
@@ -15,6 +15,15 @@
 #include "../../arch/riscv32/include/arch.h"
 #endif
 
+/**
+ * Setup arch specific stuff.
+ *
+ * See arch documentation if there is any.
+ *
+ * @param fdt Global FDT.
+ * @return \ref OK if boot can continue, error otherwise.
+ * \todo Check errors.
+ */
 stat_t setup_arch(void *fdt);
 
 #endif /* APOS_ARCH_H */
diff --git a/include/arch/proc.h b/include/arch/proc.h
index 7c6ad5b..e27fbf6 100644
--- a/include/arch/proc.h
+++ b/include/arch/proc.h
@@ -12,10 +12,45 @@
 #include "../../arch/riscv32/include/proc.h"
 #endif
 
+/**
+ * Set address to jump to when returning to userspace.
+ *
+ * @param r Address to jump to.
+ * @return \ref OK.
+ */
 stat_t set_return(vm_t r);
+
+/**
+ * Attach IPC data to load into argument registers when returning to userspace.
+ *
+ * @param t Thread that will run after return.
+ * @param pid Process ID.
+ * @param tid Thread ID.
+ * @return \ref OK.
+ */
 stat_t set_ipc(struct tcb *t, id_t pid, id_t tid);
-/*\todo: should this be in arch/tcb.h or something? */
-stat_t set_thread(struct tcb *t, vm_t stack);
+
+/** \todo Should these be in arch/tcb.h or something? */
+/** \todo Should these be void? */
+
+/**
+ * Attach thread stack and thread local storage when returning to userspace.
+ *
+ * Their info should already be stored in \c t, and this function just
+ * actualizes the information.
+ *
+ * @param t Thread that will run after return.
+ * @return \ref OK.
+ */
+stat_t set_thread(struct tcb *t);
+
+/**
+ * Run \c init program.
+ *
+ * @param t Thread that \c init is attached to.
+ * @param fdt Pointer to FDT that is passed to \c init.
+ * @return \ref ERR_ADDR, as it shouldn't return-
+ */
 stat_t run_init(struct tcb *t, void *fdt);
 
 #endif /* APOS_ARCH_PROC_H */
diff --git a/include/arch/vmem.h b/include/arch/vmem.h
index b39d905..dcfe7fd 100644
--- a/include/arch/vmem.h
+++ b/include/arch/vmem.h
@@ -13,28 +13,129 @@
 #include "../../arch/riscv32/include/vmem.h"
 #endif
 
+/**
+ * Map one virtual page to physical page.
+ *
+ * If \ref INFO_SEFF is returned, the caller is responsible for synchronizing
+ * all other threads that are in the same virtual address space.
+ *
+ * The caller is responsible for checking that both virtual and physical page of
+ * the correct order are available.
+ *
+ * @param branch Virtual memory to work in.
+ * @param paddr Physical address of page.
+ * @param vaddr Virtual address to map page to.
+ * @param flags Page flags.
+ * @param order Order of page.
+ * @return \ref INFO_SEFF when top level table modified, \ref OK otherwise.
+ */
 stat_t map_vpage(struct vmem *branch, pm_t paddr, vm_t vaddr, vmflags_t flags,
                  enum mm_order order);
 
+/**
+ * Unmap one page.
+ *
+ * @param branch Virtual memory to work in.
+ * @param vaddr Virtual address of page to unmap.
+ * @return \ref OK when succesful, \ref ERR_NF if no page at \c vaddr could be
+ * found.
+ */
 stat_t unmap_vpage(struct vmem *branch, vm_t vaddr);
 
+/**
+ * Modify page mapping physical address and flags.
+ *
+ * Note that changing the order of a page is not supported, to do that unmap and
+ * remap a page.
+ *
+ * @param branch Virtual memory to work in.
+ * @param vaddr Virtual address of map to modify.
+ * @param paddr Physical address to map to.
+ * @param flags Flags to set.
+ * @return \ref ERR_NF if no virtual page is found at \c vaddr.
+ * \ref INFO_SEFF if modding takes place in top page table but otherwise
+ * succesful, \ref OK otherwise.
+ */
 stat_t mod_vpage(struct vmem *branch, vm_t vaddr, pm_t paddr, vmflags_t flags);
+
+/**
+ * Get information about physical page.
+ *
+ * @param branch Virtual memory to work in.
+ * @param vaddr Virtual address of map to get parameters of.
+ * @param paddr Where to write physical address of the page.
+ * @param order Where to write the order of the page.
+ * @param flags Where to write the physical mapping flags of the page.
+ * @return \ref ERR_NF when no page is found at \c vaddr, \ref OK otherwise.
+ */
 stat_t stat_vpage(struct vmem *branch, vm_t vaddr, pm_t *paddr,
                   enum mm_order *order, vmflags_t *flags);
 
+/** Flush tlb of current processor. */
 void flush_tlb();
+
+/** Flush tlbs of all processors. */
 void flush_tlb_all();
 
+/** \todo Add flushing of only some region in memory? */
+
+/**
+ * Populate virtual memory with kernel virtual address info.
+ *
+ * @param b Virtual memory to work in.
+ * @return \ref OK.
+ */
 stat_t populate_kvmem(struct vmem *b);
+
+/**
+ * Initialize arch virtual memory and return boot virtual memory.
+ *
+ * @param fdt Global FDT pointer.
+ * @return Pointer to new boot virtual memory when succesful, \c NULL otherwise.
+ */
 struct vmem *init_vmem(void *fdt);
 
 #if defined(DEBUG)
+/**
+ * Map and setup serial port.
+ *
+ * @param b Virtual memory to work in.
+ * @param paddr Physical address of serial port.
+ * @return Virtual address of serial port.
+ */
 vm_t setup_kernel_io(struct vmem *b, vm_t paddr);
 #endif
 
+/**
+ * Create new virtual memory space.
+ *
+ * @return Pointer to virtual memory root when succesful, \c NULL otherwise.
+ */
 struct vmem *create_vmem();
-stat_t use_vmem(struct vmem *);
-stat_t destroy_vmem(struct vmem *);
-stat_t clone_uvmem(struct vmem *, struct vmem *);
+
+/**
+ * Jump into virtual memory context.
+ *
+ * @param b Virtual memory to jump into.
+ * @return \ref OK.
+ */
+stat_t use_vmem(struct vmem *b);
+
+/**
+ * Destroy virtual memory space.
+ *
+ * @param b Virtual memory to destroy.
+ * @return \ref OK.
+ */
+stat_t destroy_vmem(struct vmem *b);
+
+/**
+ * Raw clone user virtual memory.
+ *
+ * @param r Source virtual memory of clone.
+ * @param b Destination virtual memory of clone.
+ * @return \ref OK.
+ */
+stat_t clone_uvmem(struct vmem *r, struct vmem *b);
 
 #endif /* APOS_ARCH_PAGES_H */