cleanup: align comments and headers with the code they describe

A sweep of comments, header blocks, and explain strings had drifted from
the code they describe. No behavior changes.

Author: bcoles

src/components/bcm_msg_head_struct.c

@@ -11,7 +11,7 @@
 //   Data leaked:      kernel stack pointer (uninitialized struct padding)
 //   Kernel subsystem: net/can — CAN BCM (net/can/bcm.c)
 //   Data structure:   struct bcm_msg_head (4-byte padding hole after flags)
-//   Address type:     virtual (kernel stack)
+//   Address type:     virtual (kernel text, recovered from stack padding)
 //   Method:           heuristic
 //   CVE:              CVE-2021-34693
 //   Patched:          v5.12 (multiple commits)

src/components/boot_config.c

@@ -3,7 +3,8 @@
 // Check kernel config for CONFIG_RELOCATABLE, CONFIG_RANDOMIZE_BASE,
 // and CONFIG_PAGE_OFFSET (32-bit vmsplit).
 //
-// Detection component — does not leak an address.
+// Detection component; on 32-bit vmsplit arches also emits the parsed
+// CONFIG_PAGE_OFFSET as the page-offset base.
 //   Purpose: reads /boot/config-$(uname -r) to determine whether
 //   CONFIG_RANDOMIZE_BASE is set (KASLR compiled in) and what the
 //   32-bit vmsplit (CONFIG_PAGE_OFFSET) is. Readable when /boot is

src/components/dmesg_backtrace.c

@@ -276,8 +276,8 @@ static void scan_directmap(const char *line, struct btctx *c) {
  * text; tp/sp are not, but LoongArch is coupled (text and data share the
  * 0x9000... window) so they cannot be excluded by address range — hence the two
  * registers are read positionally by field name rather than range-scanned.
- * Always compiled (so it is unit-testable); only invoked on LoongArch, where
- * the marked-unused attribute is moot. */
+ * Always compiled; only invoked on LoongArch, where the marked-unused
+ * attribute is moot. */
 __attribute__((unused)) static void
 parse_loongarch_pc_ra(const char *line, unsigned long *pc, unsigned long *ra) {
   *pc = 0;

src/components/dmesg_cma_reserved.c

@@ -176,8 +176,7 @@ int main(void) {
   }
 
   /* CMA pools are firmware/kernel-reserved memory carved out of DRAM —
-   * each is emitted as its own RESERVED_MEM band in the parse callbacks. The
-   * directmap projection below derives one virtual landmark from the lowest. */
+   * each is emitted as its own RESERVED_MEM band in the parse callbacks. */
   kasld_info("lowest reserved pool:  0x%016lx", r.lo);
   if (r.hi && r.hi != r.lo)
     kasld_info("highest reserved pool: 0x%016lx", r.hi);

src/components/dmesg_crashkernel.c

@@ -184,8 +184,7 @@ int main(void) {
   if (r.hi && r.hi != r.lo)
     kasld_info("crashkernel end:   0x%016lx", r.hi);
 
-  /* Per-region forbidden bands are emitted in the parse callbacks; the
-   * directmap projection below derives one virtual landmark from the lowest. */
+  /* Per-region forbidden bands are emitted in the parse callbacks. */
 
   return 0;
 }

src/components/dmesg_free_reserved_area.c

@@ -73,7 +73,7 @@ KASLD_META("method:parsed\n"
            "patch:v4.10\n");
 
 /* Parse a "Freeing <name> memory: <size>K (<start> - <end>)" line.
- * Emits a kasld_result() for the start address. Returns 1 on success. */
+ * Emits a kasld_result_sample() for the start address. Returns 1 on success. */
 static int on_match(const char *line, void *ctx) {
   (void)ctx;
   const char *name_start;

src/components/dmesg_reserved_mem.c

@@ -124,8 +124,7 @@ int main(void) {
   kasld_info("lowest reserved mem physical address:  0x%016lx", r.lo);
   kasld_info("highest reserved mem physical address: 0x%016lx", r.hi);
 
-  /* Per-region forbidden bands are emitted in on_match(); the directmap
-   * projection below derives one virtual landmark from the lowest region. */
+  /* Per-region forbidden bands are emitted in on_match(). */
 
   return 0;
 }

src/components/dmesg_reserved_mem_opensbi.c

@@ -23,7 +23,8 @@
 //   Data leaked:      physical DRAM base address (OpenSBI M-mode reservation)
 //   Kernel subsystem: drivers/of/fdt_reserved_mem — mmode_resv0 DT node
 //   Data structure:   reserved memory node (physical address of DRAM base)
-//   Address type:     physical (DRAM)
+//   Address type:     physical (DRAM); on linear-map-coupled RISC-V also a
+//                     derived virtual kernel-image landmark
 //   Method:           parsed (dmesg string)
 //   Status:           unfixed (printed unconditionally on RISC-V with OpenSBI)
 //   Access check:     do_syslog() → check_syslog_permissions(); gated by

src/components/function_order_fingerprint.c

@@ -60,7 +60,7 @@ static const char *const probe_tails[] = {
 /* Minimums below which the span is statistically meaningless -> abstain. */
 #define MIN_PROBES 6
 #define MIN_T_SYMS 1000
-#define REORDER_RATIO 0.30 /* span/total_T at/above which we flag reordered */
+#define REORDER_RATIO 0.30 /* span/total_T threshold for the reordered flag */
 
 KASLD_EXPLAIN(
     "Measures how far the kernel/sys.c syscall wrappers are scattered across "

src/components/kernfs_ns_hash.c

@@ -315,7 +315,7 @@ static uint32_t base_offset_lookup(void) {
 /* Scan candidate bases b in [lo, hi] step `step`, testing salt = b + off, and
  * return 1 with the UNIQUE matching salt in *salt; 0 if none or ambiguous.
  * A wrong candidate cannot reproduce every cookie, so a lone survivor is the
- * true salt. Split out so the recovery is testable over a bounded window. */
+ * true salt. Split out so the recovery runs over a bounded window. */
 static int kernfs_scan(const struct kernfs_pair *pr, int n, unsigned long lo,
                        unsigned long hi, unsigned long step, uint32_t off,
                        unsigned long *salt) {