[PATCH] dm raid: add takeover/reshape raid1 -> raid5 table line examples

[PATCH] dm raid: add takeover/reshape raid1 -> raid5 table line examples

[Heinz Mauelshagen]

Also enhance possible takeover/reshape information and do some reformatting.

Signed-off-by: Heinz Mauelshagen <heinzm@redhat.com>
---
 .../admin-guide/device-mapper/dm-raid.rst     | 49 +++++++++++++++----
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst
b/Documentation/admin-guide/device-mapper/dm-raid.rst
index 3554c44414e63..e11f107647709 100644
--- a/Documentation/admin-guide/device-mapper/dm-raid.rst
+++ b/Documentation/admin-guide/device-mapper/dm-raid.rst
@@ -20,10 +20,10 @@ The target is named "raid" and it accepts the
following parameters::
   raid0 RAID0 striping (no resilience)
   raid1 RAID1 mirroring
   raid4 RAID4 with dedicated last parity disk
-  raid5_n RAID5 with dedicated last parity disk supporting takeover
+  raid5_n RAID5 with dedicated last parity disk supporting takeover
from/to raid1
  Same as raid4

- - Transitory layout
+ - Transitory layout for takeover from/to raid1
   raid5_la RAID5 left asymmetric

  - rotating parity 0 with data continuation
@@ -48,8 +48,8 @@ The target is named "raid" and it accepts the
following parameters::
   raid6_n_6 RAID6 with dedicate parity disks

  - parity and Q-syndrome on the last 2 disks;
-  layout for takeover from/to raid4/raid5_n
-  raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
+  layout for takeover from/to raid0/raid4/raid5_n
+  raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk
supporting takeover from/to raid5

  - layout for takeover from raid5_la from/to raid6
   raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk
@@ -371,6 +371,7 @@ to safely enable discard support for RAID 4/5/6:

     'devices_handle_discards_safely'

+
 Takeover/Reshape Support
 ------------------------
 The target natively supports these two types of MDRAID conversions:
@@ -398,16 +399,44 @@ raid10 with near layout and even number of disks
-> raid0 (select any in-sync de
 Reshape:
 linear: not possible
 raid0:  not possible
-raid1: change number of mirrors
-raid4: add and remove stripes (minimum 3), change stripesize
-raid5: add and remove stripes (minimum 3, special case 2 for raid1
takeover), change rotating parity algorithms, change stripesize
-raid6: add and remove stripes (minimum 4), change rotating syndrome
algorithms, change stripesize
-raid10 near: add stripes (minimum 4), change stripesize, no stripe
removal possible, change to offset layout
+raid1:  change number of mirrors
+raid4:  add and remove stripes (minimum 3), change stripesize
+raid5:  add and remove stripes (minimum 3, special case 2 for raid1
takeover), change rotating parity algorithms, change stripesize
+raid6:  add and remove stripes (minimum 4), change rotating syndrome
algorithms, change stripesize
+raid10 near:   add stripes (minimum 4), change stripesize, no stripe
removal possible, change to offset layout
 raid10 offset: add stripes, change stripesize, no stripe removal
possible, change to near layout
-raid10 far: not possible
+raid10 far:    not possible

 Table line examples:

+### raid1 -> raid5
+#
+# 2 devices limitation in raid1.
+# raid5 personality is able to just map 2 like raid1.
+# Reshape after takeover to change to full raid5 layout
+
+  0 1960886272 raid raid1 3 0 region_size 2048 2 /dev/dm-0 /dev/dm-1
/dev/dm-2 /dev/dm-3
+
+# dm-0 and dm-2 are e.g. 4MiB large metadata devices, dm-1 and dm-3
have to be at least 1960886272 big.
+#
+# Table line to takeover to raid5
+
+  0 1960886272 raid raid5 3 0 region_size 2048 2 /dev/dm-0 /dev/dm-1
/dev/dm-2 /dev/dm-3
+
+# Add required out-of-place reshape space to the beginniong of the
given 2 data devices,
+# allocate another metadata/data device tuple with the same sizes for
the parity space
+# and zero the first 4K of the metadata device.
+#
+# Example table of the out-of-place reshape space addition for one
data device, e.g. dm-1
+
+  0 8192 linear 8:0 0 1960903888 #  <- must be free space segment
+  8192 1960886272 linear 8:0 0 2048 # previous data segment
+
+# Mapping table for e.g. raid5_rs reshape causing the size of the
raid device to double-fold once the reshape finishes.
+# Check the status output (e.g. "dmsetup status $RaidDev") for progess.
+
+  0 $((2 * 1960886272)) raid raid5 7 0 region_size 2048 data_offset
8192 delta_disk 1 2 /dev/dm-0 /dev/dm-1 /dev/dm-2 /dev/dm-3
+

 Version History
 ---------------
-- 
2.52.0

Re: [PATCH] dm raid: add takeover/reshape raid1 -> raid5 table line examples

[Bryn M. Reeves]

On Mon, Dec 01, 2025 at 03:40:39PM +0100, Heinz Mauelshagen wrote:
> Also enhance possible takeover/reshape information and do some reformatting.

Patch seems to be line-wrapped at 80 characters. Does not apply:

$ git apply /var/tmp/dm-raid-doc.patch
error: git diff header lacks filename information when removing 1 leading pathname component (line 9)

There seems to be some tabs/space issues also even after fixing the line
breaks:

patching file Documentation/admin-guide/device-mapper/dm-raid.rst
Hunk #1 FAILED at 20.
Hunk #2 FAILED at 48.
Hunk #3 FAILED at 371.
Hunk #4 FAILED at 398.
4 out of 4 hunks FAILED -- saving rejects to file Documentation/admin-guide/device-mapper/dm-raid.rst.rej

Regards,
Bryn.

> ---
>  .../admin-guide/device-mapper/dm-raid.rst     | 49 +++++++++++++++----
>  1 file changed, 39 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/admin-guide/device-mapper/dm-raid.rst
> b/Documentation/admin-guide/device-mapper/dm-raid.rst
> index 3554c44414e63..e11f107647709 100644
> --- a/Documentation/admin-guide/device-mapper/dm-raid.rst
> +++ b/Documentation/admin-guide/device-mapper/dm-raid.rst
> @@ -20,10 +20,10 @@ The target is named "raid" and it accepts the
> following parameters::
>    raid0 RAID0 striping (no resilience)
>    raid1 RAID1 mirroring
>    raid4 RAID4 with dedicated last parity disk
> -  raid5_n RAID5 with dedicated last parity disk supporting takeover
> +  raid5_n RAID5 with dedicated last parity disk supporting takeover
> from/to raid1
>   Same as raid4