Imported Upstream version 4.6.1

30 files changed, 3702 insertions, 0 deletions

diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in
new file mode 100644
index 00000000..aea2cb47
--- /dev/null
+++ b/Documentation/Makefile.in
@@ -0,0 +1,133 @@
+# Guard against environment variables
+MAN8_TXT =
+
+# Top level commands
+MAN8_TXT += btrfs.asciidoc
+MAN8_TXT += btrfs-convert.asciidoc
+MAN8_TXT += btrfs-find-root.asciidoc
+MAN8_TXT += btrfs-image.asciidoc
+MAN8_TXT += btrfs-map-logical.asciidoc
+MAN8_TXT += btrfs-select-super.asciidoc
+MAN8_TXT += btrfstune.asciidoc
+MAN8_TXT += fsck.btrfs.asciidoc
+MAN8_TXT += mkfs.btrfs.asciidoc
+
+# Sub commands for btrfs
+MAN8_TXT += btrfs-subvolume.asciidoc
+MAN8_TXT += btrfs-filesystem.asciidoc
+MAN8_TXT += btrfs-balance.asciidoc
+MAN8_TXT += btrfs-device.asciidoc
+MAN8_TXT += btrfs-scrub.asciidoc
+MAN8_TXT += btrfs-check.asciidoc
+MAN8_TXT += btrfs-rescue.asciidoc
+MAN8_TXT += btrfs-inspect-internal.asciidoc
+MAN8_TXT += btrfs-send.asciidoc
+MAN8_TXT += btrfs-receive.asciidoc
+MAN8_TXT += btrfs-quota.asciidoc
+MAN8_TXT += btrfs-qgroup.asciidoc
+MAN8_TXT += btrfs-replace.asciidoc
+MAN8_TXT += btrfs-restore.asciidoc
+MAN8_TXT += btrfs-property.asciidoc
+
+# Category 5 manual page
+MAN5_TXT += btrfs-man5.asciidoc
+
+MAN_TXT = $(MAN8_TXT) $(MAN5_TXT)
+MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT))
+MAN_HTML = $(patsubst %.asciidoc,%.html,$(MAN_TXT))
+
+DOC_MAN5 = $(patsubst %.asciidoc,%.5,$(MAN5_TXT))
+GZ_MAN5 = $(patsubst %.asciidoc,%.5.gz,$(MAN5_TXT))
+
+DOC_MAN8 = $(patsubst %.asciidoc,%.8,$(MAN8_TXT))
+GZ_MAN8 = $(patsubst %.asciidoc,%.8.gz,$(MAN8_TXT))
+
+mandir ?= $(prefix)/share/man
+man8dir = $(mandir)/man8
+man5dir = $(mandir)/man5
+
+ASCIIDOC = @ASCIIDOC@
+ASCIIDOC_EXTRA =
+MANPAGE_XSL = manpage-normal.xsl
+XMLTO = @XMLTO@
+XMLTO_EXTRA =
+XMLTO_EXTRA = -m manpage-bold-literal.xsl
+GZIPCMD = @GZIP@
+INSTALL = @INSTALL@
+RM = @RM@
+RMDIR = @RMDIR@
+LN_S = @LN_S@
+MV = @MV@
+SED = @SED@
+BTRFS_VERSION = $(shell $(SED) -n 's/.*PACKAGE_VERSION "\(.*\)"/\1/p'\
+		  ../config.h)
+
+ifneq ($(findstring $(MAKEFLAGS),s),s)
+ifndef V
+	QUIET_RM	= @
+	QUIET_ASCIIDOC	= @echo "    [ASCII]  $@";
+	QUIET_XMLTO	= @echo "    [XMLTO]  $@";
+	QUIET_GZIP	= @echo "    [GZ]     $@";
+	QUIET_STDERR	= 2> /dev/null
+	QUIET_SUBDIR0	= +@subdir=
+	QUIET_SUBDIR1	= ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
+			  $(MAKE) $(PRINT_DIR) -C $$subdir
+	export V
+endif
+endif
+
+all: man
+man: man5 man8
+man5: $(GZ_MAN5)
+man8: $(GZ_MAN8)
+html: $(MAN_HTML)
+
+install: install-man
+
+install-man: man
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir)
+	$(INSTALL) -m 644 $(GZ_MAN5) $(DESTDIR)$(man5dir)
+	# the source file name of btrfs.5 clashes with section 8 page, but we
+	# want to keep the code generic
+	$(MV) $(DESTDIR)$(man5dir)/btrfs-man5.5.gz $(DESTDIR)$(man5dir)/btrfs.5.gz
+	$(INSTALL) -m 644 $(GZ_MAN8) $(DESTDIR)$(man8dir)
+	$(LN_S) -f btrfs-check.8.gz $(DESTDIR)$(man8dir)/btrfsck.8.gz
+	$(LN_S) -f btrfs-rescue.8.gz $(DESTDIR)$(man8dir)/btrfs-zero-log.8.gz
+	$(LN_S) -f btrfs-inspect-internal.8.gz $(DESTDIR)$(man8dir)/btrfs-debug-tree.8.gz
+	$(LN_S) -f btrfs-inspect-internal.8.gz $(DESTDIR)$(man8dir)/btrfs-show-super.8.gz
+
+uninstall:
+	cd $(DESTDIR)$(man8dir); rm -f btrfs-check.8.gz $(GZ_MAN8)
+	$(RMDIR) -p --ignore-fail-on-non-empty $(DESTDIR)$(man8dir)
+
+clean:
+	$(QUIET_RM)$(RM) -f *.xml *.xml+ *.5 *.5.gz *.8 *.8.gz *.html
+
+%.5.gz : %.5
+	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
+
+%.8.gz : %.8
+	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
+
+%.5 : %.xml
+	$(QUIET_XMLTO)$(RM) -f $@ && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+%.8 : %.xml
+	$(QUIET_XMLTO)$(RM) -f $@ && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+%.xml : %.asciidoc asciidoc.conf
+	$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
+	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
+		$(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \
+		-o $@+ $< && \
+	$(MV) $@+ $@
+
+%.html : %.asciidoc asciidoc.conf
+	$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
+	$(ASCIIDOC) -b html -d article -f asciidoc.conf \
+		$(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \
+		-o $@+ $< && \
+	$(MV) $@+ $@
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
new file mode 100644
index 00000000..1ea74591
--- /dev/null
+++ b/Documentation/asciidoc.conf
@@ -0,0 +1,48 @@
+## linkbtrfs: macro
+#
+# Usage: linkbtrfs:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show Btrfslink as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linkbtrfs):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[tags]
+bracket-emphasis={1?[{1}]}<emphasis>&lt;|&gt;</emphasis>
+
+[quotes]
+&lt;|&gt;=#bracket-emphasis
+
+[attributes]
+asterisk=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+backslash=&#92;
+tilde=&#126;
+apostrophe=&#39;
+backtick=&#96;
+litdd=&#45;&#45;
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Btrfs</refmiscinfo>
+<refmiscinfo class="version">{btrfs_version}</refmiscinfo>
+<refmiscinfo class="manual">Btrfs Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
new file mode 100644
index 00000000..7df40b9c
--- /dev/null
+++ b/Documentation/btrfs-balance.asciidoc
@@ -0,0 +1,223 @@
+btrfs-balance(8)
+================
+
+NAME
+----
+btrfs-balance - balance block groups on a btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs balance* <subcommand> <args>
+
+DESCRIPTION
+-----------
+The primary purpose of the balance feature is to spread block groups across
+all devices so they match constraints defined by the respective profiles. See
+`mkfs.btrfs`(8) section 'PROFILES' for more details.
+The scope of the balancing process can be further tuned by use of filters that
+can select the block groups to process. Balance works only on a mounted
+filesystem.
+
+The balance operation is cancellable by the user. The on-disk state of the
+filesystem is always consistent so an unexpected interruption (eg. system crash,
+reboot) does not corrupt the filesystem. The progress of the balance operation
+is temporarily stored and will be resumed upon mount, unless the mount option
+'skip_balance' is specified.
+
+WARNING: running balance without filters will take a lot of time as it basically
+rewrites the entire filesystem and needs to update all block pointers.
+
+The filters can be used to perform following actions:
+
+- convert block group profiles (filter 'convert')
+- make block group usage more compact  (filter 'usage')
+- perform actions only on a given device (filters 'devid', 'drange')
+
+The filters can be applied to a combination of block group types (data,
+metadata, system). Note that changing 'system' needs the force option.
+
+NOTE: the balance operation needs enough work space, ie. space that is
+completely unused in the filesystem, otherwise this may lead to ENOSPC reports.
+See the section 'ENOSPC' for more details.
+
+COMPATIBILITY
+-------------
+
+NOTE: The balance subcommand also exists under the *btrfs filesystem*
+namespace. This still works for backward compatibility but is deprecated and
+should not be used anymore.
+
+NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility
+but is deprecated and should not be used anymore. Use *btrfs balance start*
+command instead.
+
+SUBCOMMAND
+----------
+*cancel* <path>::
+cancel running or paused balance
+
+*pause* <path>::
+pause running balance operation, this will store the state of the balance
+progress and used filters to the filesystem
+
+*resume* <path>::
+resume interrupted balance
+
+*start* [options] <path>::
+start the balance operation according to the specified filters, no filters
+will rewrite the entire filesystem. The process runs in the foreground.
++
+NOTE: the balance command without filters will basically rewrite everything
+in the filesystem. The run time is potentially very long, depending on the
+filesystem size. To prevent starting a full balance by accident, the user is
+warned and has a few seconds to cancel the operation before it starts. The
+warning and delay can be skipped with '--full-balance' option.
++
+`Options`
++
+-d[<filters>]::::
+act on data block groups, see `FILTERS` section for details about 'filters'
+-m[<filters>]::::
+act on metadata chunks, see `FILTERS` section for details about 'filters'
+-s[<filters>]::::
+act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'.
+-v::::
+be verbose and print balance filter arguments
+-f::::
+force reducing of metadata integrity, eg. when going from 'raid1' to 'single'
+
+*status* [-v] <path>::
+Show status of running or paused balance.
++
+If '-v' option is given, output will be verbose.
+
+FILTERS
+-------
+From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the
+full filesystem, and can be used to change the replication configuration (e.g.
+moving data from single to RAID1). This functionality is accessed through the
+'-d', '-m' or '-s' options to btrfs balance start, which filter on data,
+metadata and system blocks respectively.
+
+A filter has the following structure: 'type'[='params'][,'type'=...]
+
+The available types are:
+
+*profiles=<profiles>*::
+Balances only block groups with the given profiles. Parameters
+are a list of profile names separated by "'|'" (pipe).
+
+*usage=<percent>*::
+*usage=<range>*::
+Balances only block groups with usage under the given percentage. The
+value of 0 is allowed and will clean up completely unused block groups, this
+should not require any new work space allocated. You may want to use 'usage=0'
+in case balance is returning ENOSPC and your filesystem is not too full.
++
+The argument may be a single value or a range. The single value 'N' means 'at
+most N percent used', equivalent to '..N' range syntax. Kernels prior to 4.4
+accept only the single value format.
+The minimum range boundary is inclusive, maximum is exclusive.
+
+*devid=<id>*::
+Balances only block groups which have at least one chunk on the given
+device. To list devices with ids use *btrfs fi show*.
+
+*drange=<range>*::
+Balance only block groups which overlap with the given byte range on any
+device. Use in conjunction with 'devid' to filter on a specific device. The
+parameter is a range specified as 'start..end'.
+
+*vrange=<range>*::
+Balance only block groups which overlap with the given byte range in the
+filesystem's internal virtual address space. This is the address space that
+most reports from btrfs in the kernel log use. The parameter is a range
+specified as 'start..end'.
+
+*convert=<profile>*::
+Convert each selected block group to the given profile name identified by
+parameters.
++
+NOTE: starting with kernel 4.5, the 'data' chunks can be converted to/from the
+'DUP' profile on a single device.
+
+*limit=<number>*::
+*limit=<range>*::
+Process only given number of chunks, after all filters are applied. This can be
+used to specifically target a chunk in connection with other filters ('drange',
+'vrange') or just simply limit the amount of work done by a single balance run.
++
+The argument may be a single value or a range. The single value 'N' means 'at
+most N chunks', equivalent to '..N' range syntax. Kernels prior to 4.4 accept
+only the single value format.  The range minimum and maximum are inclusive.
+
+*stripes=<range>*::
+Balance only block groups which have the given number of stripes. The parameter
+is a range specified as 'start..end'. Makes sense for block group profiles that
+utilize striping, ie. RAID0/10/5/6.  The range minimum and maximum are
+inclusive.
+
+*soft*::
+Takes no parameters. Only has meaning when converting between profiles.
+When doing convert from one profile to another and soft mode is on,
+chunks that already have the target profile are left untouched.
+This is useful e.g. when half of the filesystem was converted earlier but got
+cancelled.
++
+The soft mode switch is (like every other filter) per-type.
+For example, this means that we can convert metadata chunks the "hard" way
+while converting data chunks selectively with soft switch.
+
+Profile names, used in 'profiles' and 'convert' are one of: 'raid0', 'raid1',
+'raid10', 'raid5', 'raid6', 'dup', 'single'. The mixed data/metadata profiles
+can be converted in the same way, but it's conversion between mixed and non-mixed
+is not implemented. For the constraints of the profiles please refer to `mkfs.btrfs`(8),
+section 'PROFILES'.
+
+ENOSPC
+------
+
+The way balance operates, it usually needs to temporarily create a new block
+group and move the old data there. For that it needs work space, otherwise
+it fails for ENOSPC reasons.
+This is not the same ENOSPC as if the free space is exhausted. This refers to
+the space on the level of block groups.
+
+The free work space can be calculated from the output of the *btrfs filesystem show*
+command:
+
+------------------------------
+   Label: 'BTRFS'  uuid: 8a9d72cd-ead3-469d-b371-9c7203276265
+	   Total devices 2 FS bytes used 77.03GiB
+	   devid    1 size 53.90GiB used 51.90GiB path /dev/sdc2
+	   devid    2 size 53.90GiB used 51.90GiB path /dev/sde1
+------------------------------
+
+'size' - 'used' = 'free work space' +
+'53.90GiB' - '51.90GiB' = '2.00GiB'
+
+An example of a filter that does not require workspace is 'usage=0'. This will
+scan through all unused block groups of a given type and will reclaim the
+space. After that it might be possible to run other filters.
+
+**CONVERSIONS ON MULTIPLE DEVICES**
+
+Conversion to profiles based on striping (RAID0, RAID5/6) require the work
+space on each device. An interrupted balance may leave partially filled block
+groups that might consume the work space.
+
+EXIT STATUS
+-----------
+*btrfs balance* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-device`(8)
diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc
new file mode 100644
index 00000000..74a2ad21
--- /dev/null
+++ b/Documentation/btrfs-check.asciidoc
@@ -0,0 +1,111 @@
+btrfs-check(8)
+==============
+
+NAME
+----
+btrfs-check - check or repair an unmounted btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs check* [options] <device>
+
+DESCRIPTION
+-----------
+
+The filesystem checker is used to verify structural integrity of a filesystem
+and attempt to repair it if requested. The filesystem must be unmounted.
+
+By default, *btrfs check* will not modify the device but you can reaffirm that
+by the option '--readonly'.
+
+*btrfsck* is an alias of *btrfs check* command and is now deprecated.
+
+WARNING: Do not use '--repair' unless you are adviced to by a developer, an
+experienced user or accept the fact that 'fsck' cannot possibly fix all sorts
+of damage that could happen to a filesystem because of software and hardware
+bugs.
+
+The structural integrity check verifies if internal filesystem objects or
+data structures satisfy the constraints, point to the right objects or are
+correctly connected together.
+
+There are several cross checks that can detect wrong reference counts of shared
+extents, backrefrences, missing extents of inodes, directory and inode
+connectivity etc.
+
+The amount of memory required can be high, depending on the size of the
+filesystem, smililarly the run time.
+
+SAFE OR ADVISORY OPTIONS
+------------------------
+
+-b|--backup::
+use the first valid set of backup roots stored in the superblock
++
+This can be combined with '--super' if some of the superblocks are damaged.
+
+--check-data-csum::
+verify checksums of data blocks
++
+This expects that the filesystem is otherwise
+OK, so this is basically and offline 'scrub' but does not repair data from
+spare coipes.
+
+--chunk-root <bytenr>::
+use the given offset 'bytenr' for the chunk tree root
+
+-E|--subvol-extents <subvolid>::
+show extent state for the given subvolume
+
+-p|--progress::
+indicate progress at various checking phases
+
+--qgroup-report::
+verify qgroup accounting and compare against filesystem accounting
+
+-r|--tree-root <bytenr>::
+use the given offset 'bytenr' for the tree root
+
+--readonly::
+(default)
+run in read-only mode, this option exists to calm potential panic when users
+are going to run the checker
+
+-s|--super <superblock>::
+use 'superblock'th superblock copy, valid values are 0, 1 or 2 if the
+respective superblock offset is within the device size
++
+This can be used to use a different starting point if some of the primary
+superblock is damaged.
+
+DANGEROUS OPTIONS
+-----------------
+
+--repair::
+enable the repair mode and attempt to fix problems where possible
+--init-csum-tree::
+create a new checksum tree and recalculate checksums in all files
++
+NOTE: Do not blindly use this option to fix checksum mismatch problems.
+
+--init-extent-tree::
+build the extent tree from scratch
++
+NOTE: Do not use unless you know what you're doing.
+
+EXIT STATUS
+-----------
+*btrfs check* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-scrub`(8),
+`btrfs-rescue`(8)
diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
new file mode 100644
index 00000000..ab3577db
--- /dev/null
+++ b/Documentation/btrfs-convert.asciidoc
@@ -0,0 +1,106 @@
+btrfs-convert(8)
+================
+
+NAME
+----
+btrfs-convert - convert from ext2/3/4 filesystem to btrfs
+
+SYNOPSIS
+--------
+*btrfs-convert* [options] <device>
+
+DESCRIPTION
+-----------
+*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a
+btrfs filesystem in-place.  The original filesystem image is accessible
+subvolume named 'ext2_saved' as file 'image'.
+
+WARNING: If you are going to perform rollback to ext2/3/4, you should not
+execute *btrfs balance* command on the converted filesystem. This will change
+the extent layout and make *btrfs-convert* unable to rollback.
+
+The conversion utilizes free space of the original filesystem. The exact
+estimate of the required space cannot be foretold. The final btrfs metadata
+might occupy several gigabytes on a hundreds-gigabyte filesystem.
+
+If you decide not to rollback anymore, it is recommended to perform a few more
+steps to transform the btrfs filesystem to a more compact layout. The
+conversion inherits the original data block fragmentation and the metadata
+blocks are bound to the original free space layout.
+
+**REMOVE THE ORIGINAL FILESYSTEM METADATA**
+
+By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
+will be removed:
+
+   # btrfs subvolume delete /mnt/ext2_saved
+
+At this point it's not possible to do rollback. The filesystem is usable but may
+be impacted by the fragmentation.
+
+**MAKE FILE DATA MORE CONTIGUOUS**
+
+An optional but recommended step is to run defragmentation on the entire
+filesystem. This will attempt to make file extents more contiguous.
+
+   # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
+
+Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with target
+extent size 32M ('-t').
+
+**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT**
+
+Optional but recommended step.
+
+The metadata block groups after conversion may be smaller than the default size
+(256MiB or 1GiB). Running a balance will attempt to merge the block groups.
+This depends on the free space layout (and fragmentation) and may fail. This is
+a soft error leaving the filesystem usable but the block group layout may
+remain unchanged.
+
+Note that balance operation takes a lot of time.
+
+   # btrfs balance start -m /mnt/btrfs
+
+OPTIONS
+-------
+-d|--no-datasum::
+disable data checksum calculations and set NODATASUM file flag, this can speed
+up the conversion
+-i|--no-xattr::
+ignore xattrs and ACLs of files
+-n|--no-inline::
+disable inlining of small files to metadata blocks, this will decrease the metadata
+consumption and may help to convert a filesystem with low free space
+-N|--nodesize <SIZE>::
+set filesystem nodesize, the tree block size in which btrfs stores its metadata.
+The default value is 16KB (16384) or the page size, whichever is bigger.
+Must be a multiple of the sectorsize, but not larger than 65536. See
+`mkfs.btrfs`(8) for more details.
+-r|--rollback::
+rollback to the original ext2/3/4 filesystem if possible
+-l|--label <LABEL>::
+set filesystem label during conversion
+-L|--copy-label::
+use label from the converted filesystem
+-O|--features <feature1>[,<feature2>...]::
+A list of filesystem features turned on at btrfs-convert time. Not all features
+are supported by old kernels. To disable a feature, prefix it with '^'.
++
+To see all available features that btrfs-convert supports run:
++
++btrfs-convert -O list-all+
++
+-p|--progress::
+show progress of conversion, on by default
+--no-progress::
+disable detailed progress and show only the main phases of conversion
+
+EXIT STATUS
+-----------
+*btrfs-convert* will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
new file mode 100644
index 00000000..d05fc457
--- /dev/null
+++ b/Documentation/btrfs-device.asciidoc
@@ -0,0 +1,244 @@
+btrfs-device(8)
+===============
+
+NAME
+----
+btrfs-device - manage devices of btrfs filesystems
+
+SYNOPSIS
+--------
+*btrfs device* <subcommand> <args>
+
+DESCRIPTION
+-----------
+The *btrfs device* command group is used to manage devices of the btrfs filesystems.
+
+DEVICE MANAGEMENT
+-----------------
+Btrfs filesystem can be created on top of single or multiple block devices.
+Data and metadata are organized in allocation profiles with various redundancy
+policies. There's some similarity with traditional RAID levels, but this could
+be confusing to users familiar with the traditional meaning. Due to the
+similarity, the RAID terminology is widely used in the documentation.  See
+`mkfs.btrfs`(9) for more details and the exact profile capabilities and
+constraints.
+
+The device management works on a mounted filesystem. Devices can be added,
+removed or replaced, by commands profided by *btrfs device* and *btrfs replace*.
+
+The profiles can be also changed, provided there's enough workspace to do the
+conversion, using the *btrfs balance* comand and namely the filter 'convert'.
+
+Profile::
+A profile describes an allocation policy based on the redundancy/replication
+constrants in connection with the number of devices. The profile applies to
+data and metadata block groups separately.
+
+RAID level::
+Where applicable, the level refers to a profile that matches constraints of the
+standard RAID levels. At the moment the supported ones are: RAID0, RAID1,
+RAID10, RAID5 and RAID6.
+
+See the section *TYPICAL USECASES* for some examples.
+
+SUBCOMMAND
+----------
+*add* [-Kf] <dev> [<dev>...] <path>::
+Add device(s) to the filesystem identified by <path>.
++
+If applicable, a whole device discard (TRIM) operation is performed prior to
+adding the device. A device with existing filesystem detected by `blkid`(8)
+will prevent device addition and has to be forced. Alternatively the filesystem
+can be wiped from the device using eg. the `wipefs`(8) tool.
++
+The operation is instant and does not affect existing data. The operation merely
+adds the device to the filesystem structures and creates some block groups
+headers.
++
+`Options`
++
+-K|--nodiscard::::
+do not perform discard (TRIM) by default
+-f|--force::::
+force overwrite of existing filesystem on the given disk(s)
+
+*remove* <dev>|<devid> [<dev>|<devid>...] <path>::
+Remove device(s) from a filesystem identified by <path>
++
+Device removal must satisfy the profile constraints, otherwise the command
+fails. The filesystem must be converted to profile(s) that would allow the
+removal. This can typically happen when going down from 2 devices to 1 and
+using the RAID1 profile. See the example section below.
++
+The operation can take long as it needs to move all data from the device.
++
+NOTE: It is not possible to delete the device that was used to mount the
+filesystem. This is a limitation given by the VFS.
+
+*delete* <dev>|<devid> [<dev>|<devid>...] <path>::
+Alias of remove kept for backward compatibility
+
+*ready* <device>::
+Wait until all devices of a multiple-device filesystem are scanned and registered
+within the kernel module.
+
+*scan* [(--all-devices|-d)|<device> [<device>...]]::
+Scan devices for a btrfs filesystem and register them with the kernel module.
+This allows mounting multiple-device filesystem by specifying just one from the
+whole group.
++
+If no devices are passed, all block devices that blkid reports to contain btrfs
+are scanned.
++
+The options '--all-devices' or '-d' are deprecated and kept for backward compatibility.
+If used, behavior is the same as if no devices are passed.
++
+The command can be run repeatedly. Devices that have been already registered
+remain as such. Reloading the kernel module will drop this information. There's
+an alternative way of mounting multiple-device filesystem without the need for
+prior scanning. See the mount option 'device'.
+
+*stats* [-z] <path>|<device>::
+Read and print the device IO error statistics for all devices of the given
+filesystem identified by <path> or for a single <device>. See section *DEVICE
+STATS* for more information.
++
+`Options`
++
+-z::::
+Print the stats and reset the values to zero afterwards.
+
+*usage* [options] <path> [<path>...]::
+Show detailed information about internal allocations in devices.
++
+`Options`
++
+-b|--raw::::
+raw numbers in bytes, without the 'B' suffix
+-h|--human-readable::::
+print human friendly numbers, base 1024, this is the default
+-H::::
+print human friendly numbers, base 1000
+--iec::::
+select the 1024 base for the following options, according to the IEC standard
+--si::::
+select the 1000 base for the following options, according to the SI standard
+-k|--kbytes::::
+show sizes in KiB, or kB with --si
+-m|--mbytes::::
+show sizes in MiB, or MB with --si
+-g|--gbytes::::
+show sizes in GiB, or GB with --si
+-t|--tbytes::::
+show sizes in TiB, or TB with --si
+
+If conflicting options are passed, the last one takes precedence.
+
+TYPICAL USECASES
+----------------
+
+STARTING WITH A SINGLE-DEVICE FILESYSTEM
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Assume we've created a filesystem on a block device '/dev/sda' with profile
+'single/single' (data/metadata), the device size is 50GiB and we've used the
+whole device for the filesystem. The mount point is '/mnt'.
+
+The amount of data stored is 16GiB, metadata have allocated 2GiB.
+
+==== ADD NEW DEVICE ====
+
+We want to increase the total size of the filesystem and keep the profiles. The
+size of the new device '/dev/sdb' is 100GiB.
+
+ $ btrfs device add /dev/sdb /mnt
+
+The amount of free data space increases by less than 100GiB, some space is
+allocated for metadata.
+
+==== CONVERT TO RAID1 ====
+
+Now we want to increase the redundancy level of both data and metadata, but
+we'll do that in steps. Note, that the device sizes are not equal and we'll use
+that to show the capabilities of split data/metadata and independent profiles.
+
+The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2
+copies will be stored on the devices.
+
+First we'll convert the metadata. As the metadata occupy less than 50GiB and
+there's enough workspace for the conversion process, we can do:
+
+ $ btrfs balance start -mconvert=raid1 /mnt
+
+This operation can take a while as the metadata have to be moved and all block
+pointers updated. Depending on the physical locations of the old and new
+blocks, the disk seeking is the key factor affecting performance.
+
+You'll note that the system block group has been also converted to RAID1, this
+normally happens as the system block group also holds metadata (the physical to
+logial mappings).
+
+What changed:
+
+* available data space decreased by 3GiB, usable rougly (50 - 3) + (100 - 3) = 144 GiB
+* metadata redundancy increased
+
+IOW, the unequal device sizes allow for combined space for data yet improved
+redundancy for metadata. If we decide to increase redundancy of data as well,
+we're going to lose 50GiB of the second device for obvious reasons.
+
+ $ btrfs balance start -dconvert=raid1 /mnt
+
+The balance process needs some workspace (ie. a free device space without any
+data or metadata block groups) so the command could fail if there's too much
+data or the block groups occupy the whole first device.
+
+The device size of '/dev/sdb' as seen by the filesystem remains unchanged, but
+the logical space from 50-100GiB will be unused.
+
+DEVICE STATS
+------------
+
+The device stats keep persistent record of several error classes related to
+doing IO. The current values are printed at mount time and updated during
+filesystem lifetime or from a scrub run.
+
+ $ btrfs device stats /dev/sda3
+ [/dev/sda3].write_io_errs   0
+ [/dev/sda3].read_io_errs    0
+ [/dev/sda3].flush_io_errs   0
+ [/dev/sda3].corruption_errs 0
+ [/dev/sda3].generation_errs 0
+
+write_io_errs::
+Failed writes to the block devices, means that the layers beneath the
+filesystem were not able to satisfy the write request.
+read_io_errors::
+Read request analogy to write_io_errs.
+flush_io_errs::
+Number of failed writes with the 'FLUSH' flag set. The flushing is a method of
+forcing a particular order between write requests and is crucial for
+implementing crash consistency. In case of btrfs, all the metadata blocks must
+be permanently stored on the block device before the superblock is written.
+corruption_errs::
+A block checksum mismatched or a corrupted metadata header was found.
+generation_errs::
+The block generation does not match the expected value (eg. stored in the
+parent node).
+
+EXIT STATUS
+-----------
+*btrfs device* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-replace`(8),
+`btrfs-balance`(8)
diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc
new file mode 100644
index 00000000..dc032faa
--- /dev/null
+++ b/Documentation/btrfs-filesystem.asciidoc
@@ -0,0 +1,373 @@
+btrfs-filesystem(8)
+===================
+
+NAME
+----
+btrfs-filesystem - command group of btrfs that usually work on the whole filesystem
+
+SYNOPSIS
+--------
+*btrfs filesystem* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs filesystem* is used to do the whole filesystem level tasks, including
+all the regular filesystem operations like resizing, space stats, label
+setting/getting, and defragmentation.
+
+SUBCOMMAND
+----------
+*df* [options] <path>::
+Show a terse summary information about allocation of block group types of a given
+mount point. The original purpose of this command was a debugging helper. The
+output needs to be further interpreted and is not suitable for quick overview.
++
+--
+An example with description:
+
+* device size: '1.9TiB', one device, no RAID
+* filesystem size: '1.9TiB'
+* created with: 'mkfs.btrfs -d single -m single'
+--
++
+------------------------------
+$ btrfs filesystem df /path
+Data, single: total=1.15TiB, used=1.13TiB
+System, single: total=32.00MiB, used=144.00KiB
+Metadata, single: total=12.00GiB, used=6.45GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+------------------------------
++
+--
+* 'Data', 'System' and 'Metadata' are separate block group types.
+'GlobalReserve' is an artificial and internal emergency space, see below.
+* 'single' -- the allocation profile, defined at mkfs time
+* 'total' -- sum of space reserved for
+all allocation profiles of the given type, ie. all Data/single. Note that it's
+not total size of filesystem.
+* 'used' -- sum of used space of the above, ie. file extents, metadata blocks
+--
++
+'GlobalReserve' is an artificial and internal emergency space. It is used eg.
+when the filesystem is full. Its 'total' size is dynamic based on the
+filesystem size, usually not larger than 512MiB, 'used' may fluctuate.
++
+The global block reserve is accounted within Metadata. In case the filesystem
+metadata are exhausted, 'GlobalReserve/total + Metadata/used = Metadata/total'.
++
+`Options`
++
+-b|--raw::::
+raw numbers in bytes, without the 'B' suffix
+-h|--human-readable::::
+print human friendly numbers, base 1024, this is the default
+-H::::
+print human friendly numbers, base 1000
+--iec::::
+select the 1024 base for the following options, according to the IEC standard
+--si::::
+select the 1000 base for the following options, according to the SI standard
+-k|--kbytes::::
+show sizes in KiB, or kB with --si
+-m|--mbytes::::
+show sizes in MiB, or MB with --si
+-g|--gbytes::::
+show sizes in GiB, or GB with --si
+-t|--tbytes::::
+show sizes in TiB, or TB with --si
++
+If conflicting options are passed, the last one takes precedence.
+
+*defragment* [options] <file>|<dir> [<file>|<dir>...]::
+Defragment file data on a mounted filesystem.
++
+If '-r' is passed, files in dir will be defragmented recursively.
+The start position and the number of bytes to defragment can be specified by
+start and length using '-s' and '-l' options below.
+Extents bigger than value given by '-t' will be skipped, otherwise this value
+is used as a target extent size, but is only advisory and may not be reached
+if the free space is too fragmented.
+Use 0 to take the kernel default, which is 256kB but may change in the future.
+You can also turn on compression in defragment operations.
++
+WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as
+with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up
+the ref-links of COW data (for example files copied with `cp --reflink`,
+snapshots or de-duplicated data).
+This may cause considerable increase of space usage depending on the broken up
+ref-links.
++
+NOTE: Directory arguments without '-r' do not defragment files recursively but will
+defragment certain internal trees (extent tree and the subvolume tree). This has been
+confusing and could be removed in the future.
++
+For 'start', 'len', 'size' it is possible to append
+units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
+KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).
++
+`Options`
++
+-v::::
+be verbose, print file names as they're submitted for defragmentation
+-c[<algo>]::::
+compress file contents while defragmenting. Optional argument selects the compression
+algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no
+compression. See also section 'EXAMPLES'.
+-r::::
+defragment files recursively in given directories
+-f::::
+flush data for each file before going to the next file. This will limit the amount
+of dirty data to current file, otherwise the amount cumulates from several files
+and may increase system load.
+-s <start>[kKmMgGtTpPeE]::::
+defragmentation will start from the given offset, default is beginning of a file
+-l <len>[kKmMgGtTpPeE]::::
+defragment only up to 'len' bytes, default is the file size
+-t <size>[kKmMgGtTpPeE]::::
+target extent size, do not touch extents bigger than 'size'
+
+*du* [options] <path> [<path>..]::
+Calculate disk usage of the target files using FIEMAP. For individual
+files, it will report a count of total bytes, and exclusive (not
+shared) bytes. We also calculate a 'set shared' value which is
+described below.
++
+Each argument to 'btrfs fi du' will have a 'set shared' value
+calculated for it. We define each 'set' as those files found by a
+recursive search of an argument. The 'set shared' value
+then is a sum of all shared space referenced by the set.
++
+'set shared' takes into account overlapping shared extents, hence it
+isn't as simple as adding up shared extents.
++
+`Options`
++
+-s|--summarize::::
+display only a total for each argument
+--raw::::
+raw numbers in bytes, without the 'B' suffix.
+--human-readable::::
+print human friendly numbers, base 1024, this is the default
+--iec::::
+select the 1024 base for the following options, according to the IEC standard.
+--si::::
+select the 1000 base for the following options, according to the SI standard.
+--kbytes::::
+show sizes in KiB, or kB with --si.
+--mbytes::::
+show sizes in MiB, or MB with --si.
+--gbytes::::
+show sizes in GiB, or GB with --si.
+--tbytes::::
+show sizes in TiB, or TB with --si.
+
+*label* [<dev>|<mountpoint>] [<newlabel>]::
+Show or update the label of a filesystem. This works on a mounted filesystem or
+a filesystem image.
++
+The 'newlabel' argument is optional. Current label is printed if the the argument
+is omitted.
++
+NOTE: the maximum allowable length shall be less than 256 chars and must not contain
+a newline. The trailing newline is stripped automatically.
+
+// Some wording are extracted by the resize2fs man page
+*resize* [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>::
+Resize a mounted filesystem identified by 'path'. A particular device
+can be resized by specifying a 'devid'.
++
+WARNING: If 'path' is a file containing a BTRFS image then resize does not work
+as expected and does not resize the image. This would resize the underlying
+filesystem instead.
++
+The 'devid' can be found in the output of *btrfs filesystem show* and
+defaults to 1 if not specified.
+The 'size' parameter specifies the new size of the filesystem.
+If the prefix '+' or '-' is present the size is increased or decreased
+by the quantity 'size'.
+If no units are specified, bytes are assumed for 'size'.
+Optionally, the size parameter may be suffixed by one of the following
+units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent
+KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).
++
+If 'max' is passed, the filesystem will occupy all available space on the
+device respecting 'devid' (remember, devid 1 by default).
++
+The resize command does not manipulate the size of underlying
+partition.  If you wish to enlarge/reduce a filesystem, you must make sure you
+can expand the partition before enlarging the filesystem and shrink the
+partition after reducing the size of the filesystem.  This can done using
+`fdisk`(8) or `parted`(8) to delete the existing partition and recreate
+it with the new desired size.  When recreating the partition make sure to use
+the same starting partition offset as before.
++
+Growing is usually instant as it only updates the size. However, shrinking could
+take a long time if there are data in the device area that's beyond the new
+end. Relocation of the data takes time.
++
+See also section 'EXAMPLES'.
+
+*show* [options] [<path>|<uuid>|<device>|<label>]::
+Show the btrfs filesystem with some additional info about devices and space
+allocation.
++
+If no option none of 'path'/'uuid'/'device'/'label' is passed, information
+about all the BTRFS filesystems is shown, both mounted and unmounted.
++
+`Options`
++
+-m|--mounted::::
+probe kernel for mounted BTRFS filesystems
+-d|--all-devices::::
+scan all devices under /dev, otherwise the devices list is extracted from the
+/proc/partitions file. This is a fallback option if there's no device node
+manager (like udev) available in the system.
+--raw::::
+raw numbers in bytes, without the 'B' suffix
+--human-readable::::
+print human friendly numbers, base 1024, this is the default
+--iec::::
+select the 1024 base for the following options, according to the IEC standard
+--si::::
+select the 1000 base for the following options, according to the SI standard
+--kbytes::::
+show sizes in KiB, or kB with --si
+--mbytes::::
+show sizes in MiB, or MB with --si
+--gbytes::::
+show sizes in GiB, or GB with --si
+--tbytes::::
+show sizes in TiB, or TB with --si
+
+*sync* <path>::
+Force a sync of the filesystem at 'path'. This is done via a special ioctl and
+will also trigger cleaning of deleted subvolumes. Besides that it's equivalent
+to the `sync`(1) command.
+
+*usage* [options] <path> [<path>...]::
+Show detailed information about internal filesystem usage. This is supposed to
+replace the *btrfs filesystem df* command in the long run.
++
+The level of detail can differ if the command is run under a regular or the
+root user (due to use of restricted ioctl). For both there's a summary section
+with information about space usage:
++
+-------------------------
+$ btrfs fi usage /path
+WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
+Overall:
+    Device size:                   1.82TiB
+    Device allocated:              1.17TiB
+    Device unallocated:          669.99GiB
+    Device missing:                  0.00B
+    Used:                          1.14TiB
+    Free (estimated):            692.57GiB      (min: 692.57GiB)
+    Data ratio:                       1.00
+    Metadata ratio:                   1.00
+    Global reserve:              512.00MiB      (used: 0.00B)
+-------------------------
++
+The root user will also see stats broken down by block group types:
++
+-------------------------
+Data,single: Size:1.15TiB, Used:1.13TiB
+   /dev/sdb        1.15TiB
+
+Metadata,single: Size:12.00GiB, Used:6.45GiB
+   /dev/sdb       12.00GiB
+
+System,single: Size:32.00MiB, Used:144.00KiB
+   /dev/sdb       32.00MiB
+
+Unallocated:
+   /dev/sdb      669.99GiB
+-------------------------
++
+`Options`
++
+-b|--raw::::
+raw numbers in bytes, without the 'B' suffix
+-h|--human-readable::::
+print human friendly numbers, base 1024, this is the default
+-H::::
+print human friendly numbers, base 1000
+--iec::::
+select the 1024 base for the following options, according to the IEC standard
+--si::::
+select the 1000 base for the following options, according to the SI standard
+-k|--kbytes::::
+show sizes in KiB, or kB with --si
+-m|--mbytes::::
+show sizes in MiB, or MB with --si
+-g|--gbytes::::
+show sizes in GiB, or GB with --si
+-t|--tbytes::::
+show sizes in TiB, or TB with --si
+-T::::
+show data in tabular format
++
+If conflicting options are passed, the last one takes precedence.
+
+EXAMPLES
+--------
+
+*$ btrfs filesystem defrag -v -r dir/*
+
+Recursively defragment files under 'dir/', print files as they are processed.
+The file names will be printed in batches, similarly the amount of data triggered
+by defragmentation will be proportional to last N printed files. The system dirty
+memory throttling will slow down the defragmentation but there can still be a lot
+of IO load and the system may stall for a moment.
+
+*$ btrfs filesystem defrag -v -r -f dir/*
+
+Recursively defragment files under 'dir/', be verbose and wait until all blocks
+are flushed before processing next file. You can note slower progress of the
+output and lower IO load (proportional to currently defragmented file).
+
+*$ btrfs filesystem defrag -v -r -f -clzo dir/*
+
+Recursively defragment files under 'dir/', be verbose, wait until all blocks are
+flushed and force file compression.
+
+*$ btrfs filesystem defrag -v -r -t 64M dir/*
+
+Recursively defragment files under 'dir/', be verbose and try to merge extents
+to be about 64MiB. As stated above, the success rate depends on actual free
+space fragmentation and the final result is not guaranteed to meet the target
+even if run repeatedly.
+
+*$ btrfs filesystem resize -1G /path*
+
+*$ btrfs filesystem resize 1:-1G /path*
+
+Shrink size of the filesystem's device id 1 by 1GiB. The first syntax expects a
+device with id 1 to exist, otherwise fails. The second is equivalent and more
+explicit. For a single-device filesystem it's typically not necessary to
+specify the devid though.
+
+*$ btrfs filesystem resize max /path*
+
+*$ btrfs filesystem resize 1:max /path*
+
+Let's assume that devid 1 exists, the filesystem does not occupy the whole block
+device, eg. it has been enlarged and we wan the grow the filesystem. Simply using
+'max' as size we will achieve that.
+
+NOTE: There are two ways to minimize the filesystem on a given device. The
+*btrfs inspect-internal min-dev-size* command, or iteratively shrink in steps.
+
+EXIT STATUS
+-----------
+*btrfs filesystem* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
diff --git a/Documentation/btrfs-find-root.asciidoc b/Documentation/btrfs-find-root.asciidoc
new file mode 100644
index 00000000..e04cd3e8
--- /dev/null
+++ b/Documentation/btrfs-find-root.asciidoc
@@ -0,0 +1,35 @@
+btrfs-find-root(8)
+==================
+
+NAME
+----
+btrfs-find-root - filter to find btrfs root
+
+SYNOPSIS
+--------
+*btrfs-find-root* [options] <dev>
+
+DESCRIPTION
+-----------
+*btrfs-find-root* is used to find the satisfied root, you can filter by
+root tree's objectid, generation, level.
+
+OPTIONS
+-------
+-a::
+Search through all the metadata extents, even the root is already found.
+-g <generation>::
+Filter root tree by it's original transaction id, tree root's generation in default.
+-o <objectid>::
+Filter root tree by it's objectid,tree root's objectid in default.
+-l <level>::
+Filter root tree by B-+ tree's level, level 0 in default.
+
+EXIT STATUS
+-----------
+*btrfs-find-root* will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/btrfs-image.asciidoc b/Documentation/btrfs-image.asciidoc
new file mode 100644
index 00000000..38265171
--- /dev/null
+++ b/Documentation/btrfs-image.asciidoc
@@ -0,0 +1,66 @@
+btrfs-image(8)
+==============
+
+NAME
+----
+btrfs-image - create/restore an image of the filesystem
+
+SYNOPSIS
+--------
+*btrfs-image* [options] <source> <target>
+
+DESCRIPTION
+-----------
+*btrfs-image* is used to create an image of a btrfs filesystem.
+All data will be zeroed, but metadata and the like is preserved.
+Mainly used for debugging purposes.
+
+In the dump mode, source is the btrfs device/file and target is the output
+file (use '-' for stdout).
+
+In the restore mode (option -r), source is the dumped image and target is the btrfs device/file.
+
+
+OPTIONS
+-------
+-r::
+Restore metadump image. By default, this fixes super's chunk tree, by
+using 1 stripe pointing to primary device, so that file system can be
+restored by running tree log reply if possible. To restore without
+changing number of stripes in chunk tree check -o option.
+
+-c <value>::
+Compression level (0 ~ 9).
+
+-t <value>::
+Number of threads (1 ~ 32) to be used to process the image dump or restore.
+
+-o::
+Use the old restore method, this does not fixup the chunk tree so the restored
+file system will not be able to be mounted.
+
+-s::
+Sanitize the file names when generating the image. One -s means just
+generate random garbage, which means that the directory indexes won't match up
+since the hashes won't match with the garbage filenames. Using -ss will
+calculate a collision for the filename so that the hashes match, and if it
+can't calculate a collision then it will just generate garbage.  The collision
+calculator is very time and CPU intensive so only use it if you are having
+problems with your file system tree and need to have it mostly working.
+
+-w::
+Walk all the trees manually and copy any blocks that are referenced. Use this
+option if your extent tree is corrupted to make sure that all of the metadata is
+captured.
+
+-m::
+Restore for multiple devices, more than 1 device should be provided.
+
+EXIT STATUS
+-----------
+*btrfs-image* will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/btrfs-inspect-internal.asciidoc b/Documentation/btrfs-inspect-internal.asciidoc
new file mode 100644
index 00000000..74f6dea8
--- /dev/null
+++ b/Documentation/btrfs-inspect-internal.asciidoc
@@ -0,0 +1,162 @@
+btrfs-inspect-internal(8)
+=========================
+
+NAME
+----
+btrfs-inspect-internal - query various internal information
+
+SYNOPSIS
+--------
+*btrfs inspect-internal* <subcommand> <args>
+
+DESCRIPTION
+-----------
+
+This command group provides an interface to query internal information. The
+functionality ranges from a simple UI to an ioctl or a more complex query that
+assembles the result from several internal structures. The latter usually
+requires calls to privileged ioctls.
+
+SUBCOMMAND
+----------
+*dump-super* [options] <device> [device...]::
+(replaces the standalone tool *btrfs-show-super*)
++
+Show btrfs superblock information stored on given devices in textual form.
+By default the first superblock is printed, more details about all copies or
+additional backup data can be printed.
++
+Besides verifictaion of the filesystem signature, there are no other sanity
+checks. The superblock checksum status is reported, the device item and
+filesystem UUIDs are checked and reported.
++
+`Options`
++
+-f|--full::::
+print full superblock information, including the system chunk array and backup roots
+-a|--all::::
+print information about all present superblock copies (cannot be used together with '-i' option)
+-i <super_mirror>::::
+specify which mirror to print, valid values are 0, 1 and 2 and the superblock must be present on the device
++
+If there are multiple options specified, only the last one is applies.
++
+-F|--force::::
+attempt to print the superblock even if thre's no valid BTRFS signature found
++
+The result may be completely wrong if the data do not resemble a superblock.
++
+-s <bytenr>::::
+specify offset to a superblock in a non-standard location at 'bytenr', useful
+for debugging (disables the '-f' option)
+
+*dump-tree* [options] <device>::
+(replaces the standalone tool *btrfs-debug-tree*)
++
+Dump tree structures from a given device in textual form, expand keys to human
+readable equivalents where possible.
+This is useful for analyzing filesystem state or inconsistencies and has
+a positive educational effect on understanding the internal filesystem structure.
++
+NOTE: contains file names, consider that if you're asked to send the dump for
+analysis. Does not contain file data.
++
+`Options`
++
+-e|--extents::::
+print only extent-related information: extent and device trees
+-d|--device::::
+print only device-related information: tree root, chunk and device trees
+-r|--roots::::
+print only short root node information, ie. the root tree keys
+-R|--backups::::
+same as --roots plus print backup root info, ie. the backup root keys and
+the respective tree root block offset
+-u|--uuid::::
+print only the uuid tree information, empty output if the tree does not exist
+-b <block_num>::::
+print info of the specified block only
+-t <tree_id>::::
+print only the tree with the specified ID, where the ID can be numerical or
+common name in a flexible human readable form
++
+The tree id name recognition rules:
+[options="compact"]
+* case does not matter
+* the C source definition, eg. BTRFS_ROOT_TREE_OBJECTID
+* short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, eg. ROOT_TREE, ROOT
+* convenience aliases, eg. DEVICE for the DEV tree, CHECKSUM for CSUM
+* unrecognized ID is an error
+
+*inode-resolve* [-v] <ino> <path>::
+(needs root privileges)
++
+resolve paths to all files with given inode number 'ino' in a given subvolume
+at 'path', ie. all hardlinks
++
+`Options`
++
+-v::::
+verbose mode, print count of returned paths and ioctl() return value
+
+*logical-resolve* [-Pv] [-s <bufsize>] <logical> <path>::
+(needs root privileges)
++
+resolve paths to all files at given 'logical' address in the linear filesystem space
++
+`Options`
++
+-P::::
+skip the path resolving and print the inodes instead
+-v::::
+verbose mode, print count of returned paths and all ioctl() return values
+-s <bufsize>::::
+set internal buffer for storing the file names to 'bufsize', default is 4096, maximum 64k
+
+*min-dev-size* [options] <path>::
+(needs root privileges)
++
+return the minimum size the device can be shrunk to, without performing any
+resize operation, this may be useful before executing the actual resize operation
++
+`Options`
++
+--id <id>::::
+specify the device 'id' to query, default is 1 if this option is not used
+
+*rootid* <path>::
+for a given file or directory, return the containing tree root id, for a
+subvolume itself return it's own tree id (ie. subvol id)
++
+NOTE: The result is undefined for the so-called empty subvolumes (identified by
+inode number 2), but such subvolume does not contain any files anyway
+
+*subvolid-resolve* <subvolid> <path>::
+(needs root privileges)
++
+resolve the absolute path of a the subvolume id 'subvolid'
+
+*tree-stats* [options] <device>::
+(needs root privileges)
++
+Print sizes and statistics of trees.
++
+`Options`
++
+-b::::
+Print raw numbers in bytes.
+
+EXIT STATUS
+-----------
+*btrfs inspect-internal* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
new file mode 100644
index 00000000..7dd323fa
--- /dev/null
+++ b/Documentation/btrfs-man5.asciidoc
@@ -0,0 +1,465 @@
+btrfs-man5(5)
+==============
+
+NAME
+----
+btrfs-man5 - topics about the BTRFS filesystem (mount options, supported file attributes and other)
+
+DESCRIPTION
+-----------
+This document describes topics related to BTRFS that are not specific to the
+tools.  Currently covers:
+
+1. mount options
+
+2. file attributes
+
+MOUNT OPTIONS
+-------------
+
+This section describes mount options specific to BTRFS.  For the generic mount
+options please refer to `mount`(8) manpage. The options are sorted alphabetically
+(discarding the 'no' prefix).
+
+*acl*::
+*noacl*::
+(default: on)
++
+Enable/disable support for Posix Access Control Lists (ACLs).  See the
+`acl`(5) manual page for more information about ACLs.
++
+The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL) and
+mount fails if 'acl' is requested but the feature is not compiled in.
+
+*alloc_start='bytes'*::
+(default: 1M, minimum: 1M)
++
+Debugging option to force all block allocations above a certain
+byte threshold on each block device.  The value is specified in
+bytes, optionally with a K, M, or G suffix (case insensitive).
++
+This option was used for testing and has no practical use, it's slated to be
+removed in the future.
+
+*autodefrag*::
+*noautodefrag*::
+(since: 3.0, default: off)
++
+Enable automatic file defragmentation.
+When enabled, small random writes into files (in a range of tens of kilobytes,
+currently it's 64K) are detected and queued up for the defragmentation process.
+Not well suited for large database workloads.
++
+The read latency may increase due to reading the adjacent blocks that make up the
+range for defragmentation, successive write will merge the blocks in the new
+location.
++
+WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
+well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or
+≥ 3.13.4 will break up the ref-links of CoW data (for example files
+copied with `cp --reflink`, snapshots or de-duplicated data).
+This may cause considerable increase of space usage depending on the
+broken up ref-links.
+
+*barrier*::
+*nobarrier*::
+(default: on)
++
+Ensure that all IO write operations make it through the device cache and are stored
+permanently when the filesystem is at it's consistency checkpoint. This
+typically means that a flush command is sent to the device that will
+synchronize all pending data and ordinary metadata blocks, then writes the
+superblock and issues another flush.
++
+The write flushes incur a slight hit and also prevent the IO block
+scheduler to reorder requests in a more effective way. Disabling barriers gets
+rid of that penalty but will most certainly lead to a corrupted filesystem in
+case of a crash or power loss. The ordinary metadata blocks could be yet
+unwritten at the time the new superblock is stored permanently, expecting that
+the block pointers to metadata were stored permanently before.
++
+On a device with a volatile battery-backed write-back cache, the 'nobarrier'
+option will not lead to filesystem corruption as the pending blocks are
+supposed to make it to the permanent storage.
+
+*check_int*::
+*check_int_data*::
+*check_int_print_mask='value'*::
+(since: 3.0, default: off)
++
+These debugging options control the behavior of the integrity checking
+module (the BTRFS_FS_CHECK_INTEGRITY config option required). +
++
+`check_int` enables the integrity checker module, which examines all
+block write requests to ensure on-disk consistency, at a large
+memory and CPU cost. +
++
+`check_int_data` includes extent data in the integrity checks, and
+implies the check_int option. +
++
+`check_int_print_mask` takes a bitmask of BTRFSIC_PRINT_MASK_* values
+as defined in 'fs/btrfs/check-integrity.c', to control the integrity
+checker module behavior. +
++
+See comments at the top of 'fs/btrfs/check-integrity.c'
+for more info.
+
+*clear_cache*::
+Force clearing and rebuilding of the disk space cache if something
+has gone wrong. See also: 'space_cache'.
+
+*commit='seconds'*::
+(since: 3.12, default: 30)
++
+Set the interval of periodic commit. Higher
+values defer data being synced to permanent storage with obvious
+consequences when the system crashes. The upper bound is not forced,
+but a warning is printed if it's more than 300 seconds (5 minutes).
+
+*compress*::
+*compress='type'*::
+*compress-force*::
+*compress-force='type'*::
+(default: off)
++
+Control BTRFS file data compression.  Type may be specified as 'zlib',
+'lzo' or 'no' (for no compression, used for remounting).  If no type
+is specified, 'zlib' is used.  If 'compress-force' is specified,
+all files will be compressed, whether or not they compress well. Otherwise
+some simple heuristics are applied to detect an incompressible file. If the
+first blocks written to a file are not compressible, the whole file is
+permanently marked to skip compression.
++
+NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
+
+*datacow*::
+*nodatacow*::
+(default: on)
++
+Enable data copy-on-write for newly created files.
+'Nodatacow' implies 'nodatasum', and disables 'compression'. All files created
+under 'nodatacow' are also set the NOCOW file attribute (see `chattr`(1)).
++
+NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled.
+
+*datasum*::
+*nodatasum*::
+(default: on)
++
+Enable data checksumming for newly created files.
+'Datasum' implies 'datacow', ie. the normal mode of operation. All files created
+under 'nodatasum' inherit the "no checksums" property, however there's no
+corresponding file attribute (see `chattr`(1)).
++
+NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled.
+
+*degraded*::
+(default: off)
++
+Allow mounts with less devices than the raid profile constraints
+require.  A read-write mount (or remount) may fail with too many devices
+missing, for example if a stripe member is completely missing from RAID0.
+
+*device='devicepath'*::
+Specify a path to a device that will be scanned for BTRFS filesystem during
+mount. This is usually done automatically by a device manager (like udev) or
+using the *btrfs device scan* command (eg. run from the initial ramdisk). In
+cases where this is not possible the 'device' mount option can help.
++
+NOTE: booting eg. a RAID1 system may fail even if all filesystem's 'device'
+paths are provided as the actual device nodes may not be discovered by the
+system at that point.
+
+*discard*::
+*nodiscard*::
+(default: off)
++
+Enable discarding of freed file blocks using TRIM operation.  This is useful
+for SSD devices, thinly provisioned LUNs or virtual machine images where the
+backing device understands the operation. Depending on support of the
+underlying device, the operation may severely hurt performance in case the TRIM
+operation is synchronous (eg. with SATA devices up to revision 3.0).
++
+If discarding is not necessary to be done at the block freeing time, there's
+`fstrim` tool that lets the filesystem discard all free blocks in a batch,
+possibly not much interfering with other operations. Also, the the device may
+ignore the TRIM command if the range is too small, so running the batch discard
+can actually discard the blocks.
+
+*enospc_debug*::
+*noenospc_debug*::
+(default: off)
++
+Enable verbose output for some ENOSPC conditions. It's safe to use but can
+be noisy if the system reaches near-full state.
+
+*fatal_errors='action'*::
+(since: 3.4, default: bug)
++
+Action to take when encountering a fatal error.
++
+*bug*::::
+'BUG()' on a fatal error, the system will stay in the crashed state and may be
+still partially usable, but reboot is required for full operation
++
+*panic*::::
+'panic()' on a fatal error, depending on other system configuration, this may
+be followed by a reboot. Please refer to the documentation of kernel boot
+parameters, eg. 'panic', 'oops' or 'crashkernel'.
+
+*flushoncommit*::
+*noflushoncommit*::
+(default: on)
++
+This option forces any data dirtied by a write in a prior transaction to commit
+as part of the current commit.  This makes the committed state a fully
+consistent view of the file system from the application's perspective (i.e., it
+includes all completed file system operations).  This was previously the
+behavior only when a snapshot was created.
++
+Disabling flushing may improve performance but is not crash-safe.
+
+*fragment='type'*::
+(depends on compile-time option BTRFS_DEBUG, since: 4.4, default: off)
++
+A debugging helper to intentionally fragment given 'type' of block groups. The
+type can be 'data', 'metadata' or 'all'. This mount option should not be used
+outside of debugging environments and is not recognized if the kernel config
+option 'BTRFS_DEBUG' is not enabled.
+
+*inode_cache*::
+*noinode_cache*::
+(since: 3.0, default: off)
++
+Enable free inode number caching. Not recommended to use unless files on your
+filesystem get assigned inode numbers that are approaching 2^64^. Normally, new
+files in each subvolume get assigned incrementally (plus one from the last
+time) and are not reused. The mount option turns on caching of the existing
+inode numbers and reuse of inode numbers of deleted files.
++
+This option may slow down your system at first run, or after mounting without
+the option.
++
+NOTE: Defaults to off due to a potential overflow problem when the free space
+checksums don't fit inside a single page.
+
+*logreplay*::
+*nologreplay*::
+(default: on, even read-only)
++
+Enable/disable log replay at mount time. See also 'treelog'.
++
+WARNING: currently, the tree log is replayed even with a read-only mount! To
+disable that behaviour, mount also with 'nologreplay'.
+
+*max_inline='bytes'*::
+(default: min(2048, page size) )
++
+Specify the maximum amount of space, in bytes, that can be inlined in
+a metadata B-tree leaf.  The value is specified in bytes, optionally
+with a K suffix (case insensitive).  In practice, this value
+is limited by the filesystem block size (named 'sectorsize' at mkfs time),
+and memory page size of the system. In case of sectorsize limit, there's
+some space unavailable due to leaf headers.  For example, a 4k sectorsize,
+maximum size of inline data is about 3900 bytes.
++
+Inlining can be completely turned off by specifying 0. This will increase data
+block slack if file sizes are much smaller than block size but will reduce
+metadata consumption in return.
++
+NOTE: the default value has changed to 2048 in kernel 4.6.
+
+*metadata_ratio='value'*::
+(default: 0, internal logic)
++
+Specifies that 1 metadata chunk should be allocated after every 'value' data
+chunks. Default behaviour depends on internal logic, some percent of unused
+metadata space is attempted to be maintained but is not always possible if
+there's not enough space left for chunk allocation. The option could be useful to
+override the internal logic in favor of the metadata allocation if the expected
+workload is supposed to be metadata intense (snapshots, reflinks, xattrs,
+inlined files).
+
+*recovery*::
+(since: 3.2, default: off, deprecated since: 4.5)
++
+NOTE: this option has been replaced by 'usebackuproot' and should not be used
+but will work on 4.5+ kernels.
+
+*norecovery*::
+(since: 4.5, default: off)
++
+Do not attempt any data recovery at mount time. This will disable 'logreplay'
+and avoids other write operations.
++
+NOTE: The opposite option 'recovery' used to have different meaning but was
+changed for consistency with other filesystems, where 'norecovery' is used for
+skipping log replay. BTRFS does the same and in general will try to avoid any
+write operations.
+
+*rescan_uuid_tree*::
+(since: 3.12, default: off)
++
+Force check and rebuild procedure of the UUID tree. This should not
+normally be needed.
+
+*skip_balance*::
+(since: 3.3, default: off)
++
+Skip automatic resume of interrupted balance operation after mount.
+May be resumed with *btrfs balance resume* or the paused state can be removed
+by *btrfs balance cancel*. The default behaviour is to start interrutpd balance.
+
+*space_cache*::
+*space_cache=v2*::
+*nospace_cache*::
+('nospace_cache' since: 3.2, 'space_cache=v2' since 4.5, default: on)
++
+Options to control the free space cache.  This affects performance as searching
+for new free blocks could take longer if the space cache is not enabled. On the
+other hand, managing the space cache consumes some resources.  It can be
+disabled without clearing at mount time.
++
+There are two implementations of how the space is tracked. The safe default is
+'v1'.  On large filesystems (many-terabytes) and certain workloads the 'v1'
+performance may degrade.  This problem is addressed by 'v2', that is based on
+b-trees, sometimes referred to as 'free-space-tree'.
++
+'Compatibility notes:'
++
+* the 'v2' has to be enabled manually at mount time, once
+* kernel without 'v2' support will be able to mount the filesystem in read-only mode
+* 'v2' can be removed by mounting with 'clear_cache'
+
+*ssd*::
+*nossd*::
+*ssd_spread*::
+(default: SSD autodetected)
++
+Options to control SSD allocation schemes.  By default, BTRFS will
+enable or disable SSD allocation heuristics depending on whether a
+rotational or non-rotational disk is in use (contents of
+'/sys/block/DEV/queue/rotational').  The 'ssd' and 'nossd' options
+can override this autodetection.
++
+The 'ssd_spread' mount option attempts to allocate into bigger and aligned
+chunks of unused space, and may perform better on low-end SSDs.  'ssd_spread'
+implies 'ssd', enabling all other SSD heuristics as well.
+
+*subvol='path'*::
+Mount subvolume from 'path' rather than the toplevel subvolume. The
+'path' is absolute (ie. starts at the toplevel subvolume).
+This mount option overrides the default subvolume set for the given filesystem.
+
+*subvolid='subvolid'*::
+Mount subvolume specified by a 'subvolid' number rather than the toplevel
+subvolume.  You can use *btrfs subvolume list* to see subvolume ID numbers.
+This mount option overrides the default subvolume set for the given filesystem.
++
+NOTE: if both 'subvolid' and 'subvol' are specified, they must point at the
+same subvolume, otherwise mount will fail.
+
+*subvolrootid='objectid'*::
+(irrelevant since: 3.2, formally deprecated since: 3.10)
++
+A workaround option from times (pre 3.2) when it was not possible to mount a
+subvolume that did not reside directly under the toplevel subvolume.
+
+*thread_pool='number'*::
+(default: min(NRCPUS + 2, 8) )
++
+The number of worker threads to allocate. NRCPUS is number of on-line CPUs
+detected at the time of mount. Small number leads to less parallelism in
+processing data and metadata, higher numbers could lead to a performance hit
+due to increased locking contention, cache-line bouncing or costly data
+transfers between local CPU memories.
+
+*treelog*::
+*notreelog*::
+(default: on)
++
+Enable the tree logging used for 'fsync' and 'O_SYNC' writes. The tree log
+stores changes without the need of a full filesystem sync. The log operations
+are flushed at sync and transaction commit. If the system crashes between two
+such syncs, the pending tree log operations are replayed during mount.
++
+WARNING: currently, the tree log is replayed even with a read-only mount! To
+disable that behaviour, mount also with 'nologreplay'.
++
+The tree log could contain new files/directories, these would not exist on
+a mounted filesystem if the log is not replayed.
+
+*usebackuproot*::
+*nousebackuproot*::
++
+Enable autorecovery attempts if a bad tree root is found at mount time.
+Currently this scans a backup list of several previous tree roots and tries to
+use the first readable. This can be used with read-only mounts as well.
++
+NOTE: This option has replaced 'recovery'.
+
+*user_subvol_rm_allowed*::
+(default: off)
++
+Allow subvolumes to be deleted by their respective owner. Otherwise, only the
+root user can do that.
+
+FILE ATTRIBUTES
+---------------
+The btrfs filesystem supports setting the following file attributes using the
+`chattr`(1) utility:
+
+*a*::
+'append only', new writes are always written at the end of the file
+
+*A*::
+'no atime updates'
+
+*c*::
+'compress data', all data written after this attribute is set will be compressed.
+Please note that compression is also affected by the mount options or the parent
+directory attributes.
++
+When set on a directory, all newly created files will inherit this attribute.
+
+*C*::
+'no copy-on-write', file modifications are done in-place
++
+When set on a directory, all newly created files will inherit this attribute.
++
+NOTE: due to implementation limitations, this flag can be set/unset only on
+empty files.
+
+*d*::
+'no dump', makes sense with 3rd party tools like `dump`(8), on BTRFS the
+attribute can be set/unset on no other special handling is done
+
+*D*::
+'synchronous directory updates', for more details search `open`(2) for 'O_SYNC'
+and 'O_DSYNC'
+
+*i*::
+'immutable', no file data and metadata changes allowed even to the root user as
+long as this attribute is set (obviously the exception is unsetting the attribute)
+
+*S*::
+'synchronous updates', for more details search `open`(2) for 'O_SYNC' and
+'O_DSYNC'
+
+*X*::
+'no compression', permanently turn off compression on the given file, other
+compression mount options will not affect that
++
+When set on a directory, all newly created files will inherit this attribute.
+
+No other attributes are supported.  For the complete list please refer to the
+`chattr`(1) manual page.
+
+SEE ALSO
+--------
+`acl`(5),
+`btrfs`(8),
+`chattr`(1),
+`fstrim`(8),
+`mkfs.btrfs`(8),
+`mount`(8)
diff --git a/Documentation/btrfs-map-logical.asciidoc b/Documentation/btrfs-map-logical.asciidoc
new file mode 100644
index 00000000..a3d110cb
--- /dev/null
+++ b/Documentation/btrfs-map-logical.asciidoc
@@ -0,0 +1,37 @@
+btrfs-map-logical(8)
+====================
+
+NAME
+----
+btrfs-map-logical - map btrfs logical extent to physical extent
+
+SYNOPSIS
+--------
+*btrfs-map-logical* <options> <device>
+
+DESCRIPTION
+-----------
+*btrfs-map-logical* can be used to find out what the physical offsets are
+on the mirrors, the result is dumped into stdout in default.
+
+Mainly used for debug purpose.
+
+OPTIONS
+-------
+-l|--logical <logical_num>::
+Logical extent to map.
+-c|--copy <copy>::
+Copy of the extent to read(usually 1 or 2).
+-o|--output <filename>::
+Output file to hold the extent.
+-b|--bytes <bytes>::
+Number of bytes to read.
+
+EXIT STATUS
+-----------
+*btrfs-map-logical* will return 0 if no error happened.
+If any problems happened, 1 will be returned.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/btrfs-property.asciidoc b/Documentation/btrfs-property.asciidoc
new file mode 100644
index 00000000..8b9b7f03
--- /dev/null
+++ b/Documentation/btrfs-property.asciidoc
@@ -0,0 +1,73 @@
+btrfs-property(8)
+=================
+
+NAME
+----
+btrfs-property - get/set/list properties for given btrfs object.
+
+SYNOPSIS
+--------
+*btrfs property* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs property* is used to get/set/list property for given btrfs object.
+See the description of *get* subcommand for more information about
+both btrfs object and property.
+
+*btrfs property* provides an unified and user-friendly method to tune different
+btrfs properties instead of using the traditional method like `chattr`(1) or
+`lsattr`(1).
+
+SUBCOMMAND
+----------
+*get* [-t <type>] <object> [<name>]::
+Gets a property from a btrfs object.
++
+A btrfs object, which is set by <object>, can be a btrfs filesystem
+itself, a btrfs subvolume, an inode(file or directory) inside btrfs,
+or a device on which a btrfs exists.
++
+The '-t <type>' option can be used to explicitly
+specify what type of object you meant. This is only needed when a
+property could be set for more then one object type.
++
+Possible types are 's[ubvol]', 'f[ilesystem]', 'i[node]' and 'd[evice]'.
++
+Set the name of property by '<name>'. If no '<name>' is specified,
+all properties for the given object are printed. '<name>' is one of
+the followings.
+
+ro::::
+read-only flag of subvolume: true or false
+label::::
+label of device
+compression::::
+compression setting for an inode: lzo, zlib, or "" (empty string)
+
+*list* [-t <type>] <object>::
+Lists available properties with their descriptions for the given object.
++
+See the description of *get* subcommand for the meaning of each option.
+
+*set* [-t <type>] <object> <name> <value>::
+Sets a property on a btrfs object.
++
+See the description of *get* subcommand for the meaning of each option.
+
+EXIT STATUS
+-----------
+*btrfs property* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`lsattr`(1),
+`chattr`(1)
diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc
new file mode 100644
index 00000000..438dbc7d
--- /dev/null
+++ b/Documentation/btrfs-qgroup.asciidoc
@@ -0,0 +1,145 @@
+btrfs-qgroup(8)
+===============
+
+NAME
+----
+btrfs-qgroup - control the quota group of a btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs qgroup* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs qgroup* is used to control quota group (qgroup) of a btrfs filesystem.
+
+NOTE: To use qgroup you need to enable quota first using *btrfs quota enable*
+command.
+
+WARNING: Qgroup is not stable yet and will impact performance in current mainline
+kernel (v3.14 so far).
+
+QGROUP
+------
+Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are
+attached to subvolumes. The size limits are set per qgroup and apply when any
+limit is reached in tree that contains a given subvolume.
+
+The limits are separated between shared and exclusive and reflect the extent
+ownership. For example a fresh snapshot shares almost all the blocks with the
+original subvolume, new writes to either subvolume will raise towards the
+exclusive limit.
+
+The qgroup identifiers conform to 'level/id' where level 0 is reserved to the
+qgroups associated with subvolumes. Such qgroups are created automatically.
+
+The qgroup hierarchy is built by commands *create* and *assign*.
+
+NOTE: If the qgroup of a subvolume is destroyed, quota about the subvolume
+will not be functional until qgroup '0/<subvolume id>' is created again.
+
+SUBCOMMAND
+----------
+*assign* [options] <src> <dst> <path>::
+Assign qgroup <src> as the child qgroup of <dst> in the btrfs filesystem
+identified by <path>.
++
+`Options`
++
+--rescan::::
+Automatically schedule quota rescan if the new qgroup assignment leads to
+quota inconsistency.
+--no-rescan::::
+Explicitly ask not to do a rescan.
+
+*create* <qgroupid> <path>::
+Create a subvolume quota group.
++
+For the '0/<subvolume id>' qgroup, a qgroup can be created even before the
+subvolume created.
+
+*destroy* <qgroupid> <path>::
+Destroy a qgroup.
++
+If a qgroup is no isolated,which means it is a parent or child qgroup, it
+can't be destroyed.
+
+*limit* [options] <size>|none [<qgroupid>] <path>::
+Limit the size of a qgroup to <size> or no limit in the btrfs filesystem
+identified by <path>.
++
+If <qgroupid> is not given, qgroup of the subvolume identified by <path>
+is used if possible.
++
+`Options`
++
+-c::::
+limit amount of data after compression. This is the default, it is currently not
+possible to turn off this option.
++
+-e::::
+limit space exclusively assigned to this qgroup.
+
+*remove* <src> <dst> <path>::
+Remove the relationship between child qgroup <src> and parent qgroup <dst> in
+the btrfs filesystem identified by <path>.
+
+*show* [options] <path>::
+Show all qgroups in the btrfs filesystem identified by <path>.
++
+`Options`
++
+-p::::
+print parent qgroup id.
+-c::::
+print child qgroup id.
+-r::::
+print limit of referenced size of qgroup.
+-e::::
+print limit of exclusive size of qgroup.
+-F::::
+list all qgroups which impact the given path(include ancestral qgroups)
+-f::::
+list all qgroups which impact the given path(exclude ancestral qgroups)
+--raw::::
+raw numbers in bytes, without the 'B' suffix.
+--human-readable::::
+print human friendly numbers, base 1024, this is the default
+--iec::::
+select the 1024 base for the following options, according to the IEC standard.
+--si::::
+select the 1000 base for the following options, according to the SI standard.
+--kbytes::::
+show sizes in KiB, or kB with --si.
+--mbytes::::
+show sizes in MiB, or MB with --si.
+--gbytes::::
+show sizes in GiB, or GB with --si.
+--tbytes::::
+show sizes in TiB, or TB with --si.
+--sort=[\+/-]<attr>[,[+/-]<attr>]...::::
+list qgroups in order of <attr>.
++
+<attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl.
++
+Prefix \'+' means ascending order and \'-' means descending order of <attr>.
+If no prefix is given, use ascending order by default.
++
+If multiple <attr>s is given, use comma to separate.
+
+EXIT STATUS
+-----------
+*btrfs qgroup* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-subvolume`(8),
+`btrfs-quota`(8),
diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc
new file mode 100644
index 00000000..00e09c61
--- /dev/null
+++ b/Documentation/btrfs-quota.asciidoc
@@ -0,0 +1,56 @@
+btrfs-quota(8)
+==============
+
+NAME
+----
+btrfs-quota - control the quota of a btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs quota* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs quota* is used to enable/disable or rescan subvolume quota of a btrfs
+filesystem.
+
+For setting quota or other quota operations on a btrfs filesystem, please see
+`btrfs-qgroup`(8) for details.
+
+WARNING: Quota and qgroup in btrfs filesystem is not stable and impacts
+performance in mainline kernel yet(v3.14 so far).
+
+SUBCOMMAND
+----------
+*disable* <path>::
+Disable subvolume quota support for a filesystem.
+
+*enable* <path>::
+Enable subvolume quota support for a filesystem.
+
+*rescan* [-s] <path>::
+Trash all qgroup numbers and scan the metadata again with the current config.
++
+`Options`
++
+-s::::
+show status of a running rescan operation.
+-w::::
+wait for rescan operation to finish(can be already in progress).
+
+EXIT STATUS
+-----------
+*btrfs quota* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-subvolume`(8),
+`btrfs-qgroup`(8)
diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc
new file mode 100644
index 00000000..e246603c
--- /dev/null
+++ b/Documentation/btrfs-receive.asciidoc
@@ -0,0 +1,73 @@
+btrfs-receive(8)
+================
+
+NAME
+----
+btrfs-receive - receive subvolumes from send stream
+
+SYNOPSIS
+--------
+*btrfs receive* [options] <path>
+
+DESCRIPTION
+-----------
+
+Receive a stream of changes and replicate one or more subvolumes that were
+previously used with *btrfs send* The received subvolumes are stored to
+'path'.
+
+*btrfs receive* will fail int the following cases:
+
+1. receiving subvolume already exists
+
+2. previously received subvolume was changed after it was received
+
+3. default subvolume has changed or you didn't mount BTRFS filesystem at the toplevel subvolume
+
+A subvolume is made read-only after the receiving process finishes succesfully.
+
+`Options`
+
+-v::
+enable verbose debug output, print each operation (each occurrence of this
+option increases the verbosity level)
+
+-f <infile>::
+by default, btrfs receive uses standard input to receive the stream,
+use this option to read from a file instead
+
+-C|--chroot::
+confine the process to 'path' using `chroot`(1)
+
+-e::
+terminate after receiving an 'end cmd' marker in the stream.
++
+Without this option, the receiver terminates only if an error is encountered
+or at end of file
+
+--max-errors <N>::
+terminate as soon as N errors happened while processing commands from the send
+stream, default value is 1, 0 means no limit
+
+-m <mountpoint>::
+the root mount point of the destination filesystem
++
+By default the mountpoint is searched in '/proc/self/mounts'.
+If you do not have '/proc', eg. in a chroot environment, use this option to tell
+us where this filesystem is mounted.
+
+EXIT STATUS
+-----------
+*btrfs receive* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-send`(8)
diff --git a/Documentation/btrfs-replace.asciidoc b/Documentation/btrfs-replace.asciidoc
new file mode 100644
index 00000000..a259f96d
--- /dev/null
+++ b/Documentation/btrfs-replace.asciidoc
@@ -0,0 +1,80 @@
+btrfs-replace(8)
+===============
+
+NAME
+----
+btrfs-replace - replace devices managed by btrfs with other device.
+
+SYNOPSIS
+--------
+*btrfs replace* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs replace* is used to replace btrfs managed devices with other device.
+
+SUBCOMMAND
+----------
+*cancel* <mount_point>::
+Cancel a running device replace operation.
+
+*start* [-Bfr] <srcdev>|<devid> <targetdev> <path>::
+Replace device of a btrfs filesystem.
++
+On a live filesystem, duplicate the data to the target device which
+is currently stored on the source device.
+If the source device is not available anymore, or if the -r option is set,
+the data is built only using the RAID redundancy mechanisms.
+After completion of the operation, the source device is removed from the
+filesystem.
+If the <srcdev> is a numerical value, it is assumed to be the device id
+of the filesystem which is mounted at <path>, otherwise is is
+the path to the source device. If the source device is disconnected,
+from the system, you have to use the devid parameter format.
+The <targetdev> needs to be same size or larger than the <srcdev>.
++
+NOTE: the filesystem has to be resized to fully take advantage of a
+larger target device, this can be achieved with
+`btrfs filesystem resize <devid>:max /path`
++
+`Options`
++
+-r::::
+only read from <srcdev> if no other zero-defect mirror exists.
+(enable this if your drive has lots of read errors, the access would be very
+slow)
+-f::::
+force using and overwriting <targetdev> even if it looks like
+containing a valid btrfs filesystem.
++
+A valid filesystem is assumed if a btrfs superblock is found which contains a
+correct checksum. Devices which are currently mounted are
+never allowed to be used as the <targetdev>.
++
+-B::::
+no background replace.
+
+*status* [-1] <mount_point>::
+Print status and progress information of a running device replace operation.
++
+`Options`
++
+-1::::
+print once instead of print continuously until the replace
+operation finishes (or is cancelled)
+
+EXIT STATUS
+-----------
+*btrfs replace* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-device`(8),
diff --git a/Documentation/btrfs-rescue.asciidoc b/Documentation/btrfs-rescue.asciidoc
new file mode 100644
index 00000000..42aca645
--- /dev/null
+++ b/Documentation/btrfs-rescue.asciidoc
@@ -0,0 +1,90 @@
+btrfs-rescue(8)
+==============
+
+NAME
+----
+btrfs-rescue - Recover a damaged btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs rescue* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs rescue* is used to try to recover a damaged btrfs filesystem.
+
+SUBCOMMAND
+----------
+*chunk-recover* [options] <device>::
+Recover the chunk tree by scanning the devices
++
+`Options`
++
+-y::::
+assume an answer of 'yes' to all questions.
+-v::::
+verbose mode.
+-h::::
+help.
+
+NOTE: Since *chunk-recover* will scan the whole device, it will be *VERY* slow
+especially executed on a large device.
+
+*super-recover* [options] <device>::
+Recover bad superblocks from good copies.
++
+`Options`
++
+-y::::
+assume an answer of 'yes' to all questions.
+-v::::
+verbose mode.
+
+*zero-log* <device>::
+clear the filesystem log tree
+
+This command will clear the filesystem log tree. This may fix a specific
+set of problem when the filesystem mount fails due to the log replay. See below
+for sample stacktraces that may show up in system log.
+
+The common case where this happens has been fixed a long time ago,
+so it is unlikely that you will see this particular problem, but the utility is
+kept around.
+
+NOTE: clearing the log may lead to loss of changes that were made since the
+last transaction commit. This may be up to 30 seconds (default commit period)
+or less if the commit was implied by other filesystem activity.
+
+One can determine whether *zero-log* is needed according to the kernel
+backtrace:
+----
+? replay_one_dir_item+0xb5/0xb5 [btrfs]
+? walk_log_tree+0x9c/0x19d [btrfs]
+? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs]
+? btrfs_recover_log_trees+0x195/0x29c [btrfs]
+? replay_one_dir_item+0xb5/0xb5 [btrfs]
+? btree_read_extent_buffer_pages+0x76/0xbc [btrfs]
+? open_ctree+0xff6/0x132c [btrfs]
+----
+
+If the errors are like above, then *zero-log* should be used to clear
+the log and the filesystem may be mounted normally again. The keywords to look
+for are 'open_ctree' which says that it's during mount and function names
+that contain 'replay', 'recover' or 'log_tree'.
+
+EXIT STATUS
+-----------
+*btrfs rescue* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-scrub`(8),
+`btrfs-check`(8)
diff --git a/Documentation/btrfs-restore.asciidoc b/Documentation/btrfs-restore.asciidoc
new file mode 100644
index 00000000..41e90e2f
--- /dev/null
+++ b/Documentation/btrfs-restore.asciidoc
@@ -0,0 +1,108 @@
+btrfs-restore(8)
+================
+
+NAME
+----
+btrfs-restore - try to restore files from a damaged btrfs filesystem image
+
+SYNOPSIS
+--------
+*btrfs restore* [options] <device> <path> | -l <device>
+
+DESCRIPTION
+-----------
+*btrfs restore* is used to try to salvage files from a damaged filesystem and
+restore them into <path> or just list the subvolume tree roots. The filesystem
+image is not modified.
+
+If the filesystem is damaged and cannot be repaired by the other tools
+(`btrfs-check`(8) or `btrfs-rescue`(8)), *btrfs restore* could be used to
+retrieve file data, as far as the metadata are readable. The checks done by
+restore are less strict and the process is usually able to get far enough to
+retrieve data from the whole filesystem. This comes at a cost that some data
+might be incomplete or from older versions if they're available.
+
+There are several options to attempt restoration of various file metadata type.
+You can try a dry run first to see how well the process goes and use further
+options to extend the set of restored metadata.
+
+For images with damaged tree structures, there are several options to point the
+process to some spare copy.
+
+NOTE: It is recommended to read the following btrfs wiki page if your data is
+not salvaged with default option: +
+https://btrfs.wiki.kernel.org/index.php/Restore
+
+OPTIONS
+-------
+-s|--snapshots::
+get also snapshots that are skippped by default
+
+-x|--xattr::
+get extended attributes
+
+-m|--metadata::
+restore owner, mode and times for files and directories
+
+-S|--symlinks::
+restore symbolic links as well as normal files
+
+-v|--verbose::
+be verbose and print what is being restored
+
+-i|--ignore-errors::
+ignore errors during restoration and continue
+
+-o|--overwrite::
+overwrite directories/files in <path>, eg. for repeated runs
+
+-t <bytenr>::
+use <bytenr> to read the root tree
+
+-f <bytenr>::
+only restore files that are under specified subvolume root pointed by <bytenr>
+
+-u|--super <mirror>::
+use given superblock mirror identified by <mirror>, it can be 0,1 or 2
+
+-r|--root <rootid>::
+only restore files that are under a specified subvolume whose objectid is <rootid>
+
+-d::
+find directory
+
+-l|--list-roots::
+list subvolume tree roots, can be used as argument for '-r'
+
+-D|--dry-run::
+dry run (only list files that would be recovered)
+
+--path-regex <regex>::
+restore only filenames matching a regular expression (`regex`(7)) with a
+mandatory format
++
++^/(|home(|/username(|/Desktop(|/.*))))$+
++
+The format is not very comfortable and restores all files in the directories
+in the whole path, so this is not useful for restoring single file in a deep
+hierarchy.
+
+-c::
+ignore case (--path-regex only)
+
+EXIT STATUS
+-----------
+*btrfs restore* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-rescue`(8),
+`btrfs-check`(8)
diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc
new file mode 100644
index 00000000..83ddcaa7
--- /dev/null
+++ b/Documentation/btrfs-scrub.asciidoc
@@ -0,0 +1,97 @@
+btrfs-scrub(8)
+==============
+
+NAME
+----
+btrfs-scrub - scrub btrfs filesystem, verify block checksums
+
+SYNOPSIS
+--------
+*btrfs scrub* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs scrub* is used to scrub a btrfs filesystem, which will read all data
+and metadata blocks from all disks and verify checksums. Automatically repair
+corrupted blocks if there's a correct copy available.
+
+SUBCOMMAND
+----------
+*cancel* <path>|<device>::
+If a scrub is running on the filesystem identified by 'path>' cancel it.
++
+Progress is saved in the scrub progress file ('/var/lib/btrfs/scrub.status.UUID')
+and scrubbing can be resumed later using the *btrfs scrub resume* command.
+If a 'device' is specified, the corresponding filesystem is found and
+*btrfs scrub cancel* behaves as if it was called on that filesystem.
+
+*resume* [-BdqrR] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>::
+Resume a cancelled or interrupted scrub on the filesystem identified by
+'path' or on a given 'device'.
++
+Does not start a new scrub if the last scrub finished successfully.
++
+`Options`
++
+see *scrub start*.
+
+*start* [-BdqrRf] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>::
+Start a scrub on all devices of the filesystem identified by 'path' or on
+a single 'device'. If a scrub is already running, the new one fails.
++
+Without options, scrub is started as a background process.
+Progress can be obtained with the *btrfs scrub status* command. Scrubbing
+involves reading all data from all disks and verifying checksums. Errors are
+corrected along the way if possible.
++
+The default IO priority of scrub is the idle class. The priority can be
+configured similar to the `ionice`(1) syntax using '-c' and '-n' options.
++
+`Options`
++
+-B::::
+do not background and print scrub statistics when finished
+-d::::
+print separate statistics for each device of the filesystem ('-B' only)
+-q::::
+be quiet, omit error messages and statistics
+-r::::
+read only mode, do not attempt to correct anything, can be run on a read-only
+filesystem
+-R::::
+print raw statistics per-device instead of a summary
+-c <ioprio_class>::::
+set IO priority class (see `ionice`(1) manpage)
+-n <ioprio_classdata>::::
+set IO priority classdata (see `ionice`(1) manpage)
+-f::::
+force starting new scrub even if a scrub is already running,
+this is useful when scrub status file is damaged and reports a running
+scrub although it is not
+
+*status* [-d] <path>|<device>::
+Show status of a running scrub for the filesystem identified by 'path' or
+for the specified 'device'.
++
+If no scrub is running, show statistics of the last finished or cancelled scrub
+for that filesystem or device.
++
+`Options`
++
+-d::::
+print separate statistics for each device of the filesystem
+
+EXIT STATUS
+-----------
+*btrfs scrub* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
diff --git a/Documentation/btrfs-select-super.asciidoc b/Documentation/btrfs-select-super.asciidoc
new file mode 100644
index 00000000..6e94a034
--- /dev/null
+++ b/Documentation/btrfs-select-super.asciidoc
@@ -0,0 +1,47 @@
+btrfs-select-super(8)
+=====================
+
+NAME
+----
+btrfs-select-super - overwrite primary superblock with a backup copy
+
+SYNOPSIS
+--------
+*btrfs-select-super* -s number <device>
+
+DESCRIPTION
+-----------
+Destructively overwrite all copies of the superblock
+with a specified copy.  This helps in certain cases, for example when write
+barriers were disabled during a power failure and not all superblocks were
+written, or if the primary superblock is damaged, eg. accidentally overwritten.
+
+The filesystem specified by 'device' must not be mounted.
+
+NOTE: *Prior to overwriting the primary superblock, please make sure that the backup
+copies are valid!*
+
+To dump a superblock use the *btrfs inspect-internal
+dump-super* command, or the obsolete command *btrfs-show-super*.
+
+Then run the check (in the non-repair mode) using the command *btrfs check -s*
+where '-s' specifies the superblock copy to use.
+
+Superblock copies exist in the following offsets on the device:
+
+- primary: '64KiB' (65536)
+- 1st copy: '64MiB' (67108864)
+- 2nd copy: '256GiB' (274877906944)
+
+A superblock size is '4KiB' (4096).
+
+OPTIONS
+-------
+-s|--super <superblock>::
+use 'superblock'th superblock copy, valid values are 0 1 or 2 if the
+respective superblock offset is within the device size
+
+SEE ALSO
+--------
+`btrfs-inspect-internal`(8),
+`btrfsck check`(8)
diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc
new file mode 100644
index 00000000..47b0b047
--- /dev/null
+++ b/Documentation/btrfs-send.asciidoc
@@ -0,0 +1,76 @@
+btrfs-send(8)
+=============
+
+NAME
+----
+btrfs-send - generate a stream of changes between two subvolumes
+
+SYNOPSIS
+--------
+*btrfs send* [-ve] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol> [<subvol>...]
+
+DESCRIPTION
+-----------
+
+This command will generate a stream of instructions that describe changes
+between two subvolumes. The stream can be consumed by the *btrfs receive*
+command to replicate the sent subvolume on a different filesystem.
+The command operates in two modes: full and incremental.
+
+All subvolumes involved in one send command must be read-only (ie. the
+read-only snapshots and this status cannot be changed if there's a running send
+operation that uses the subvolume).
+
+In the full mode, the entire subvolume data and metadata will end up in the
+stream.
+
+In the incremental mode (options '-p' and '-c'), there can be one or more
+parent subvolumes that will establish the base for determining the changes.
+The final stream will be smaller compared to the full mode.
+
+It is allowed to omit the '-p <parent>' option when '-c <clone-src>' options
+are given, in which case *btrfs send* will determine a suitable parent among the
+clone sources itself.
+
+You must not specify clone sources unless you guarantee that these snapshots
+are exactly in the same state on both sides, the sender and the receiver.
+
+`Options`
+
+-e::
+if sending multiple subvolumes at once, use the new format and omit the
+'end cmd' marker in the stream separating the subvolumes
+-p <parent>::
+send an incremental stream from 'parent' to 'subvol'
+-c <clone-src>::
+use this snapshot as a clone source for an incremental send (multiple allowed)
+-f <outfile>::
+output is normally written to standard outout so it can be eg. piped to
+receive, use this option to write it to a file
+--no-data::
+send in 'NO_FILE_DATA' mode
++
+The output stream does not contain any file
+data and thus cannot be used to transfer changes. This mode is faster and
+useful to show the differences in metadata.
+-v|--verbose::
+enable verbose output, print generated commands in a readable form, (each
+occurrence of this option increases the verbosity level)
+-q|--quiet::
+suppress all messagese except errors
+
+EXIT STATUS
+-----------
+*btrfs send* returns a zero exit status if it succeeds. Non zero is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-receive`(8)
diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
new file mode 100644
index 00000000..fb64aa4a
--- /dev/null
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -0,0 +1,182 @@
+btrfs-subvolume(8)
+==================
+
+NAME
+----
+btrfs-subvolume - control btrfs subvolume(s)
+
+SYNOPSIS
+--------
+*btrfs subvolume* <subcommand> [<args>]
+
+DESCRIPTION
+-----------
+*btrfs subvolume* is used to control the filesystem to create/delete/list/show
+subvolumes and snapshots.
+
+SUBVOLUME AND SNAPSHOT
+----------------------
+A subvolume in btrfs is not like an LVM logical volume, which is quite
+independent from each other, a btrfs subvolume has its hierarchy and relations
+between other subvolumes.
+
+A subvolume in btrfs can be accessed in two ways.
+
+1. From the parent subvolume +
+When accessing from the parent subvolume, the subvolume can be used just
+like a directory. It can have child subvolumes and its own files/directories.
+
+2. Separate mounted filesystem +
+When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access
+files/directories/subvolumes inside it, but nothing in parent subvolumes.
+
+Also every btrfs filesystem has a default subvolume as its initially top-level
+subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.)
+
+A btrfs snapshot is much like a subvolume, but shares its data(and metadata)
+with other subvolume/snapshot. Due to the capabilities of COW, modifications
+inside a snapshot will only show in a snapshot but not in its source subvolume.
+
+Although in btrfs, subvolumes/snapshots are treated as directories, only
+subvolume/snapshot can be the source of a snapshot, snapshot can not be made
+from normal directories.
+
+SUBCOMMAND
+-----------
+*create* [-i <qgroupid>] [<dest>]<name>::
+Create a subvolume <name> in <dest>.
++
+If <dest> is not given, subvolume <name> will be created in the current
+directory.
++
+`Options`
++
+-i <qgroupid>::::
+Add the newly created subvolume to a qgroup. This option can be given multiple
+times.
+
+*delete* [options] <subvolume> [<subvolume>...]::
+Delete the subvolume(s) from the filesystem.
++
+If <subvolume> is not a subvolume, btrfs returns an error but continues if
+there are more arguments to process.
++
+The corresponding directory is removed instantly but the data blocks are
+removed later.  The deletion does not involve full commit by default due to
+performance reasons (as a consequence, the subvolume may appear again after a
+crash).  Use one of the '--commit' options to wait until the operation is safely
+stored on the media.
++
+`Options`
++
+-c|--commit-after::::
+wait for transaction commit at the end of the operation
++
+-C|--commit-each::::
+wait for transaction commit after deleting each subvolume
+
+*find-new* <subvolume> <last_gen>::
+List the recently modified files in a subvolume, after <last_gen> ID.
+
+*get-default* <path>::
+Get the default subvolume of the filesystem <path>.
++
+The output format is similar to *subvolume list* command.
+
+*list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>::
+List the subvolumes present in the filesystem <path>.
++
+For every subvolume the following information is shown by default. +
+ID <ID> top level <ID> path <path> +
+where path is the relative path of the subvolume to the top level subvolume.
+The subvolume's ID may be used by the subvolume set-default command,
+or at mount time via the subvolid= option.
+If `-p` is given, then parent <ID> is added to the output between ID
+and top level. The parent's ID may be used at mount time via the
+`subvolrootid=` option.
++
+`Options`
++
+-p::::
+print parent ID.
+-a::::
+print all the subvolumes in the filesystem and distinguish between
+absolute and relative path with respect to the given <path>.
+-c::::
+print the ogeneration of the subvolume, aliases: ogen or origin generation.
+-g::::
+print the generation of the subvolume.
+-o::::
+print only subvolumes below specified <path>.
+-u::::
+print the UUID of the subvolume.
+-q::::
+print the parent uuid of subvolumes (and snapshots).
+-R::::
+print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
+-t::::
+print the result as a table.
+-s::::
+only snapshot subvolumes in the filesystem will be listed.
+-r::::
+only readonly subvolumes in the filesystem will be listed.
+-G [+|-]<value>::::
+list subvolumes in the filesystem that its generation is
+>=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is
+neither \'+' nor \'-', it means = value.
+-C [+|-]<value>::::
+list subvolumes in the filesystem that its ogeneration is
+>=, \<= or = value. The usage is the same to '-g' option.
+--sort=rootid,gen,ogen,path::::
+list subvolumes in order by specified items.
+you can add \'\+' or \'-' in front of each items, \'+' means ascending,
+\'-' means descending. The default is ascending.
++
+for --sort you can combine some items together by \',', just like
+-sort=+ogen,-gen,path,rootid.
+
+*set-default* <id> <path>::
+Set the subvolume of the filesystem <path> which is mounted as
+default.
++
+The subvolume is identified by <id>, which is returned by the *subvolume list*
+command.
+
+*show* <path>::
+Show information of a given subvolume in the <path>.
+
+*snapshot* [-r] <source> <dest>|[<dest>/]<name>::
+Create a writable/readonly snapshot of the subvolume <source> with the
+name <name> in the <dest> directory.
++
+If only <dest> is given, the subvolume will be named the basename of <source>.
+If <source> is not a subvolume, btrfs returns an error.
+If '-r' is given, the snapshot will be readonly.
+
+*sync* <path> [subvolid...]::
+Wait until given subvolume(s) are completely removed from the filesystem
+after deletion. If no subvolume id is given, wait until all current  deletion
+requests are completed, but do not wait for subvolumes deleted meanwhile.
+The status of subvolume ids is checked periodically.
++
+`Options`
++
+-s <N>::::
+sleep N seconds between checks (default: 1)
+
+EXIT STATUS
+-----------
+*btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is
+returned in case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8),
+`btrfs-quota`(8),
+`btrfs-qgroup`(8),
diff --git a/Documentation/btrfs.asciidoc b/Documentation/btrfs.asciidoc
new file mode 100644
index 00000000..6a77a852
--- /dev/null
+++ b/Documentation/btrfs.asciidoc
@@ -0,0 +1,127 @@
+btrfs(8)
+========
+
+NAME
+----
+btrfs - control a btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs* <command> [<args>]
+
+DESCRIPTION
+-----------
+The *btrfs* utility is a toolbox for managing btrfs filesystems.  There are
+command groups to work with subvolumes, devices, for whole filesystem or other
+specific actions. See section *COMMANDS*.
+
+COMMAND SYNTAX
+--------------
+
+Any command name can be shortened as far as it stays unambiguous,
+however it is recommended to use full command names in scripts.
+All command groups have their manual page named *btrfs-<group>*.
+
+For example: it is possible to run *btrfs sub snaps* instead of
+*btrfs subvolume snapshot*.
+But *btrfs file s* is not allowed, because *file s* may be interpreted
+both as *filesystem show* and as *filesystem sync*.
+
+If the command name is ambiguous, the list of conflicting options is
+printed.
+
+For an overview of a given command use 'btrfs command --help'
+or 'btrfs [command...] --help --full' to print all available options.
+
+COMMANDS
+--------
+*balance*::
+	Balance btrfs filesystem chunks across single or several devices. +
+	See `btrfs-balance`(8) for details.
+
+*check*::
+	Do off-line check on a btrfs filesystem. +
+	See `btrfs-check`(8) for details.
+
+*device*::
+	Manage devices managed by btrfs, including add/delete/scan and so
+	on. +
+	See `btrfs-device`(8) for details.
+
+*filesystem*::
+	Manage a btrfs filesystem, including label setting/sync and so on. +
+	See `btrfs-filesystem`(8) for details.
+
+*inspect-internal*::
+	Debug tools for developers/hackers. +
+	See `btrfs-inspect-internal`(8) for details.
+
+*property*::
+	Get/set a property from/to a btrfs object. +
+	See `btrfs-property`(8) for details.
+
+*qgroup*::
+	Manage quota group(qgroup) for btrfs filesystem. +
+	See `btrfs-qgroup`(8) for details.
+
+*quota*::
+	Manage quota on btrfs filesystem like enabling/rescan and etc. +
+	See `btrfs-quota`(8) and `btrfs-qgroup`(8) for details.
+
+*receive*::
+	Receive subvolume data from stdin/file for restore and etc. +
+	See `btrfs-receive`(8) for details.
+
+*replace*::
+	Replace btrfs devices. +
+	See `btrfs-replace`(8) for details.
+
+*rescue*::
+	Try to rescue damaged btrfs filesystem. +
+	See `btrfs-rescue`(8) for details.
+
+*restore*::
+	Try to restore files from a damaged btrfs filesystem. +
+	See `btrfs-restore`(8) for details.
+
+*scrub*::
+	Scrub a btrfs filesystem. +
+	See `btrfs-scrub`(8) for details.
+
+*send*::
+	Send subvolume data to stdout/file for backup and etc. +
+	See `btrfs-send`(8) for details.
+
+*subvolume*::
+	Create/delete/list/manage btrfs subvolume. +
+	See `btrfs-subvolume`(8) for details.
+
+EXIT STATUS
+-----------
+*btrfs* returns a zero exit status if it succeeds. Non zero is returned in
+case of failure.
+
+AVAILABILITY
+------------
+*btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8), `ionice`(1),
+`btrfs-balance`(8),
+`btrfs-check`(8),
+`btrfs-device`(8),
+`btrfs-filesystem`(8),
+`btrfs-inspect-internal`(8),
+`btrfs-property`(8),
+`btrfs-qgroup`(8),
+`btrfs-quota`(8),
+`btrfs-receive`(8),
+`btrfs-replace`(8),
+`btrfs-rescue`(8),
+`btrfs-restore`(8),
+`btrfs-scrub`(8),
+`btrfs-send`(8),
+`btrfs-subvolume`(8),
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
new file mode 100644
index 00000000..68fec4c9
--- /dev/null
+++ b/Documentation/btrfstune.asciidoc
@@ -0,0 +1,75 @@
+btrfstune(8)
+============
+
+NAME
+----
+btrfstune - tune various filesystem parameters
+
+SYNOPSIS
+--------
+*btrfstune* [options] <dev> [<dev>...]
+
+DESCRIPTION
+-----------
+*btrfstune* can be used to enable, disable or set various filesystem
+parameters. The filesystem must be unmounted.
+
+The common usecase is to enable features that were not enabled at mkfs time.
+Please make sure that you have kernel support for the features.  You can find a
+complete list of features and kernel version of their introduction at
+https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature .
+
+OPTIONS
+-------
+-S <0|1>::
+Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. +
+A seeding filesystem is forced to be mounted read-only. A new device can be added
+to the filesystem and will capture all writes keeping the seeding device intact.
+-r::
+Enable extended inode refs (hardlink limit per file in a directory is 65536),
+enabled by mkfs feature 'extref'. Since kernel 3.7.
+-x::
+Enable skinny metadata extent refs (more efficient representation of extents),
+enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10.
+-n::
+Enable no-holes feature (more efficient representation of file holes), enabled
+by mkfs feature 'no-holes'. Since kernel 3.14.
+-f::
+Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
+that you are aware of the dangers.
+-u::
+Change fsid to a randomly generated UUID or continue previous fsid change
+operation in case it was interrupted.
+-U <UUID>::
+Change fsid to 'UUID'.
++
+The 'UUID' should be a 36 bytes string in `printf`(3) format
+'"%08x-%04x-%04x-%04x-%012x"'.
+If there is a previous unfinished fsid change, it will continue only if the
+'UUID' matches the unfinished one or if you use the option '-u'.
+
+WARNING: Cancelling or interrupting a UUID change operation will make the
+filesystem temporarily unmountable.  To fix it, rerun 'btrfstune -u' to restore
+the UUID and let it complete.
+
+WARNING: Clearing the seeding flag on a device may be dangerous.
+If a previously-seeding device is changed, all filesystems that used that
+device will become unmountable. Setting the seeding flag back will not fix
+that. +
+A valid usecase is 'seeding device as a base image'. Clear the seeding
+flag, update the filesystem and make it seeding again, provided that it's OK
+to throw away all filesystems built on top of the previous base.
+
+EXIT STATUS
+-----------
+*btrfstune* returns 0 if no error happened, 1 otherwise.
+
+COMPATIBILITY NOTE
+------------------
+This tool exists for historical reasons but is still in use today.  The
+functionality is about to be merged to the main tool someday and *btrfstune*
+will become deprecated and removed afterwards.
+
+SEE ALSO
+--------
+`mkfs.btrfs`(8)
diff --git a/Documentation/fsck.btrfs.asciidoc b/Documentation/fsck.btrfs.asciidoc
new file mode 100644
index 00000000..0bad075b
--- /dev/null
+++ b/Documentation/fsck.btrfs.asciidoc
@@ -0,0 +1,51 @@
+fsck.btrfs(8)
+=============
+
+NAME
+----
+fsck.btrfs - do nothing, successfully
+
+SYNOPSIS
+--------
+*fsck.btrfs* [-aApy] [<device>...]
+
+DESCRIPTION
+-----------
+*fsck.btrfs* is a type of utility that should exist for any filesystem and is
+called during system setup when the corresponding `/etc/fstab` entries
+contain non-zero value for `fs_passno` , see `fstab`(5) for more.
+
+Traditional filesystems need to run their respective fsck utility in case the
+filesystem was not unmounted cleanly and the log needs to be replayed before
+mount. This is not needed for BTRFS. You should set fs_passno to 0.
+
+If you wish to check the consistency of a BTRFS filesystem or repair a damaged
+filesystem, see `btrfs-check`(8). By default the filesystem
+consistency is checked, the repair mode is enabled via '--repair' option (use
+with care!).
+
+OPTIONS
+-------
+The options are all the same and detect if *fsck.btrfs* is executed in
+non-interactive mode and exits with success,
+otherwise prints a message about btrfs check.
+
+EXIT STATUS
+-----------
+There are two possible exit code returned:
+
+0::
+No error
+
+8::
+Operational error, eg. device does not exist
+
+FILES
+-----
+`/etc/fstab`
+
+SEE ALSO
+--------
+`btrfs`(8),
+`fsck`(8),
+`fstab`(5),
diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
new file mode 100644
index 00000000..a264fa61
--- /dev/null
+++ b/Documentation/manpage-base.xsl
@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format;
+     git.docbook.backslash and git.docbook.dot params
+     must be supplied by another XSL file or other means -->
+<xsl:template match="co">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB(',
+			      substring-after(@id,'-'),')',
+			      $git.docbook.backslash,'fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>sp&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB',
+			      substring-after(@arearefs,'-'),
+			      '. ',$git.docbook.backslash,'fR')"/>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>br&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 00000000..608eb5df
--- /dev/null
+++ b/Documentation/manpage-bold-literal.xsl
@@ -0,0 +1,17 @@
+<!-- manpage-bold-literal.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- render literal text as bold (instead of plain or monospace);
+     this makes literal text easier to distinguish in manpages
+     viewed on a tty -->
+<xsl:template match="literal">
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fB</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fR</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
new file mode 100644
index 00000000..a48f5b11
--- /dev/null
+++ b/Documentation/manpage-normal.xsl
@@ -0,0 +1,13 @@
+<!-- manpage-normal.xsl:
+     special settings for manpages rendered from asciidoc+docbook
+     handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot"	>.</xsl:param>
+
+</xsl:stylesheet>
diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
new file mode 100644
index 00000000..5d79e24f
--- /dev/null
+++ b/Documentation/mkfs.btrfs.asciidoc
@@ -0,0 +1,354 @@
+mkfs.btrfs(8)
+=============
+
+NAME
+----
+mkfs.btrfs - create a btrfs filesystem
+
+SYNOPSIS
+--------
+*mkfs.btrfs*
+$$[-A|--alloc-start <alloc-start>]$$
+$$[-b|--byte-count <byte-count>]$$
+$$[-d|--data <data-profile>]$$
+$$[-m|--metadata <metadata profile>]$$
+$$[-M|--mixed]$$
+$$[-l|--leafsize <leafsize>]$$
+$$[-n|--nodesize <nodesize>]$$
+$$[-s|--sectorsize <sectorsize>]$$
+$$[-L|--label <label>]$$
+$$[-K|--nodiscard]$$
+$$[-r|--rootdir <rootdir>]$$
+$$[-O|--features <feature1>[,<feature2>...]]$$
+$$[-U|--uuid <UUID>]$$
+$$[-f|--force]$$
+$$[-q|--quiet]$$
+$$[--help]$$
+$$[-V|--version]$$
+$$<device> [<device>...]$$
+
+DESCRIPTION
+-----------
+*mkfs.btrfs* is used to create the btrfs filesystem on a single or multiple
+devices.  <device> is typically a block device but can be a file-backed image
+as well. Multiple devices are grouped by UUID of the filesystem.
+
+Before mounting such filesystem, the kernel module must know all the devices
+either via preceding execution of *btrfs device scan* or using the *device*
+mount option. See section *MULTIPLE DEVICES* for more details.
+
+OPTIONS
+-------
+*-A|--alloc-start <offset>*::
+(An option to help debugging chunk allocator.)
+Specify the (physical) offset from the start of the device at which allocations
+start.  The default value is zero.
+
+*-b|--byte-count <size>*::
+Specify the size of the filesystem. If this option is not used,
+mkfs.btrfs uses the entire device space for the filesystem.
+
+*-d|--data <profile>*::
+Specify the profile for the data block groups.  Valid values are 'raid0',
+'raid1', 'raid5', 'raid6', 'raid10' or 'single' or dup (case does not matter).
++
+See 'DUP PROFILES ON A SINGLE DEVICE' for more.
+
+*-m|--metadata <profile>*::
+Specify the profile for the metadata block groups.
+Valid values are 'raid0', 'raid1', 'raid5', 'raid6', 'raid10', 'single' or
+'dup', (case does not matter).
++
+A single device filesystem will default to 'DUP', unless a SSD is detected. Then
+it will default to 'single'. The detection is based on the value of
+`/sys/block/DEV/queue/rotational`, where 'DEV' is the short name of the device.
++
+Note that the rotational status can be arbitrarily set by the underlying block
+device driver and may not reflect the true status (network block device, memory-backed
+SCSI devices etc). Use the options '--data/--metadata' to avoid confusion.
++
+See 'DUP PROFILES ON A SINGLE DEVICE' for more details.
+
+*-M|--mixed*::
+Normally the data and metadata block groups are isolated. The 'mixed' mode
+will remove the isolation and store both types in the same block group type.
+This helps to utilize the free space regardless of the purpose and is suitable
+for small devices. The separate allocation of block groups leads to a situation
+where the space is reserved for the other block group type, is not available for
+allocation and can lead to ENOSPC state.
++
+The recommended size for the mixed mode is for filesystems less than 1GiB. The
+soft recommendation is to use it for filesystems smaller than 5GiB. The mixed
+mode may lead to degraded performance on larger filesystems, but is otherwise
+usable, even on multiple devices.
++
+The 'nodesize' and 'sectorsize' must be equal, and the block group types must
+match.
++
+NOTE: versions up to 4.2.x forced the mixed mode for devices smaller than 1GiB.
+This has been removed in 4.3+ as it caused some usability issues.
+
+*-l|--leafsize <size>*::
+Alias for --nodesize. Deprecated.
+
+*-n|--nodesize <size>*::
+Specify the nodesize, the tree block size in which btrfs stores metadata. The
+default value is 16KiB (16384) or the page size, whichever is bigger. Must be a
+multiple of the sectorsize, but not larger than 64KiB (65536).  Leafsize always
+equals nodesize and the options are aliases.
++
+Smaller node size increases fragmentation but lead to higher b-trees which in
+turn leads to lower locking contention. Higher node sizes give better packing
+and less fragmentation at the cost of more expensive memory operations while
+updating the metadata blocks.
++
+NOTE: versions up to 3.11 set the nodesize to 4k.
+
+*-s|--sectorsize <size>*::
+Specify the sectorsize, the minimum data block allocation unit.
++
+The default value is the page size and is autodetected. If the sectorsize
+differs from the page size, the created filesystem may not be mountable by the
+kernel. Therefore it is not recommended to use this option unless you are going
+to mount it on a system with the appropriate page size.
+
+*-L|--label <string>*::
+Specify a label for the filesystem. The 'string' should be less than 256
+bytes and must not contain newline characters.
+
+*-K|--nodiscard*::
+Do not perform whole device TRIM operation on devices that are capable of that.
+
+*-r|--rootdir <rootdir>*::
+Populate the toplevel subvolume with files from 'rootdir'.  This does not
+require root permissions and does not mount the filesystem.
+
+*-O|--features <feature1>[,<feature2>...]*::
+A list of filesystem features turned on at mkfs time. Not all features are
+supported by old kernels. To disable a feature, prefix it with '^'.
++
+See section *FILESYSTEM FEATURES* for more details.  To see all available
+features that mkfs.btrfs supports run:
++
++mkfs.btrfs -O list-all+
+
+*-f|--force*::
+Forcibly overwrite the block devices when an existing filesystem is detected.
+By default, mkfs.btrfs will utilize 'libblkid' to check for any known
+filesystem on the devices. Alternatively you can use the `wipefs` utility
+to clear the devices.
+
+*-q|--quiet*::
+Print only error or warning messages. Options --features or --help are unaffected.
+
+*-U|--uuid <UUID>*::
+Create the filesystem with the given 'UUID'. The UUID must not exist on any
+filesystem currently present.
+
+*-V|--version*::
+Print the *mkfs.btrfs* version and exit.
+
+*--help*::
+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', 'p', 'e', both uppercase
+and lowercase.
+
+MULTIPLE DEVICES
+----------------
+
+Before mounting a multiple device filesystem, the kernel module must know the
+association of the block devices that are attached to the filesystem UUID.
+
+There is typically no action needed from the user.  On a system that utilizes a
+udev-like daemon, any new block device is automatically registered. The rules
+call *btrfs device scan*.
+
+The same command can be used to trigger the device scanning if the btrfs kernel
+module is reloaded (naturally all previous information about the device
+registration is lost).
+
+Another possibility is to use the mount options *device* to specify the list of
+devices to scan at the time of mount.
+
+ # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
+
+NOTE: that this means only scanning, if the devices do not exist in the system,
+mount will fail anyway. This can happen on systems without initramfs/initrd and
+root partition created with RAID1/10/5/6 profiles. The mount action can happen
+before all block devices are discovered. The waiting is usually done on the
+initramfs/initrd systems.
+
+FILESYSTEM FEATURES
+-------------------
+
+*mixed-bg*::
+mixed data and metadata block groups, also set by option '--mixed'
+
+*extref*::
+(default since btrfs-progs 3.12, kernel support since 3.7)
++
+increased hardlink limit per file in a directory to 65536, older kernels
+supported a varying number of hardlinks depending on the sum of all file name
+sizes that can be stored into one metadata block
+
+*raid56*::
+extended format for RAID5/6, also enabled if raid5 or raid6 block groups
+are selected
+
+*skinny-metadata*::
+(default since btrfs-progs 3.18, kernel support since 3.10)
++
+reduced-size metadata for extent references, saves a few percent of metadata
+
+*no-holes*::
+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
+
+BLOCK GROUPS, CHUNKS, RAID
+--------------------------
+
+The highlevel organizational units of a filesystem are block groups of three types:
+data, metadata and system.
+
+*DATA*::
+store data blocks and nothing else
+
+*METADATA*::
+store internal metadata in b-trees, can store file data if they fit into the
+inline limit
+
+*SYSTEM*::
+store structures that describe the mapping between the physical devices and the
+linear logical space representing the filesystem
+
+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 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
+size is a few megabytes.
+
+*RAID*::
+a block group profile type that utilizes RAID-like features on multiple
+devices: striping, mirroring, parity
+
+*profile*::
+when used in connection with block groups refers to the allocation strategy
+and constraints, see the section 'PROFILES' for more details
+
+PROFILES
+--------
+
+There are the following block group types available:
+
+[ cols="^,^,^,^,^",width="60%" ]
+|=============================================================
+.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/any ^(see note)^
+| 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
+|=============================================================
+
+'Note:' 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.
+
+DUP PROFILES ON A SINGLE DEVICE
+-------------------------------
+
+The mkfs utility will let the user create a filesystem with profiles that write
+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 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. 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.
+
+In any case, a device that starts to misbehave and repairs from the DUP copy
+should be replaced! *DUP is not backup*.
+
+KNOWN ISSUES
+------------
+
+**SMALL FILESYSTEMS AND LARGE NODESIZE**
+
+The combination of small filesystem size and large nodesize is not recommended
+in general and can lead to various ENOSPC-related issues during mount time or runtime.
+
+Since mixed block group creation is optional, we allow small
+filesystem instances with differing values for 'sectorsize' and 'nodesize'
+to be created and could end up in the following situation:
+
+  # mkfs.btrfs -f -n 65536 /dev/loop0
+  btrfs-progs v3.19-rc2-405-g976307c
+  See http://btrfs.wiki.kernel.org for more information.
+
+  Performing full device TRIM (512.00MiB) ...
+  Label:              (null)
+  UUID:               49fab72e-0c8b-466b-a3ca-d1bfe56475f0
+  Node size:          65536
+  Sector size:        4096
+  Filesystem size:    512.00MiB
+  Block group profiles:
+    Data:             single            8.00MiB
+    Metadata:         DUP              40.00MiB
+    System:           DUP              12.00MiB
+  SSD detected:       no
+  Incompat features:  extref, skinny-metadata
+  Number of devices:  1
+  Devices:
+    ID        SIZE  PATH
+     1   512.00MiB  /dev/loop0
+
+  # mount /dev/loop0 /mnt/
+  mount: mount /dev/loop0 on /mnt failed: No space left on device
+
+The ENOSPC occurs during the creation of the UUID tree. This is caused
+by large metadata blocks and space reservation strategy that allocates more
+than can fit into the filesystem.
+
+
+AVAILABILITY
+------------
+*mkfs.btrfs* is part of btrfs-progs.
+Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
+further details.
+
+SEE ALSO
+--------
+`btrfs`(8), `wipefs`(8)