regions: rename REGION_MODULE_REGION to REGION_MODULE_BAND

The pair read backwards: "module_region" says region twice and looks like
the more specific of the two, when it is the weaker one — the band itself,
or an address merely assumed to be a module because it fell inside it. The
codebase already calls that concept a band everywhere in prose, and the
MODULES_BAND_EXACT arch axis uses the same word, so the enum was the odd
one out. The wire name follows: module_region -> module_band.

kasld_addr_is_module_region() becomes kasld_addr_is_module_band(), and its
comment gains the distinction it was missing: a source that already knows
it read a module's address uses the predicate as a sanity filter and still
emits REGION_MODULE, while a source holding a bare pointer uses it to
classify and must emit REGION_MODULE_BAND.

Two comments were stale rather than merely misnamed. The region note said
module_text_bound "reads both" and that its arches have a narrow
text-relative band; neither is true — it reads REGION_MODULE only, and the
band contains the whole kernel-text range on both riscv64 and s390. And the
wire-token parse was documented against "longest module_region = 13" when
virt_page_offset and efi_loader_image are 16.

Author: bcoles

src/components/dmesg_backtrace.c

@@ -105,7 +105,7 @@ static int in_directmap_range(unsigned long val) {
   if (val >= KERNEL_VIRT_TEXT_MIN)
     return 0;
 #if MODULES_START >= PAGE_OFFSET
-  if (kasld_addr_is_module_region(val))
+  if (kasld_addr_is_module_band(val))
     return 0;
 #endif
   return 1;

src/components/dmesg_mem_init_kernel_layout.c

@@ -184,7 +184,7 @@ static const struct layout_entry entries[] = {
     {"lowmem  : 0x", KASLD_TYPE_VIRT, "kernel lowmem start", REGION_DIRECTMAP,
      KERNEL_VIRT_VAS_START, KERNEL_VIRT_VAS_END, LK_BASE},
     {"modules : 0x", KASLD_TYPE_VIRT, "kernel modules start",
-     REGION_MODULE_REGION, MODULES_START, MODULES_END, LK_BASE},
+     REGION_MODULE_BAND, MODULES_START, MODULES_END, LK_BASE},
     {"memory  : 0x", KASLD_TYPE_VIRT, "kernel memory start", REGION_DIRECTMAP,
      KERNEL_VIRT_VAS_START, KERNEL_VIRT_VAS_END, LK_BASE},
     /* Range extractions (lo,hi). One needle per print-format dialect:
@@ -264,7 +264,7 @@ static void emit_base(int idx, unsigned long addr) {
   kasld_info("%s: %lx", entries[idx].display, addr);
 
 #if KERNEL_VIRT_VAS_START /* vacuous where VAS_START is 0 (s390) */
-  if ((region == REGION_DIRECTMAP || region == REGION_MODULE_REGION) &&
+  if ((region == REGION_DIRECTMAP || region == REGION_MODULE_BAND) &&
       addr < (unsigned long)KERNEL_VIRT_VAS_START)
     kasld_err("warning: %s %lx below configured KERNEL_VIRT_VAS_START %lx",
               entries[idx].display, addr, (unsigned long)KERNEL_VIRT_VAS_START);

src/components/perf_ksymbol_leak.c

@@ -23,7 +23,7 @@
 // perf_event_paranoid<=0 for unprivileged users (or CAP_PERFMON).
 //
 // The component subscribes, polls for a short window, and emits one
-// REGION_MODULE_REGION observation per ksymbol register record. The kernel
+// REGION_MODULE_BAND observation per ksymbol register record. The kernel
 // virtual addresses BPF JIT pages, kprobe OOL pages, and ftrace trampolines
 // occupy all live in the module region on every supported arch.
 // Notification-driven: yields nothing if no BPF / kprobe / ftrace registration
@@ -223,16 +223,16 @@ static int drain_ring(struct perf_event_mmap_page *meta, const char *ring,
       /* Only emit an address inside the module window. A KSYMBOL record is a
        * BPF-JIT / kprobe-OOL / ftrace-trampoline allocation, normally in the
        * module region; one outside it (a separate bpf/vmalloc region on some
-       * configs) must be DROPPED, not tagged REGION_MODULE_REGION — that would
+       * configs) must be DROPPED, not tagged REGION_MODULE_BAND — that would
        * feed module_text_bound a bogus text-base bound on
        * MODULES_RELATIVE_TO_TEXT arches (riscv64/s390). Mirrors the window
        * check perf_text_poke_leak already applies. */
       if (!(k->flags & KSYM_FLAG_UNREGISTER) && k->addr != 0 &&
-          kasld_addr_is_module_region((unsigned long)k->addr)) {
+          kasld_addr_is_module_band((unsigned long)k->addr)) {
         kasld_found("ksymbol: addr=0x%lx len=%u type=%u name=%s",
                     (unsigned long)k->addr, k->len, k->ksym_type,
                     name_copy[0] ? name_copy : "(anon)");
-        kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION,
+        kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND,
                             (unsigned long)k->addr,
                             name_copy[0] ? name_copy : NULL, CONF_PARSED);
         emitted++;

src/components/perf_text_poke_leak.c

@@ -43,7 +43,7 @@
 // each leaked address is emitted only under the region it actually falls in: a
 // core-.text address as a KERNEL_TEXT interior sample (bounds the image base
 // from above), a module-region address (ftrace trampoline / kprobe page) as
-// REGION_MODULE_REGION; anything outside both windows is skipped.
+// REGION_MODULE_BAND; anything outside both windows is skipped.
 //
 // Requires:
 // - kernel.perf_event_paranoid <= 0 (or CAP_PERFMON / CAP_SYS_ADMIN)
@@ -255,7 +255,7 @@ static void drain_ring(struct perf_event_mmap_page *meta, const char *ring,
         if (acc->text_n == 0 || addr > acc->text_hi)
           acc->text_hi = addr;
         acc->text_n++;
-      } else if (addr != 0 && kasld_addr_is_module_region(addr)) {
+      } else if (addr != 0 && kasld_addr_is_module_band(addr)) {
         if (acc->mod_n == 0 || addr < acc->mod_lo)
           acc->mod_lo = addr;
         if (acc->mod_n == 0 || addr > acc->mod_hi)
@@ -408,11 +408,11 @@ int main(int argc, char *argv[]) {
   if (acc.mod_n) {
     kasld_found("%d module-region poke(s); lowest 0x%lx highest 0x%lx",
                 acc.mod_n, acc.mod_lo, acc.mod_hi);
-    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION, acc.mod_lo, NULL,
+    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND, acc.mod_lo, NULL,
                         CONF_PARSED);
     if (acc.mod_hi != acc.mod_lo)
-      kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION, acc.mod_hi,
-                          NULL, CONF_PARSED);
+      kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND, acc.mod_hi, NULL,
+                          CONF_PARSED);
   }
   return 0;
 }

src/components/proc_modules.c

@@ -79,7 +79,7 @@ static struct module_range get_addr_proc_modules(void) {
     if (!module_addr)
       continue;
 
-    if (kasld_addr_is_module_region(module_addr)) {
+    if (kasld_addr_is_module_band(module_addr)) {
       if (!range.lo || module_addr < range.lo)
         range.lo = module_addr;
       if (module_addr > range.hi)
@@ -109,7 +109,7 @@ int main(void) {
    * The component aggregates them into a min/max range — both endpoints
    * are within the module region. (A future version could enumerate
    * each module by name with kasld_result().) */
-  /* REGION_MODULE, not REGION_MODULE_REGION: each address is a loaded
+  /* REGION_MODULE, not REGION_MODULE_BAND: each address is a loaded
    * module's own base, read from a per-module record — the region is known
    * structurally, not inferred from the address falling in a band. That is
    * what lets module_text_bracket consume it on arches whose band is a wide

src/components/sysfs_iscsi_transport_handle.c

@@ -204,7 +204,7 @@ static enum handle_read read_transport_handle(const char *transport,
 
 /* The struct iscsi_transport lives in MODULE memory when the driver is built as
  * a module (the usual case), or in the kernel image .data section when built
- * in. Classify by range so a module pointer is tagged REGION_MODULE_REGION, not
+ * in. Classify by range so a module pointer is tagged REGION_MODULE_BAND, not
  * an image region: a KERNEL_DATA tag on a module pointer feeds
  * image_size_text_data_gap a bogus (>1 GiB) text..data gap, which pushes the
  * Q_VIRT_IMAGE_BASE ceiling below the true base and excludes it.
@@ -216,12 +216,12 @@ static enum handle_read read_transport_handle(const char *transport,
  * range, so a text-first order would tag real module pointers KERNEL_DATA and
  * reproduce exactly the ceiling bug described above. Range classification
  * cannot separate the two where the ranges overlap; what makes the ambiguity
- * harmless is that REGION_MODULE_REGION no longer reaches any rule that moves
+ * harmless is that REGION_MODULE_BAND no longer reaches any rule that moves
  * a text base (module_text_bound and module_text_bracket both require
  * REGION_MODULE), so a mis-tag here is presentational. */
 static void emit_iscsi_transport(unsigned long addr, const char *name) {
-  if (kasld_addr_is_module_region(addr))
-    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION, addr, name,
+  if (kasld_addr_is_module_band(addr))
+    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND, addr, name,
                         CONF_PARSED);
   else if (kasld_addr_is_kernel_text(addr))
     kasld_result_sample(KASLD_TYPE_VIRT, REGION_KERNEL_DATA, addr, name,

src/components/sysfs_module_sections.c

@@ -81,7 +81,7 @@ static unsigned long read_module_text(char *path) {
 
   addr = strtoul(buff, &endptr, 16);
 
-  if (addr && kasld_addr_is_module_region(addr))
+  if (addr && kasld_addr_is_module_band(addr))
     return addr;
 
   return 0;
@@ -138,7 +138,7 @@ int main(void) {
     return 0;
   }
 
-  /* REGION_MODULE, not REGION_MODULE_REGION: these are section addresses read
+  /* REGION_MODULE, not REGION_MODULE_BAND: these are section addresses read
    * from a named module's own sysfs directory, so the region is known
    * structurally rather than inferred from the address falling in a band —
    * the provenance module_text_bracket requires (see api.h). */

src/components/tracefs_printk_formats.c

@@ -99,7 +99,7 @@ int main(int argc, char **argv) {
       if (!have_text || a > text_hi)
         text_hi = a;
       have_text = 1;
-    } else if (kasld_addr_is_module_region(a)) {
+    } else if (kasld_addr_is_module_band(a)) {
       if (!have_mod || a < mod_lo)
         mod_lo = a;
       if (!have_mod || a > mod_hi)
@@ -129,10 +129,10 @@ int main(int argc, char **argv) {
   }
   if (have_mod) {
     kasld_info("module format addresses: 0x%lx-0x%lx", mod_lo, mod_hi);
-    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION, mod_lo,
+    kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND, mod_lo,
                         "printk_fmt", CONF_PARSED);
     if (mod_hi != mod_lo)
-      kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_REGION, mod_hi,
+      kasld_result_sample(KASLD_TYPE_VIRT, REGION_MODULE_BAND, mod_hi,
                           "printk_fmt", CONF_PARSED);
   }
   return 0;

src/components/zfs_dbgmsg.c

@@ -99,8 +99,8 @@ static int emit_addr(unsigned long addr) {
   enum kasld_region region;
   if (kasld_addr_is_kernel_text(addr))
     region = REGION_KERNEL_TEXT;
-  else if (kasld_addr_is_module_region(addr))
-    region = REGION_MODULE_REGION;
+  else if (kasld_addr_is_module_band(addr))
+    region = REGION_MODULE_BAND;
   else if (kasld_addr_is_directmap(addr))
     region = REGION_DIRECTMAP;
   else if (kasld_addr_is_kernel_vas(addr))

src/include/kasld/api.h

@@ -93,7 +93,7 @@ static inline int kasld_mul_ovf(unsigned long a, unsigned long b,
  *   the relocatable range; a static band describes the region only when KASLR
  *   is off. Widening far enough to do that can leave range-classification
  *   vacuous on an arch -- that is the correct trade, and it is contained by
- *   the REGION_MODULE / REGION_MODULE_REGION provenance split (see the region
+ *   the REGION_MODULE / REGION_MODULE_BAND provenance split (see the region
  *   table), never by narrowing the union back.
  *
  * - MODULES_RELATIVE_TO_TEXT: 1 if the module region shifts with KASLR text.
@@ -652,15 +652,20 @@ static inline int kasld_addr_in_range(unsigned long long addr,
   return addr >= lo && addr <= hi;
 }
 
-/* Predicate: is `va` plausibly inside the kernel module region on this arch?
+/* Predicate: is `va` plausibly inside the kernel module BAND on this arch?
  *
  * Wraps the MODULES_START/END validation union (see the CONTRACT in the
- * arch-header contract banner above).
- * Used by components that classify leaked addresses as module-region
- * (proc_modules, sysfs_module_sections, dmesg-parsers). Centralising the
- * check here means the per-arch widening / future per-version handling
- * lives in one place rather than four. */
-static inline int kasld_addr_is_module_region(unsigned long va) {
+ * arch-header contract banner above). Centralising the check here means the
+ * per-arch widening / future per-version handling lives in one place.
+ *
+ * Two different uses, and the difference decides the region tag. A source that
+ * already KNOWS it read a module's address (proc_modules,
+ * sysfs_module_sections) uses this only as a sanity filter and still emits
+ * REGION_MODULE. A source holding a bare pointer uses it to CLASSIFY, and must
+ * emit REGION_MODULE_BAND — membership in the band is not evidence that an
+ * address is a module, since the band overlaps other regions on several arches
+ * (see the region note by the region table). */
+static inline int kasld_addr_is_module_band(unsigned long va) {
   return kasld_addr_in_range(va, (unsigned long)MODULES_START,
                              (unsigned long)MODULES_END);
 }
@@ -921,24 +926,29 @@ enum kasld_confidence {
   X(REGION_KERNEL_DATA, "kernel_data", "data", K_OPEN)                         \
   X(REGION_KERNEL_BSS, "kernel_bss", "bss", K_OPEN)                            \
   X(REGION_KERNEL_IMAGE, "kernel_image", "text", K_OPEN)                       \
-  /* The two module regions differ by PROVENANCE, not by address range —   */  \
-  /* both are validated against the same [MODULES_START, MODULES_END] band.*/  \
-  /* MODULE: the source structurally KNOWS the address belongs to a loaded */  \
-  /* module (it read a module's own address — /proc/modules, a sysfs      */   \
-  /* per-module sections entry, a named symbol in a known module).        */   \
-  /* MODULE_REGION: the band itself, OR an address merely CLASSIFIED as    */  \
-  /* module because it fell inside the band (dmesg parsers, opportunistic  */  \
-  /* pointer leaks, perf JIT/trampoline records).                          */  \
-  /* The distinction is load-bearing on MODULES_BRACKET_TEXT arches, where */  \
-  /* the band is a wide multi-layout union that overlaps other regions:    */  \
-  /* on arm64 a VA_BITS=48 direct map starts at MODULES_START, so a        */  \
-  /* range-classified kmalloc pointer would otherwise bound the text base  */  \
-  /* ~128 TiB below the truth. module_text_bracket therefore reads MODULE  */  \
-  /* only; module_text_bound (whose arches have a narrow text-relative     */  \
-  /* band) reads both. Emit MODULE_REGION when in any doubt — it is the    */  \
-  /* weaker, always-safe tag.                                              */  \
+  /* The two module regions differ by PROVENANCE, not by address range —    */ \
+  /* both are validated against the same [MODULES_START, MODULES_END] band. */ \
+  /* MODULE: the source structurally KNOWS the address belongs to a loaded  */ \
+  /* module (it read a module's own address — /proc/modules, a sysfs        */ \
+  /* per-module sections entry, a named symbol in a known module).          */ \
+  /* MODULE_BAND: the band itself, OR an address merely CLASSIFIED as a     */ \
+  /* module because it fell inside the band (dmesg parsers, opportunistic   */ \
+  /* pointer leaks, perf JIT/trampoline records).                           */ \
+  /*                                                                        */ \
+  /* The distinction is load-bearing wherever a module address moves a TEXT */ \
+  /* base, because the band overlaps other regions on every such arch: on   */ \
+  /* arm64 a VA_BITS=48 direct map starts at MODULES_START, and on riscv64  */ \
+  /* and s390 the band contains the whole kernel-text range. A              */ \
+  /* range-classified address is then indistinguishable from a module one.  */ \
+  /* So module_text_bracket AND module_text_bound both read MODULE only.    */ \
+  /*                                                                        */ \
+  /* MODULE_BAND is read where the claim is about the REGION rather than a  */ \
+  /* module: the rendered band, and (with POS_BASE) the kernel's own        */ \
+  /* "modules : 0x..." layout line, which pins Q_MODULE_BASE.               */ \
+  /*                                                                        */ \
+  /* Emit MODULE_BAND when in any doubt — it is the weaker, always-safe tag.*/ \
   X(REGION_MODULE, "module", "module", K_MODULE)                               \
-  X(REGION_MODULE_REGION, "module_region", "module", K_MODULE)                 \
+  X(REGION_MODULE_BAND, "module_band", "module", K_MODULE)                     \
   /* ---- Direct-map / virtual landmarks --------------------------------- */  \
   X(REGION_DIRECTMAP, "directmap", "directmap", K_VIRT)                        \
   X(REGION_PAGE_OFFSET, "virt_page_offset", "pageoffset", K_PAGEOFFSET)        \