From c1a78092c41f59708c321ebe4cab5daa67de984d Mon Sep 17 00:00:00 2001
From: Andrea Mazzoleni <amadvance@gmail.com>
Date: Mon, 24 Aug 2026 20:20:35 +0200
Subject: [PATCH] Fix RAID documentation accuracy

---
 raid/internal.h |  4 +++-
 raid/raid.c     | 16 +++++++---------
 raid/raid.h     | 11 +++++++----
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/raid/internal.h b/raid/internal.h
index 1ac13e63..f34f376f 100644
--- a/raid/internal.h
+++ b/raid/internal.h
@@ -44,7 +44,9 @@
 #include <string.h>
 
 /*
- * Inverse assert.
+ * Inverse assert used to check internal invariants and API preconditions.
+ * It is intentionally based on assert() so that all checks can be disabled
+ * with NDEBUG. When disabled, callers must satisfy all documented preconditions.
  */
 #define BUG_ON(a) assert(!(a))
 
diff --git a/raid/raid.c b/raid/raid.c
index b5d07407..c2aab876 100644
--- a/raid/raid.c
+++ b/raid/raid.c
@@ -26,12 +26,10 @@
  * and divisions by 2 in GF(2^8) are very fast. It is similar to ZFS RAIDZ3,
  * which uses powers of 4 instead of 2^-1.
  *
- * Unfortunately, this method does not extend beyond triple parity because
- * no choice of power coefficients guarantees solvable equations for all
- * combinations of missing disks. This is expected: a Vandermonde matrix,
- * used in this method, does not ensure that all submatrices are nonsingular
- * [2, Chap. 11, Problem 7], which is required for an MDS (Maximum Distance
- * Separable) code [2, Chap. 11, Theorem 8].
+ * Unfortunately, this method does not extend reliably beyond triple parity.
+ * Vandermonde matrices do not guarantee that all square submatrices are
+ * nonsingular, which is required to recover every possible combination of
+ * missing disks [2, Chap. 11, Problem 7][2, Chap. 11, Theorem 8].
  *
  * To overcome this limitation, a Cauchy matrix [3][4] is used for parity
  * computation. A Cauchy matrix ensures that all square submatrices are
@@ -121,9 +119,9 @@
  * data disks, one for each column. All the 377,342,351,231 square submatrices
  * are nonsingular, verified also by brute-force testing.
  *
- * This matrix can be extended to support any number of parities by simply
- * adding additional rows and removing one column for each new row to maintain
- * the condition i + j < 255.
+ * The construction can be extended to additional parity rows while reducing
+ * the maximum number of data columns accordingly. In GF(2^8), the Extended
+ * Cauchy construction requires data + parity <= 257
  * (See mktables.c for more details on how the matrix is generated.)
  *
  * The downside is that generic multiplications are required to compute the
diff --git a/raid/raid.h b/raid/raid.h
index a33e46bd..89360018 100644
--- a/raid/raid.h
+++ b/raid/raid.h
@@ -20,8 +20,8 @@
  *
  *   The polynomial used by the original RAID-6 specification and the
  *   Linux kernel RAID implementation, used with primitive generator g=2.
- *   Choosing this polynomial ensures on-disk compatibility with existing
- *   RAID arrays and interchange with other RAID implementations.
+ *   For identically ordered data blocks, the generated P/Q syndrome bytes
+ *   match the Linux RAID6 implementation.
  *
  *   On CPUs supporting Intel GFNI (Galois Field New Instructions),
  *   generation and recovery are accelerated with vgf2p8affineqb.
@@ -63,7 +63,7 @@
  *
  * Provides high performance on modern CPUs with SSSE3, AVX2, AVX-512, GFNI, or NEON support.
  * On GFNI CPUs, the standard RAID field is accelerated using affine transformations.
- * Ensures maximum compatibility with standard Linux RAID arrays.
+ * Uses Linux RAID6-compatible P/Q coefficients.
  *
  * This is the default mode set after calling raid_init().
  */
@@ -331,7 +331,10 @@ int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v);
  * first one encountered is returned. This function does not check that the
  * returned combination is unique.
  *
- * It uses a brute force method, and then the call can be expensive.
+ * This function is primarily intended as a reference implementation and to
+ * demonstrate how raid_check() can be used to locate failed blocks. It uses
+ * an exhaustive brute force search and is not intended for production use.
+ *
  * The expected execution time is proportional to the binomial coefficient
  * @np + @nd choose @np - 1, usually written as:
  *