cycle: add --view-reclaim

installed-fresh --view-reclaim appends -DSNAP_VIEW_RECLAIM=1 after every
other monitor define. It is a monitor define only: no AuxKC, boot-arg
or loader change. docs/RUNNING.md describes it.
tools/test-edp-backlight.py's "appended last" check now lets this newer
define follow its own.

With next1's qualification flags plus the define the monitor is 459,904
bytes, 15,232 under the 464 KiB reservation; without it the monitor is
byte-identical to next1's (458,552 bytes, 16,584 under).
Hardware: not run.

docs/RUNNING.md

@@ -147,6 +147,7 @@ The flags fall into these groups:
 | Clocks and bandwidth | `--thermal-guard`, `--gpu-dvfs`, `--gpu-dvfs-ceiling`, `--cpu-dvfs`, `--ddr-vote`, `--llcc`, `--bw-probe` |
 | Storage | `--nvme-async`, `--nvme-converted` |
 | Wi-Fi | `--qcc2072-wifi`, `--qcc2072-auxkc`, `--qcc2072-auxkc-sha256` |
+| Kernel view pool | `--view-reclaim` |
 | Monitor performance | `--fine-locks`, `--root-cache-wide`, `--user-hw-walk`, `--fast-timer-irq`, `--fast-ipi`, `--lean-traps`, `--sptm-fine`, and others |
 | Kernel patches | `--kernel-sysreg-zero`, `--kernel-user-4k`, `--kernel-refmod-skip` ([KERNEL-PATCHES.md](KERNEL-PATCHES.md)) |
 
@@ -205,6 +206,18 @@ PWM-pin mode to DPCD control. `tools/survey-edp-aux.py` checks, read-only from
 q1n1, that the clocks and the AUX controller the call needs are on.
 `tools/test-edp-backlight.py` is the offline test.
 
+`--view-reclaim` gives the monitor `SNAP_VIEW_RECLAIM`. The kernel's per-CPU
+private page-table copies (`shadow/sprr-view.h`) hold 256 tables instead of
+128, and when a protecting RETYPE (read-only zone, TXM) finds them full, the
+copies that no selector2 or selector4 leaf needs any more are retired: every
+CPU's copies are synced back to the shared tables, published and invalidated
+before their pages are reused. Without it, a desktop session stops with exit 7
+(RETYPE to ROZONE refused) once the read-only zone has grown past about 120
+frames (installed-fresh-desktop-20261024-next1: after 1,104 s). The report's
+`VIEWRCL1` record (and `summary.json` `view_reclaim`) has the count, its
+high-water mark and the reclaims. `tools/test-view-reclaim.py` is the offline
+test.
+
 `--input-fnkeys FLAGS` (needs `--input`) adds the guest boot-arg
 `snap_i2c_fnkeys=FLAGS` for SnapI2CHID's keyboard Fn-key layer, which only a
 SnapI2CHID built with `PROFILE=desktop-fnkeys` has (`I2C_PROFILE=desktop-fnkeys

tools/cycle.py

@@ -283,6 +283,11 @@ def parse(argv=None):
                         'change switch a panel the firmware left in PWM-pin mode to DPCD control (level written first, '
                         'only the two mode bits changed, read back; on failure the old mode is restored and the '
                         'monitor stops)')
+    p.add_argument('--view-reclaim', action='store_true',
+                   help='opt-in kernel view pool (shadow/sprr-view.h): monitor define SNAP_VIEW_RECLAIM, 256 private '
+                        'kernel view tables instead of 128 and, when a protecting RETYPE finds them full, the copies no '
+                        'selector2/4 leaf needs any more retired (after an all-CPU sync, publication and TLBI) and their '
+                        'pages reused; report record VIEWRCL1. Monitor only')
     p.add_argument('--present-latch-us', type=int, default=None,
                    help='with --present-latch: guest boot-arg adreno_latch_us, the slack kept before row 0 (default '
                         '3000; 0 = the beam kext\'s aim before the vblank)')

tools/cycle_lib/installed_fresh.py

@@ -673,6 +673,10 @@ GPU_COHERENT_FORCE_DEFINE = '-DSNAP_ADRENO_COHERENT_FORCE=1'
 # flag adds. Monitor define only (no loader change). Appended after every earlier flag; off, the monitor is
 # byte-identical.
 EDP_BACKLIGHT_DEFINE = '-DSNAP_EDP_BACKLIGHT=1'
+# --view-reclaim (agents/view-reclaim): shadow/sprr-view.h SNAP_VIEW_RECLAIM, a 256-table kernel view pool and the
+# reclaim of copies no protected leaf needs when a protecting RETYPE finds it full (next1 stopped at 128, exit 7).
+# Monitor define only (no loader change). Appended after every earlier flag; off, the monitor is byte-identical.
+VIEW_RECLAIM_DEFINE = '-DSNAP_VIEW_RECLAIM=1'
 # agents/dvfs (FAILURE-MODES.md): opt-in governors on vCPU 0's locked tick, state at the end of root_ext (so
 # --root-cache-wide), report DVFSREP1 after the thermal record, restored at the stop; both need --thermal-guard (they
 # never write without the guard's readings). compat/cpu-dvfs.h SNAP_CPU_DVFS: SCMI PERF LEVEL_SET fastchannels of the
@@ -1096,6 +1100,8 @@ def variant_flags(sets, args, variant=None):
         flags.append(GPU_COHERENT_FORCE_DEFINE)
     if getattr(args, 'edp_backlight', False):
         flags.append(EDP_BACKLIGHT_DEFINE)
+    if getattr(args, 'view_reclaim', False):
+        flags.append(VIEW_RECLAIM_DEFINE)
     return flags
 
 

tools/test-edp-backlight.py

@@ -197,6 +197,8 @@ class Wiring(unittest.TestCase):
         src = (ROOT / 'tools/cycle_lib/installed_fresh.py').read_text()
         body = src[src.index('def variant_flags('):]
         body = body[:body.index('\n    return flags\n')]
+        # Only defines added after this one (tools/test-view-reclaim.py) may follow it.
+        body = body.replace("\n    if getattr(args, 'view_reclaim', False):\n        flags.append(VIEW_RECLAIM_DEFINE)", '')
         self.assertTrue(body.rstrip().endswith('flags.append(EDP_BACKLIGHT_DEFINE)'), 'the define is not appended last')