arch: correct the riscv64 module-band comment, and separate two axes

The riscv64 header said modules sit ABOVE the image's _end. They do not:
MODULES_VADDR is _end - 2 GiB and MODULES_END is _start, so the band runs
below the image, the same side as s390. What actually differs between the
two is which end of the image the band's low edge is pinned to, and that is
what decides where MODULES_END_TO_TEXT_OFFSET lands — on the text base for
s390, on _end for riscv64, which is why module_text_bound then subtracts a
minimum image size there. Say that instead.

DIRECTMAP_STATIC and TEXT_TRACKS_DIRECTMAP answer different questions — one
gates the compile-time linear-map projections, the other whether a physical
bound may reach the virtual text base — but they hold the same value on all
twelve supported architectures, so no in-tree header demonstrates the
difference and neither can be inferred from the other by example. Record
both shapes that would separate them, and that the pair must be picked by
the question being asked.

Author: bcoles

src/include/kasld/api.h

@@ -237,7 +237,31 @@ __extension__ _Static_assert((unsigned long)KERNEL_PHYS_MAX >
 /* DIRECTMAP_STATIC and TEXT_TRACKS_DIRECTMAP must be declared by every arch
  * header — no defaults. Forcing each arch author to make the decision
  * explicitly is the whole point. See the arch-header contract banner above
- * for the 0/1 semantics. */
+ * for the 0/1 semantics.
+ *
+ * The two answer different questions, and both are read on their own:
+ * DIRECTMAP_STATIC decides whether phys_to_directmap_virt() and
+ * directmap_virt_to_phys() are defined at all, so it gates every compile-time
+ * linear-map projection; TEXT_TRACKS_DIRECTMAP decides whether a physical
+ * bound may propagate to the virtual text base.
+ *
+ * They nonetheless hold the SAME value on every architecture supported today,
+ * so no in-tree arch demonstrates the difference and neither can be inferred
+ * from the other by example. Pick by the question being asked, not by what a
+ * neighbouring header happens to say. The pair separates as soon as an arch
+ * fixes one of the two independently:
+ *
+ *   DIRECTMAP_STATIC=1, TEXT_TRACKS_DIRECTMAP=0 — the linear map sits at its
+ *   compile-time address while the image is randomized independently of it
+ *   (x86_64 built without RANDOMIZE_MEMORY is exactly this shape; KASLD models
+ *   x86_64 with DIRECTMAP_STATIC=0 because it cannot prove the build).
+ *
+ *   DIRECTMAP_STATIC=0, TEXT_TRACKS_DIRECTMAP=1 — text keeps a fixed offset
+ *   inside a linear map whose own base is randomized, so the offset is known
+ *   but neither endpoint is.
+ *
+ * Treating them as one flag would silently pick a side on whichever arch
+ * arrives first. */
 #ifndef DIRECTMAP_STATIC
 #error "arch header must define DIRECTMAP_STATIC (0 or 1)"
 #endif

src/include/kasld/arch/riscv64.h

@@ -96,11 +96,21 @@
 
 // Module region is anchored to kernel _end (shifts with KASLR)
 #define MODULES_RELATIVE_TO_TEXT 1
-// MODULES_BELOW_TEXT_START selects the s390-style "Case B" placement
-// (module band sits below the image). riscv64 puts modules ABOVE the
-// image's _end, so explicitly 0 — needed (not just implicit-zero) so
-// -Wundef does not fire at the `#if MODULES_BELOW_TEXT_START` sites in
-// orchestrator.c + rules/module_text_bound.c (those sites are gated on
+// MODULES_BELOW_TEXT_START selects which end of the image the band is
+// measured from, which decides what MODULES_END_TO_TEXT_OFFSET added to the
+// lowest module address yields. Both riscv64 and s390 place the band below
+// the image; they differ in what its low edge is pinned to:
+//
+//   s390 (1):     MODULES_END = round_down(_text), low edge = that - 2 GiB,
+//                 so lowest module + offset bounds the TEXT BASE directly.
+//   riscv64 (0):  MODULES_VADDR = _end - 2 GiB (MODULES_END = _start), so the
+//                 low edge tracks _end and lowest module + offset bounds _END;
+//                 module_text_bound then subtracts a minimum image size to
+//                 reach the text base.
+//
+// Explicit 0 rather than implicit-zero so -Wundef does not fire at the
+// `#if MODULES_BELOW_TEXT_START` sites in orchestrator.c +
+// rules/module_text_bound.c (those sites are gated on
 // MODULES_RELATIVE_TO_TEXT so they're only reachable on riscv64 + s390).
 #define MODULES_BELOW_TEXT_START 0
 #define MODULES_END_TO_TEXT_OFFSET 0x80000000ul /* 2 GiB */