From d89b3a05370a42aed8802b2b0ae28b3078bc2467 Mon Sep 17 00:00:00 2001
From: Axel Heider <axelheider@gmx.de>
Date: Sun, 6 Feb 2022 21:08:57 +0100
Subject: [PATCH] elfloader/risc-v: improve comments

Signed-off-by: Axel Heider <axelheider@gmx.de>
---
 elfloader-tool/src/arch-riscv/boot.c | 19 +++++++++++--------
 elfloader-tool/src/arch-riscv/crt0.S | 26 +++++++++++++-------------
 2 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/elfloader-tool/src/arch-riscv/boot.c b/elfloader-tool/src/arch-riscv/boot.c
index 48085b8e8..1d5b7f12f 100644
--- a/elfloader-tool/src/arch-riscv/boot.c
+++ b/elfloader-tool/src/arch-riscv/boot.c
@@ -144,14 +144,14 @@ uint64_t vm_mode = 0x9llu << 60;
 #error "Wrong PT level"
 #endif
 
-int hsm_exists = 0;
+int hsm_exists = 0; /* assembly startup code will initialise this */
 
 #if CONFIG_MAX_NUM_NODES > 1
 
 extern void secondary_harts(word_t hart_id, word_t core_id);
 
 int secondary_go = 0;
-int next_logical_core_id = 1;
+int next_logical_core_id = 1; /* incremented by assembly code  */
 int mutex = 0;
 int core_ready[CONFIG_MAX_NUM_NODES] = { 0 };
 static void set_and_wait_for_ready(word_t hart_id, word_t core_id)
@@ -162,12 +162,15 @@ static void set_and_wait_for_ready(word_t hart_id, word_t core_id)
     core_ready[core_id] = 1;
     __atomic_store_n(&mutex, 0, __ATOMIC_RELEASE);
 
-    /* Wait untill all cores are go */
+    /* Wait until all cores are go */
     for (int i = 0; i < CONFIG_MAX_NUM_NODES; i++) {
-        while (__atomic_load_n(&core_ready[i], __ATOMIC_RELAXED) == 0) ;
+        while (__atomic_load_n(&core_ready[i], __ATOMIC_RELAXED) == 0) {
+            /* busy waiting loop */
+        }
     }
 }
-#endif
+
+#endif /* CONFIG_MAX_NUM_NODES > 1 */
 
 static inline void sfence_vma(void)
 {
@@ -234,7 +237,7 @@ static int run_elfloader(UNUSED word_t hart_id, void *bootloader_dtb)
     }
 
     set_and_wait_for_ready(hart_id, 0);
-#endif
+#endif /* CONFIG_MAX_NUM_NODES > 1 */
 
     printf("Enabling MMU and paging\n");
     enable_virtual_memory();
@@ -250,7 +253,7 @@ static int run_elfloader(UNUSED word_t hart_id, void *bootloader_dtb)
                                                   ,
                                                   hart_id,
                                                   0
-#endif
+#endif /* CONFIG_MAX_NUM_NODES > 1 */
                                                  );
 
     /* We should never get here. */
@@ -287,7 +290,7 @@ void secondary_entry(word_t hart_id, word_t core_id)
                                                  );
 }
 
-#endif
+#endif /* CONFIG_MAX_NUM_NODES > 1 */
 
 void main(word_t hart_id, void *bootloader_dtb)
 {
diff --git a/elfloader-tool/src/arch-riscv/crt0.S b/elfloader-tool/src/arch-riscv/crt0.S
index 74e39a6e8..2814abb61 100644
--- a/elfloader-tool/src/arch-riscv/crt0.S
+++ b/elfloader-tool/src/arch-riscv/crt0.S
@@ -107,28 +107,28 @@ hsm_switch_hart:
   mv a0, s0 /* restore a0 to hold hart ID passed by OpenSBI */
   j secondary_harts
 
-
-_start1: /* a0 must hold current hard ID passed by bootloader */
-         /* a1 must hold dtb address passed by bootloader */
+/*----------------------------------------------------------------------------*/
+_start1:
+/* This is basically an asm wrapper to jump to the C code at main(). The
+ * registers are already set up with the perameters for the C code:
+ *   a0 holds current hard ID passed by bootloader
+ *   a1 holds dtb address passed by bootloader
+ * All that is left to be done here is setting up the registers gp and sp to
+ * have a proper C environment. The hart we are running on now could be a
+ * different HART to the one that we have been on in _start. The original hart
+ * we came from will get a different stack in secondary_harts.
+ */
 .option push
 .option norelax
 1:auipc gp, %pcrel_hi(__global_pointer$)
   addi  gp, gp, %pcrel_lo(1b)
 .option pop
-
-  /* Attach the stack to sp before calling any C functions */
-  /* This HART may be a different HART to the one that started at _start
-   * If we've switched HARTs then the other HART will get a different stack
-   * region in secondary_harts. */
   la sp, (elfloader_stack + BIT(CONFIG_KERNEL_STACK_BITS))
-  /* The C code expects the registers to be set up as:
-   *   a0 = hart id
-   *   a1 = dtb
-   */
+  /* Jump via a register, as this can cover a bigger range. */
   la s0, main
   jr s0
 
-
+/*----------------------------------------------------------------------------*/
 .global secondary_harts
 secondary_harts: