X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=Documentation%2Fmkfs.btrfs.asciidoc;h=6515e145ee6deef6195e218a29420ca9e85de578;hb=b56fe169227a17bc92dea2fa399d1fb77e7cd233;hp=82bb75672a3d1004cbcd115817fbf9a3da517def;hpb=39ac3d16c1554d7f481776335a6e4c03fde32d7c;p=platform%2Fupstream%2Fbtrfs-progs.git

diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
index 82bb756..6515e14 100644
--- a/Documentation/mkfs.btrfs.asciidoc
+++ b/Documentation/mkfs.btrfs.asciidoc
@@ -154,8 +154,8 @@ Print help.
 SIZE UNITS
 ----------
 The default unit is 'byte'. All size parameters accept suffixes in the 1024
-base. The recognized suffixes are: 'k', 'm', 'g', 't', 'e', both uppercase and
-lowercase.
+base. The recognized suffixes are: 'k', 'm', 'g', 't', 'p', 'e', both uppercase
+and lowercase.
 
 MULTIPLE DEVICES
 ----------------
@@ -185,7 +185,12 @@ initramfs/initrd systems.
 FILESYSTEM FEATURES
 -------------------
 
+Features that can be enabled during creation time. See also `btrfs`(5) section
+'FILESYSTEM FEATURES'.
+
 *mixed-bg*::
+(kernel support since 2.6.37)
++
 mixed data and metadata block groups, also set by option '--mixed'
 
 *extref*::
@@ -196,6 +201,8 @@ supported a varying number of hardlinks depending on the sum of all file name
 sizes that can be stored into one metadata block
 
 *raid56*::
+(kernel support since 3.9)
++
 extended format for RAID5/6, also enabled if raid5 or raid6 block groups
 are selected
 
@@ -205,6 +212,8 @@ are selected
 reduced-size metadata for extent references, saves a few percent of metadata
 
 *no-holes*::
+(kernel support since 3.14)
++
 improved representation of file extents where holes are not explicitly
 stored as an extent, saves a few percent of metadata if sparse files are used
 
@@ -230,7 +239,7 @@ Other terms commonly used:
 *block group*::
 *chunk*::
 a logical range of space of a given profile, stores data, metadata or both;
-sometimes the terms are used interchangably
+sometimes the terms are used interchangeably
 +
 A typical size of metadata block group is 256MiB (filesystem smaller than
 50GiB) and 1GiB (larger than 50GiB), for data it's 1GiB. The system block group
@@ -254,17 +263,29 @@ There are the following block group types available:
 .2+^.<h| Profile   3+^.^h| Redundancy           .2+^.<h| Min/max devices
       ^.^h| Copies   ^.^h| Parity     ^.<h| Striping
 | single  | 1            |                |            | 1/any
-| DUP     | 2 / 1 device |                |            | 1/1 ^(see note)^
+| DUP     | 2 / 1 device |                |            | 1/any ^(see note 1)^
 | RAID0   |              |                | 1 to N     | 2/any
 | RAID1   | 2            |                |            | 2/any
 | RAID10  | 2            |                | 1 to N     | 4/any
-| RAID5   | 1            | 1              | 2 to N - 1 | 2/any
-| RAID6   | 1            | 2              | 3 to N - 2 | 3/any
+| RAID5   | 1            | 1              | 2 to N - 1 | 2/any ^(see note 2)^
+| RAID6   | 1            | 2              | 3 to N - 2 | 3/any ^(see note 3)^
 |=============================================================
 
-'Note:' DUP may exist on more than 1 device if it starts on a single device and
-another one is added, but *mkfs.btrfs* will not let you create DUP on multiple
-devices.
+WARNING: It's not recommended to build btrfs with RAID0/1/10/5/6 prfiles on
+partitions from the same device.  Neither redundancy nor performance will be
+improved.
+
+'Note 1:' DUP may exist on more than 1 device if it starts on a single device and
+another one is added. Since version 4.5.1, *mkfs.btrfs* will let you create DUP
+on multiple devices.
+
+'Note 2:' It's not recommended to use 2 devices with RAID5. In that case,
+parity stripe will contain the same data as the data stripe, making RAID5
+degraded to RAID1 with more overhead.
+
+'Note 3:' It's also not recommended to use 3 devices with RAID6, unless you
+want to get effectively 3 copies in a RAID1-like manner (but not exactly that).
+N-copies RAID1 is not implemented.
 
 DUP PROFILES ON A SINGLE DEVICE
 -------------------------------
@@ -274,15 +295,28 @@ the logical blocks to 2 physical locations. Whether there are really 2
 physical copies highly depends on the underlying device type.
 
 For example, a SSD drive can remap the blocks internally to a single copy thus
-deduplicating them. This negates the purpose of increased redunancy and just
-wastes space.
+deduplicating them. This negates the purpose of increased redundancy and just
+wastes filesystem space without the expected level of redundancy.
 
 The duplicated data/metadata may still be useful to statistically improve the
 chances on a device that might perform some internal optimizations. The actual
-details are not usually disclosed by vendors. As another example, the widely
-used USB flash or SD cards use a translation layer. The data lifetime may
-be affected by frequent plugging. The memory cells could get damaged, hopefully
-not destroying both copies of particular data.
+details are not usually disclosed by vendors. For example we could expect that
+not all blocks get deduplicated. This will provide a non-zero probability of
+recovery compared to a zero chance if the single profile is used. The user
+should make the tradeoff decision. The deduplication in SSDs is thought to be
+widely available so the reason behind the mkfs default is to not give a false
+sense of redundancy.
+
+As another example, the widely used USB flash or SD cards use a translation
+layer between the logical and physical view of the device. The data lifetime
+may be affected by frequent plugging. The memory cells could get damaged,
+hopefully not destroying both copies of particular data in case of DUP.
+
+The wear levelling techniques can also lead to reduced redundancy, even if the
+device does not do any deduplication. The controllers may put data written in
+a short timespan into the same physical storage unit (cell, block etc). In case
+this unit dies, both copies are lost. BTRFS does not add any artificial delay
+between metadata writes.
 
 The traditional rotational hard drives usually fail at the sector level.
 
@@ -338,4 +372,6 @@ further details.
 
 SEE ALSO
 --------
-`btrfs`(8), `wipefs`(8)
+`btrfs`(5),
+`btrfs`(8),
+`wipefs`(8)