btrfs-progs: docs: copy more contents from wiki

- Tree-checker - about reporting problems
- Seeding-device - chained seeding devices
- RAID56 - write hole, fixed stripe width

Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/Tree-checker.rst

@@ -74,3 +74,12 @@ detector of faulty RAM).
 The capabilities of tree checker have been improved over time and it's possible
 that a filesystem created on an older kernel may trigger warnings or fail some
 checks on a new one.
+
+Reporting problems
+------------------
+
+In many cases the bug is caused by hardware and cannot be automatically fixed
+by *btrfs check --repair*, so do not try that without being adviced to. Even if
+the error is unfixable it's useful to report it, either to validate the cause
+but also to give more ideas how to improve the tree checker.  Please consider
+reporting it to the mailing list *linux-btrfs@vger.kernel.org*.

Documentation/btrfs-man5.rst

@@ -393,7 +393,17 @@ degrade the performance. The workaround is to start it on each device
 separately. Due to that the device stats may not match the actual state and
 some errors might get reported multiple times.
 
-The *write hole* problem.
+The *write hole* problem. An unclean shutdown could leave a partially written
+stripe in a state where the some stripe ranges and the parity are from the old
+writes and some are new. The information which is which is not tracked. Write
+journal is not implemented. Alternatively a full read-modify-write would make
+sure that a full stripe is always written, avoiding the write hole completely,
+but performance in that case turned out to be too bad for use.
+
+The striping happens on all available devices (at the time the chunks were
+allocated), so in case a new device is added it may not be utilized
+immediately and would require a rebalance. A fixed configured stripe width is
+not implemented.
 
 
 STORAGE MODEL, HARDWARE CONSIDERATIONS

Documentation/ch-seeding-device.rst

@@ -1,6 +1,6 @@
 The COW mechanism and multiple devices under one hood enable an interesting
-concept, called a seeding device: extending a read-only filesystem on a single
-device filesystem with another device that captures all writes. For example
+concept, called a seeding device: extending a read-only filesystem on a
+device with another device that captures all writes. For example
 imagine an immutable golden image of an operating system enhanced with another
 device that allows to use the data from the golden image and normal operation.
 This idea originated on CD-ROMs with base OS and allowing to use them for live
@@ -13,9 +13,9 @@ will not allow any writes, except adding a new device by **btrfs device add**.
 Then the filesystem can be remounted as read-write.
 
 Given that the filesystem on the seeding device is always recognized as
-read-only, it can be used to seed multiple filesystems, at the same time. The
-UUID that is normally attached to a device is automatically changed to a random
-UUID on each mount.
+read-only, it can be used to seed multiple filesystems from one device at the
+same time. The UUID that is normally attached to a device is automatically
+changed to a random UUID on each mount.
 
 Once the seeding device is mounted, it needs the writable device. After adding
 it, something like **remount -o remount,rw /path** makes the filesystem at
@@ -26,10 +26,10 @@ Alternatively, deleting the seeding device from the filesystem can turn it into
 a normal filesystem, provided that the writable device can also contain all the
 data from the seeding device.
 
-The seeding device flag can be cleared again by **btrfstune -f -s 0**, eg.
+The seeding device flag can be cleared again by **btrfstune -f -S 0**, eg.
 allowing to update with newer data but please note that this will invalidate
 all existing filesystems that use this particular seeding device. This works
-for some use cases, not for others, and a forcing flag to the command is
+for some use cases, not for others, and the forcing flag to the command is
 mandatory to avoid accidental mistakes.
 
 Example how to create and use one seeding device:
@@ -38,13 +38,15 @@ Example how to create and use one seeding device:
 
         # mkfs.btrfs /dev/sda
         # mount /dev/sda /mnt/mnt1
-        # ... fill mnt1 with data
+        ... fill mnt1 with data
         # umount /mnt/mnt1
+
         # btrfstune -S 1 /dev/sda
+
         # mount /dev/sda /mnt/mnt1
-        # btrfs device add /dev/sdb /mnt
+        # btrfs device add /dev/sdb /mnt/mnt1
         # mount -o remount,rw /mnt/mnt1
-        # ... /mnt/mnt1 is now writable
+        ... /mnt/mnt1 is now writable
 
 Now */mnt/mnt1* can be used normally. The device */dev/sda* can be mounted
 again with a another writable device:
@@ -74,3 +76,47 @@ A few things to note:
 * block group profiles *single* and *dup* support the use cases above
 * the label is copied from the seeding device and can be changed by **btrfs filesystem label**
 * each new mount of the seeding device gets a new random UUID
+
+Chained seeding devices
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Though it's not recommended and is rather an obscure and untested use case,
+chaining seeding devices is possible. In the first example, the writable device
+*/dev/sdb* can be turned onto another seeding device again, depending on the
+unchanged seeding device */dev/sda*. Then using */dev/sdb* as the primary
+seeding device it can be extended with another writable device, say */dev/sdd*,
+and it continues as before as a simple tree structure on devices.
+
+.. code-block:: bash
+
+        # mkfs.btrfs /dev/sda
+        # mount /dev/sda /mnt/mnt1
+        ... fill mnt1 with data
+        # umount /mnt/mnt1
+
+        # btrfstune -S 1 /dev/sda
+
+        # mount /dev/sda /mnt/mnt1
+        # btrfs device add /dev/sdb /mnt/mnt1
+        # mount -o remount,rw /mnt/mnt1
+        ... /mnt/mnt1 is now writable
+        # umount /mnt/mnt1
+
+        # btrfstune -S 1 /dev/sdb
+
+        # mount /dev/sdb /mnt/mnt1
+        # btrfs device add /dev/sdc /mnt
+        # mount -o remount,rw /mnt/mnt1
+        ... /mnt/mnt1 is now writable
+        # umount /mnt/mnt1
+
+As a result we have:
+
+* *sda* is a single seeding device, with its initial contents
+* *sdb* is a seeding device but requires *sda*, the contents are from the time
+  when *sdb* is made seeding, ie. contents of *sda* with any later changes
+* *sdc* last writable, can be made a seeding one the same way as was *sdb*,
+  preserving its contents and depending on *sda* and *sdb*
+
+As long as the seeding devices are unmodified and available, they can be used
+to start another branch.