From ad072dbf39036eaeb2879bd39f5195175d8b1280 Mon Sep 17 00:00:00 2001
From: Miquel Sabaté Solà <mikisabate@gmail.com>
Date: Wed, 4 Dec 2024 14:23:44 +0100
Subject: Move documentation to the proper places
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Code documentation was scattered between header and source files. Since
the norm was already to have this documentation into header files, move
some comments from source files to their header counterparts. This
hopefully makes things more consistent.

Signed-off-by: Miquel Sabaté Solà <mikisabate@gmail.com>
---
 include/fbos/init.h  |  6 +++++-
 include/fbos/sched.h | 23 ++++++++++++++++++-----
 kernel/main.c        | 17 ++---------------
 kernel/trap.c        |  5 +++++
 4 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/include/fbos/init.h b/include/fbos/init.h
index a3cc16f..f253645 100644
--- a/include/fbos/init.h
+++ b/include/fbos/init.h
@@ -50,7 +50,11 @@ void extract_initrd(const unsigned char *const base_addr, uint64_t size,
 // Setup the interrupt vectors and the SBI timer.
 void setup_interrupts(void);
 
-// The entry point for the kernel.
+/*
+ * This is the main entry point of the kernel after head.S is done. This
+ * function can (and will) assume that everything has been reset and that we can
+ * start the whole thing.
+ */
 void start_kernel(void *dtb);
 
 #endif /* __FBOS_INIT_H */
diff --git a/include/fbos/sched.h b/include/fbos/sched.h
index ced620c..23763d3 100644
--- a/include/fbos/sched.h
+++ b/include/fbos/sched.h
@@ -24,15 +24,28 @@ struct task_struct {
 	const void *entry_addr;
 };
 
-// Instantiated in kernel/main.c.
+/*
+ * Stack to be used by our processes, which is initialized in head.S.
+ * "Blasphemy!" I hear you say. "How dare you use the same stack for kernel and
+ * user space?" It's not like this is some sort of utopian system in which
+ * everyone shares everything, but since this stupidly simple kernel does not\
+ * even bother to implement paging nor any other memory protection of any kind,
+ * it's not like separating stacks for each process and kernel space would make
+ * much of a difference. Hence, let's keep it simple and have the same stack
+ * everwhere.
+ *
+ * Instantiated in kernel/main.c.
+ */
 extern uint64_t stack[];
 
-// Tasks available on this kernel.
+// Tasks available on this kernel. Instantiated in kernel/main.c
 extern struct task_struct tasks[4];
 
-// Prepare for switching to the given task. Note that this will not actually
-// jump into the given task, but it will prepare the relevant registers before
-// performing the actual jump.
+/*
+ * Prepare for switching to the given task. Note that this will not actually
+ * jump into the given task, but it will prepare the relevant registers before
+ * performing the actual jump.
+ */
 __kernel __always_inline void prepare_switch_to(int task_id)
 {
 	register struct task_struct *current asm("tp");
diff --git a/kernel/main.c b/kernel/main.c
index 822d638..41619d6 100644
--- a/kernel/main.c
+++ b/kernel/main.c
@@ -11,18 +11,10 @@
 atomic32_t hart_lottery __section(".sdata");
 uint32_t hart_id;
 
-// Stack to be used by our processes, which is initialized in head.S.
-// "Blasphemy!" I hear you say. "How dare you use the same stack for kernel and
-// user space?" It's not like this is some sort of utopian system in which
-// everyone shares everything, but since this stupidly simple kernel does not
-// even bother to implement paging nor any other memory protection of any kind,
-// it's not like separating stacks for each process and kernel space would make
-// much of a difference. Hence, let's keep it simple and have the same stack
-// everwhere.
+// Defined in fbos/sched.h.
 uint64_t stack[STACK_SIZE / sizeof(uint64_t)];
 
-// Initialize the list of structs by providing a fixed stack address and empty
-// values everywhere else.
+// Defined in fbos/sched.h.
 struct task_struct tasks[4] = {
 	[TASK_INIT] = { .name = "init", .entry_addr = nullptr, },
 	[TASK_FIZZ] = { .name = "fizz", .entry_addr = nullptr, },
@@ -38,11 +30,6 @@ struct dt_info info = {
 	.initrd_end = 0,
 };
 
-/*
- * This is the main entry point of the kernel after head.S is done. This
- * function can (and will) assume that everything has been reset and that we can
- * start the whole thing.
- */
 __noreturn __kernel void start_kernel(void *dtb)
 {
 	printk("Welcome to FizzBuzz OS!\n");
diff --git a/kernel/trap.c b/kernel/trap.c
index 29f1c21..855b048 100644
--- a/kernel/trap.c
+++ b/kernel/trap.c
@@ -39,6 +39,11 @@ __kernel void time_out_in_one_second(void)
 	}
 }
 
+/*
+ * Exception handler. For this kernel, it only ensures that the 'write' system
+ * call is the one responsible for this exception and handles it; otherwise it
+ * will die.
+ */
 __kernel __always_inline void exception_handler(uint64_t cause)
 {
 	register char *message asm("a0");
-- 
cgit v1.2.3