From 0f4a751e60a6c8ac40592ff44c74f1c9e4846d9a Mon Sep 17 00:00:00 2001
From: Kimplul <kimi.h.kuparinen@gmail.com>
Date: Sun, 29 May 2022 01:07:48 +0300
Subject: continue documentation efforts.

---
 include/arch/cpu.h  |  8 ++++++++
 include/arch/irq.h  | 12 +++++++++++-
 include/arch/pmem.h | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 1 deletion(-)

(limited to 'include/arch')

diff --git a/include/arch/cpu.h b/include/arch/cpu.h
index 23b2911..763ebba 100644
--- a/include/arch/cpu.h
+++ b/include/arch/cpu.h
@@ -15,7 +15,15 @@
 #include "../../arch/riscv32/include/cpu.h"
 #endif
 
+/**
+ * Get current CPU ID.
+ * ID must be in range \c 0 .. \c num_cpus, where \c num_cpus is the number of
+ * cpus on this system.
+ *
+ * @return Current CPU ID.
+ */
 id_t cpu_id();
+
 /* TODO: add more cpu handling functions */
 
 #endif /* APOS_CPU_H */
diff --git a/include/arch/irq.h b/include/arch/irq.h
index 5526b18..7c6a365 100644
--- a/include/arch/irq.h
+++ b/include/arch/irq.h
@@ -5,6 +5,8 @@
  * @file irq.h
  * Arch-specific interrupt handling, generally implemented in
  * arch/whatever/kernel/irq.c
+ *
+ * @todo These should probably also be stat_t...
  */
 
 #if defined(riscv64)
@@ -13,9 +15,17 @@
 #include "../../arch/riscv32/include/irq.h"
 #endif
 
+/**
+ * Initialize IRQ subsystem.
+ *
+ * @param fdt Global FDT pointer.
+ */
 void init_irq(void *fdt);
-void handle_irq();
+
+/** Enable IRQs. */
 void enable_irq();
+
+/** Disable IRQs. */
 void disable_irq();
 
 #endif /* APOS_IRQ_H */
diff --git a/include/arch/pmem.h b/include/arch/pmem.h
index c9423b2..21a721a 100644
--- a/include/arch/pmem.h
+++ b/include/arch/pmem.h
@@ -16,6 +16,47 @@
 #include "../../arch/riscv32/include/pmem.h"
 #endif
 
+/**
+ * Get physical memory parameters.
+ *
+ * The kernel assumes all virtual addresses can be represented approximately as
+ * follows:
+ *
+ * @code
+ * Content ... 0 1 1 0 0 1 0 1 0
+ * -----------------------------
+ * Index   ... 9 8 7 6 5 4 3 2 1
+ *           --- --- --- +++++++
+ *           O2  O1  O0  Base
+ * @endcode
+ *
+ * Where \c Base is a portion of the address that is directly passed through
+ * without any lookups, and each \c O0, \c O1, \c O2 are increasingly higher
+ * order pages, where each order is an index into the higher order.
+ *
+ * For example, in the diagram above:
+ * The base page is four bits, and each page order consists of four pages of
+ * one order lower (two bits), and there are three orders, so
+ * @code
+ * max_order = 2
+ * base_bits = 4
+ * bits[0] = 2
+ * bits[1] = 2
+ * bits[2] = 2
+ * bits[3] = 0
+ * ...
+ * @endcode
+ *
+ * @todo Move documentation into its own .md
+ *
+ * @param fdt Global FDT pointer.
+ * @param max_order Highest order pages the arch supports.
+ * @param base_bits Size of base page as number of bits in bitmask.
+ * Eg. 12bits -> 4k page.
+ * @param bits Size in bits as bitmask of corresponding page order. Zeroed out
+ * beforehand.
+ * @return \ref OK when query succesful, arch specific otherwise.
+ */
 stat_t stat_pmem_conf(void *fdt, size_t *max_order, size_t *base_bits,
                       size_t bits[NUM_ORDERS]);
 
-- 
cgit v1.3