From a0faa469f357a9eb2bf04c53f684f4300f9328ad Mon Sep 17 00:00:00 2001
From: Imbus <>
Date: Thu, 26 Jun 2025 03:25:22 +0200
Subject: [PATCH] More documentation in start.c

---
 start.c | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/start.c b/start.c
index 2ae4a1c..46c6bfc 100644
--- a/start.c
+++ b/start.c
@@ -1,19 +1,34 @@
+/*
+ * Number of CPU's For now, this is hard-coded here. It will likely be in a
+ * header, or dynamically discovered in the future
+ */
 #define NCPU 3
 
-#define UART ((char *)0x10000000)
+/* QEMU memory maps a UART device here. */
+#define UART_BASE ((char *)0x10000000)
 
-void uart_putc(char c) { *UART = c; }
+/** Send a single character to the UART device */
+void uart_putc(char c) { *UART_BASE = c; }
 
+/** Send a **NULL TERMINATED** string to the UART device */
 void uart_puts(const char *s) {
-    while (*s) {
-        uart_putc(*s++);
-    }
+    while (*s) uart_putc(*s++);
 }
 
-// Entry.S needs one stack per CPU.
-__attribute__((aligned(16))) char stack0[4096 * NCPU];
+/**
+ * Allocate one stack per CPU (hart).
+ * Each stack is 4096 bytes, aligned to 16 bytes for safety and performance.
+ * The entry assembly code will calculate the proper stack address for the
+ * current hart. For more info, read up on stack pointers and see: entry.S
+ */
+char stack0[4096 * NCPU] __attribute__((aligned(16)));
 
+/* This is where entry.S drops us of. All cores land here */
 void start() {
     uart_puts("Hello Neptune!\n");
-    while (1);
+
+    /* Here we will do a bunch of initialization steps */
+
+    // We should not arrive here, but if we do, hang in a while on wfi.
+    while (1) __asm__ volatile("wfi"); // (Wait For Interrupt)
 }