Inline NEON prototype register cleanup

Author: eldryoth

CHANGELOG.md

@@ -34,6 +34,8 @@
 - Added `base64-ng-subtle` as an optional companion crate for projects that
   already admit `subtle` and want reviewed `ConstantTimeEq` comparisons for
   `base64-ng` buffers.
+- Inlined the test-only AArch64 NEON register cleanup macro into the prototype
+  path so callee-saved `v8..v15` are not restored by a separate helper frame.
 - Added a real non-dispatchable AVX2 fixed-block encode prototype for Standard
   and URL-safe alphabets. The prototype remains test-only and active runtime
   backend selection remains scalar-only.

docs/UNSAFE.md

@@ -745,9 +745,9 @@ Safety argument:
 - The AArch64 vector path remains test-only and non-dispatchable. Runtime
   acceleration is still blocked by the SIMD admission manifest.
 - Register-retention note: the AArch64 vector path loads caller bytes into NEON
-  state and calls `clear_neon_registers_for_test_prototype` before return. This
-  is retention reduction for the inactive prototype, not a formal
-  microarchitectural side-channel proof.
+  state and expands `clear_neon_registers_for_test_prototype!` directly inside
+  the prototype function before return. This is retention reduction for the
+  inactive prototype, not a formal microarchitectural side-channel proof.
 
 ### `encode_12_bytes_neon_aarch64_standard_family`
 
@@ -779,8 +779,8 @@ Unsafe operation:
 - `encode_standard_family_indices_neon` maps those indices to Standard or
   URL-safe alphabet bytes with NEON comparisons and bit selects.
 - `vst1q_u8` stores the 16 encoded bytes into the output buffer.
-- `clear_neon_registers_for_test_prototype` clears `v0` through `v31` before
-  return.
+- `clear_neon_registers_for_test_prototype!` clears `v0` through `v31` inside
+  the prototype function before return.
 - The local staging array is wiped with the crate cleanup primitive before the
   function returns.
 
@@ -828,11 +828,11 @@ Safety argument:
   six-bit Base64 value.
 - The helper is private to the test-only prototype path.
 
-### `clear_neon_registers_for_test_prototype`
+### `clear_neon_registers_for_test_prototype!`
 
 Location: `src/simd/mod.rs`
 
-Status: private helper for inactive AArch64 NEON test-only prototypes, not
+Status: private macro for inactive AArch64 NEON test-only prototypes, not
 dispatchable and not reachable from runtime backend selection.
 
 Purpose:
@@ -844,6 +844,9 @@ Preconditions:
 
 - Called only after the prototype has stored its output and no later NEON value
   is needed by the function.
+- Expanded directly inside the prototype function. It must not be moved to a
+  separate function because an AArch64 helper can save and restore callee-saved
+  `v8` through `v15`, undoing register clearing in the helper frame.
 
 Unsafe operation:
 
@@ -852,14 +855,14 @@ Unsafe operation:
 
 Safety argument:
 
-- The helper does not read or write memory.
-- The helper runs at the end of the inactive prototype path.
+- The macro does not read or write memory.
+- The macro expands at the end of the inactive prototype path.
 - Clobbered registers are declared to the compiler with explicit `out("vN")`
   operands.
 - This is best-effort register-retention reduction for test evidence, not a
   guarantee that historical register, stack, cache, or microarchitectural
   copies do not exist.
-- This helper clears all AArch64 vector registers for the reviewed prototype
+- This macro clears all AArch64 vector registers for the reviewed prototype
   sequence. It is not an admission claim for arbitrary future NEON code. Before
   NEON dispatch can become active, generated assembly must prove which vector
   registers carry caller-derived data and whether any callee-saved vector

src/simd/mod.rs

@@ -264,6 +264,85 @@ where
     (encode[62] == b'+' && encode[63] == b'/') || (encode[62] == b'-' && encode[63] == b'_')
 }
 
+#[cfg(all(test, target_arch = "aarch64"))]
+macro_rules! clear_neon_registers_for_test_prototype {
+    () => {{
+        // SAFETY: This test-only cleanup is expanded directly inside the
+        // prototype function after it stores its output. There is no separate
+        // helper frame whose ABI save/restore can undo `v8..v15` clearing. The
+        // explicit outputs tell the compiler every AArch64 vector register is
+        // clobbered while the assembly clears it. This is retention reduction
+        // for prototype evidence, not a formal microarchitectural proof.
+        core::arch::asm!(
+            "eor v0.16b, v0.16b, v0.16b",
+            "eor v1.16b, v1.16b, v1.16b",
+            "eor v2.16b, v2.16b, v2.16b",
+            "eor v3.16b, v3.16b, v3.16b",
+            "eor v4.16b, v4.16b, v4.16b",
+            "eor v5.16b, v5.16b, v5.16b",
+            "eor v6.16b, v6.16b, v6.16b",
+            "eor v7.16b, v7.16b, v7.16b",
+            "eor v8.16b, v8.16b, v8.16b",
+            "eor v9.16b, v9.16b, v9.16b",
+            "eor v10.16b, v10.16b, v10.16b",
+            "eor v11.16b, v11.16b, v11.16b",
+            "eor v12.16b, v12.16b, v12.16b",
+            "eor v13.16b, v13.16b, v13.16b",
+            "eor v14.16b, v14.16b, v14.16b",
+            "eor v15.16b, v15.16b, v15.16b",
+            "eor v16.16b, v16.16b, v16.16b",
+            "eor v17.16b, v17.16b, v17.16b",
+            "eor v18.16b, v18.16b, v18.16b",
+            "eor v19.16b, v19.16b, v19.16b",
+            "eor v20.16b, v20.16b, v20.16b",
+            "eor v21.16b, v21.16b, v21.16b",
+            "eor v22.16b, v22.16b, v22.16b",
+            "eor v23.16b, v23.16b, v23.16b",
+            "eor v24.16b, v24.16b, v24.16b",
+            "eor v25.16b, v25.16b, v25.16b",
+            "eor v26.16b, v26.16b, v26.16b",
+            "eor v27.16b, v27.16b, v27.16b",
+            "eor v28.16b, v28.16b, v28.16b",
+            "eor v29.16b, v29.16b, v29.16b",
+            "eor v30.16b, v30.16b, v30.16b",
+            "eor v31.16b, v31.16b, v31.16b",
+            out("v0") _,
+            out("v1") _,
+            out("v2") _,
+            out("v3") _,
+            out("v4") _,
+            out("v5") _,
+            out("v6") _,
+            out("v7") _,
+            out("v8") _,
+            out("v9") _,
+            out("v10") _,
+            out("v11") _,
+            out("v12") _,
+            out("v13") _,
+            out("v14") _,
+            out("v15") _,
+            out("v16") _,
+            out("v17") _,
+            out("v18") _,
+            out("v19") _,
+            out("v20") _,
+            out("v21") _,
+            out("v22") _,
+            out("v23") _,
+            out("v24") _,
+            out("v25") _,
+            out("v26") _,
+            out("v27") _,
+            out("v28") _,
+            out("v29") _,
+            out("v30") _,
+            out("v31") _,
+            options(nostack, preserves_flags)
+        );
+    }};
+}
+
 #[cfg(all(test, target_arch = "aarch64"))]
 #[target_feature(enable = "neon")]
 unsafe fn encode_12_bytes_neon_aarch64_standard_family<A>(input: &[u8; 12], output: &mut [u8; 16])
@@ -296,7 +375,7 @@ where
 
         let encoded = encode_standard_family_indices_neon::<A>(indices);
         vst1q_u8(output.as_mut_ptr(), encoded);
-        clear_neon_registers_for_test_prototype();
+        clear_neon_registers_for_test_prototype!();
     }
     crate::wipe_bytes(&mut staged);
 }
@@ -337,82 +416,5 @@ where
     vbslq_u8(slash, vdupq_n_u8(slash_char), encoded)
 }
 
-#[cfg(all(test, target_arch = "aarch64"))]
-unsafe fn clear_neon_registers_for_test_prototype() {
-    // SAFETY: This test-only cleanup runs after the prototype stores its
-    // output. The explicit outputs tell the compiler every AArch64 vector
-    // register is clobbered while the assembly clears it. This is retention
-    // reduction for prototype evidence, not a formal microarchitectural proof.
-    unsafe {
-        core::arch::asm!(
-            "eor v0.16b, v0.16b, v0.16b",
-            "eor v1.16b, v1.16b, v1.16b",
-            "eor v2.16b, v2.16b, v2.16b",
-            "eor v3.16b, v3.16b, v3.16b",
-            "eor v4.16b, v4.16b, v4.16b",
-            "eor v5.16b, v5.16b, v5.16b",
-            "eor v6.16b, v6.16b, v6.16b",
-            "eor v7.16b, v7.16b, v7.16b",
-            "eor v8.16b, v8.16b, v8.16b",
-            "eor v9.16b, v9.16b, v9.16b",
-            "eor v10.16b, v10.16b, v10.16b",
-            "eor v11.16b, v11.16b, v11.16b",
-            "eor v12.16b, v12.16b, v12.16b",
-            "eor v13.16b, v13.16b, v13.16b",
-            "eor v14.16b, v14.16b, v14.16b",
-            "eor v15.16b, v15.16b, v15.16b",
-            "eor v16.16b, v16.16b, v16.16b",
-            "eor v17.16b, v17.16b, v17.16b",
-            "eor v18.16b, v18.16b, v18.16b",
-            "eor v19.16b, v19.16b, v19.16b",
-            "eor v20.16b, v20.16b, v20.16b",
-            "eor v21.16b, v21.16b, v21.16b",
-            "eor v22.16b, v22.16b, v22.16b",
-            "eor v23.16b, v23.16b, v23.16b",
-            "eor v24.16b, v24.16b, v24.16b",
-            "eor v25.16b, v25.16b, v25.16b",
-            "eor v26.16b, v26.16b, v26.16b",
-            "eor v27.16b, v27.16b, v27.16b",
-            "eor v28.16b, v28.16b, v28.16b",
-            "eor v29.16b, v29.16b, v29.16b",
-            "eor v30.16b, v30.16b, v30.16b",
-            "eor v31.16b, v31.16b, v31.16b",
-            out("v0") _,
-            out("v1") _,
-            out("v2") _,
-            out("v3") _,
-            out("v4") _,
-            out("v5") _,
-            out("v6") _,
-            out("v7") _,
-            out("v8") _,
-            out("v9") _,
-            out("v10") _,
-            out("v11") _,
-            out("v12") _,
-            out("v13") _,
-            out("v14") _,
-            out("v15") _,
-            out("v16") _,
-            out("v17") _,
-            out("v18") _,
-            out("v19") _,
-            out("v20") _,
-            out("v21") _,
-            out("v22") _,
-            out("v23") _,
-            out("v24") _,
-            out("v25") _,
-            out("v26") _,
-            out("v27") _,
-            out("v28") _,
-            out("v29") _,
-            out("v30") _,
-            out("v31") _,
-            options(nostack, preserves_flags)
-        );
-    }
-}
-
 #[cfg(all(test, not(target_arch = "wasm32")))]
 mod tests;