From 63c81dedf317f749b452426394d070338d0e8cf8 Mon Sep 17 00:00:00 2001
From: Andrea Mazzoleni <amadvance@gmail.com>
Date: Sun, 23 Aug 2026 20:26:14 +0200
Subject: [PATCH] Clarify AES GFNI performance expectations and document RAID
 affine multiplication behavior

---
 raid/README     | 20 +++++++++++++-------
 raid/mktables.c |  2 +-
 raid/raid.h     | 31 ++++++++++++++++++++-----------
 3 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/raid/README b/raid/README
index 6f345b37..ca8566fe 100644
--- a/raid/README
+++ b/raid/README
@@ -122,15 +122,21 @@ Operating Modes and Polynomials
   RAID_MODE_CAUCHY_AES (Mode = 2)
     Uses Cauchy matrix with AES polynomial 0x1b (x^8 + x^4 + x^3 + x + 1,
     0x11b) and primitive generator g = 3. On CPUs supporting Intel GFNI,
-    generation and recovery are accelerated directly using VGF2P8MULB.
-    This native GFNI multiplication is typically faster than the affine GFNI
-    implementation required by the standard RAID polynomial. Parity data is
+    generation and recovery can use VGF2P8MULB directly for multiplication
+    in the AES field. This mode also provides a useful benchmark and
+    reference implementation for comparison with RAID_MODE_CAUCHY_RAID,
+    where fixed-coefficient multiplication in the 0x11d field is implemented
+    with VGF2P8AFFINEQB and precomputed affine matrices. Relative performance
+    depends on the CPU, backend, parity count, and workload. Parity data is
     incompatible with standard 0x11d polynomial arrays.
 
-  Both Cauchy modes use the same Extended Cauchy construction with coefficients
-  based on powers of their respective primitive generator. GFNI acceleration
-  is available for both fields: the RAID field uses affine transformations,
-  while the AES field uses the native GFNI multiplication instruction.
+  Both Cauchy modes use the same Extended Cauchy construction with
+  coefficients based on powers of their respective primitive generators.
+  GFNI acceleration is available for both fields: the RAID field uses
+  VGF2P8AFFINEQB for fixed-coefficient multiplication, while the AES field
+  can use native VGF2P8MULB. Neither instruction should be assumed to be
+  faster in general; relative performance is hardware and workload
+  dependent.
 
 
 Implementation Structure
diff --git a/raid/mktables.c b/raid/mktables.c
index 70e5c9bc..ac60e1f0 100644
--- a/raid/mktables.c
+++ b/raid/mktables.c
@@ -8,7 +8,7 @@
  * Galois field reduction polynomials.
  *
  * RAID_POLY_RAID - Standard RAID polynomial 0x1d (x^8 + x^4 + x^3 + x^2 + 1).
- * RAID_POLY_AES  - AES polynomial 0x1b (x^8 + x^4 + x^3 + x + 1) for GFNI acceleration.
+ * RAID_POLY_AES  - AES polynomial 0x1b (x^8 + x^4 + x^3 + x + 1), using generator g=3.
  */
 #define RAID_POLY_RAID 0x1d
 #define RAID_POLY_AES 0x1b
diff --git a/raid/raid.h b/raid/raid.h
index 01d84fee..934085e1 100644
--- a/raid/raid.h
+++ b/raid/raid.h
@@ -35,18 +35,22 @@
  *
  *   On CPUs supporting Intel GFNI, generation and recovery can use the
  *   vgf2p8mulb instruction, which performs GF(2^8) multiplication directly
- *   in hardware using this polynomial. This native multiplication is
- *   typically faster than the affine GFNI implementation required for the
- *   standard RAID polynomial.
+ *   using this polynomial.
+ *
+ *   This mode also provides a useful comparison with
+ *   RAID_MODE_CAUCHY_RAID, where multiplication by a fixed coefficient in
+ *   GF(2^8)/0x11d is implemented directly with vgf2p8affineqb and a
+ *   precomputed 8x8 GF(2) matrix. Relative performance depends on the CPU,
+ *   backend, parity count, and workload.
  *
  *   The trade-off is that parity data is not compatible with arrays using
  *   the standard 0x11d polynomial (g=2), so all data must be generated and
  *   recovered using the same operating mode.
  *
  * Both Cauchy modes can therefore use GFNI acceleration. The standard RAID
- * mode preserves compatibility by using affine GFNI transformations, while
- * the AES mode trades compatibility for the typically faster native GFNI
- * multiplication instruction.
+ * mode uses affine transformations for fixed-coefficient multiplication in
+ * the 0x11d field, while the AES mode can use native vgf2p8mulb
+ * multiplication in the 0x11b field.
  */
 
 /**
@@ -76,12 +80,17 @@
 #define RAID_MODE_VANDERMONDE_RAID 1
 
 /**
- * RAID mode supporting up to 6 parities using AES polynomial 0x1b (0x11b) and primitive generator g=3.
+ * RAID mode supporting up to 6 parities using AES polynomial 0x1b (0x11b)
+ * and primitive generator g=3.
  *
- * It has slightly lower performance than RAID_MODE_CAUCHY_RAID on CPUs without GFNI due
- * to the additional cost of generator g=3. On CPUs supporting GFNI, it uses native
- * VGF2P8MULB multiplication and is typically faster than the affine GFNI implementation
- * required by RAID_MODE_CAUCHY_RAID.
+ * It has slightly lower performance than RAID_MODE_CAUCHY_RAID on CPUs
+ * without GFNI due to the additional cost of generator g=3.
+ *
+ * On CPUs supporting GFNI, it uses native VGF2P8MULB multiplication. This
+ * mode also provides a useful benchmark and reference implementation for
+ * comparing native AES-field GFNI multiplication with the affine GFNI
+ * implementation used by RAID_MODE_CAUCHY_RAID. Relative performance
+ * depends on the CPU, backend, parity count, and workload.
  *
  * Parity data is incompatible with RAID_MODE_CAUCHY_RAID.
  */