doc/rados: add blaum_roth coding guidance

Direct Ceph administrators using blaum_roth coding for erasure-coded
pools to change the default value of w=7 to a different value in order
to ensure that w+1 is prime.

This information was provided to the Ceph upstream by Benjamin Mare in
September of 2024.

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 6648d94aed5ff5643f50fcd4f3f07d97b846e885)

diff --git a/doc/rados/operations/erasure-code-jerasure.rst b/doc/rados/operations/erasure-code-jerasure.rst
index 8a0207748ae0e69ea4e6e707aeffa9a36f2e936b..c3717750754defa75cfcfed051c135497651ca2c 100644 (file)
--- a/doc/rados/operations/erasure-code-jerasure.rst
+++ b/doc/rados/operations/erasure-code-jerasure.rst
@@ -60,6 +60,24 @@ Where:
               *blaum_roth*, *liber8tion* are *RAID6* equivalents in
               the sense that they can only be configured with *m=2*. 
 
+              .. note:: When using ``blaum_roth`` coding, the default 
+                 word size of ``w=7`` is suboptimal because ``blaum_roth`` 
+                 works best when ``w+1`` is prime. When creating a new 
+                 erasure-code profile with ``technique=blaum_roth``, 
+                 set ``w`` to a number that is one integer less than a prime 
+                 number (for example, ``6``). See `Loic Dachary's 
+                 commit f51d21b to ceph/ceph <https://github.com/ceph/ceph/commit/f51d21b53d26d4f27c950cb1ba3f989e713ab325>`_ for information about
+                 why this default cannot be changed easily in the
+                 source code, and see `the second bullet point on
+                 page 29 of Plank and Greenan's "Jerasure: A Library
+                 in C Facilitating Erasure Coding for Storage
+                 Applications" <https://github.com/ceph/jerasure/blob/master/Manual.pdf>`_ for an unequivocal statement of the restriction that applies 
+                 to ``w`` when using Blaum-Roth coding.
+                 (Information about the proper value of ``w`` when
+                 using ``blaum_roth`` coding was provided to the
+                 Ceph upstream in September of 2024 by Benjamin
+                 Mare.)
+
 :Type: String
 :Required: No.
 :Default: reed_sol_van