New upstream release.

21 files changed, 235 insertions, 136 deletions

diff --git a/Documentation/CodingConventions b/Documentation/CodingConventions
new file mode 100644
index 00000000..cee90b30
--- /dev/null
+++ b/Documentation/CodingConventions
@@ -0,0 +1,19 @@
+C style
+-------
+
+The kernel CodingStyle where applicable
+
+https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+Error messages
+--------------
+
+* formatting:
+  * use `error("string ...")`
+  * no trailing newline
+  * small letter starts the first word
+  * no string splitting
+  * move string to new line if it's too long, un-indent to the left if it
+    exceeds 80 chars
+* contents:
+  * be descriptive
diff --git a/Documentation/DocConventions b/Documentation/DocConventions
new file mode 100644
index 00000000..e84ed7a7
--- /dev/null
+++ b/Documentation/DocConventions
@@ -0,0 +1,39 @@
+Manual pages structure:
+
+- add references to all external commands mentioned anywhere in the text to the
+  'SEE ALSO' section
+  - also add related, not explicitly mentioned
+- the heading levels are validated
+  - mandatory, manual page ===
+  - mandatory, sections ---
+  - optional, sub-sections ~~~
+- command-specific examples are mostly free of restrictions but should be
+  readable in all output formats (manual page, html)
+
+- subcommands are in alphabetical order
+
+- long command output or shell examples: verbatim output
+  - a new paragraph, 2 spaces at the beginning of the line
+
+
+Quotation in subcommands:
+
+- exact syntax: monotype `usage=0`
+- reference to arguments etc: 'italics'
+- command reference: bold *btrfs fi show*
+- section references: italics 'EXAMPLES'
+
+- argument name in option desciption: caps in angle brackets <NAME>
+  - reference in help text: caps NAME
+    also possible: caps italics 'NAME'
+
+- command short description:
+  - command name: bold *command*
+  - optional unspecified: brackets [options]
+  - mandatory argument: angle brackets <path>
+  - optional parameter with argument: [-p <path>]
+
+
+Refrences:
+- full asciidoc syntax: http://asciidoc.org/userguide.html
+- cheatsheet: http://powerman.name/doc/asciidoc
diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in
index aea2cb47..539c6b55 100644
--- a/Documentation/Makefile.in
+++ b/Documentation/Makefile.in
@@ -68,11 +68,6 @@ ifndef V
 	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
 
diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
index c456898e..fba55140 100644
--- a/Documentation/btrfs-balance.asciidoc
+++ b/Documentation/btrfs-balance.asciidoc
@@ -89,7 +89,7 @@ warned and has a few seconds to cancel the operation before it starts. The
 warning and delay can be skipped with '--full-balance' option.
 +
 Please note that the filters must be written together with the '-d', '-m' and
-'-s' options, because they're optional and bare '-d' etc alwo work and mean no
+'-s' options, because they're optional and bare '-d' etc also work and mean no
 filters.
 +
 `Options`
@@ -143,7 +143,7 @@ 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*.
+device. To list devices with ids use *btrfs filesystem show*.
 
 *drange=<range>*::
 Balance only block groups which overlap with the given byte range on any
@@ -247,7 +247,7 @@ provided.
 Let's use the following real life example and start with the output:
 
 --------------------
-$ btrfs fi df /path
+$ btrfs filesystem df /path
 Data, single: total=75.81GiB, used=64.44GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB
@@ -273,7 +273,7 @@ data and thus will be faster. A typical filter command would look like:
 # btrfs balance start -dusage=50 /path
 Done, had to relocate 2 out of 97 chunks
 
-$ btrfs fi df /path
+$ btrfs filesystem df /path
 Data, single: total=74.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.84GiB
@@ -288,7 +288,7 @@ usage filter.
 # btrfs balance start -dusage=85 /path
 Done, had to relocate 13 out of 95 chunks
 
-$ btrfs fi df /path
+$ btrfs filesystem df /path
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=15.87GiB, used=8.85GiB
@@ -309,7 +309,7 @@ reflinks updated frequently.
 # btrfs balance start -musage=50 /path
 Done, had to relocate 4 out of 89 chunks
 
-$ btrfs fi df /path
+$ btrfs filesystem df /path
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=14.87GiB, used=8.85GiB
@@ -327,7 +327,7 @@ further compaction:
 # btrfs balance start -musage=70 /path
 Done, had to relocate 13 out of 88 chunks
 
-$ btrfs fi df .
+$ btrfs filesystem df .
 Data, single: total=68.03GiB, used=64.43GiB
 System, RAID1: total=32.00MiB, used=20.00KiB
 Metadata, RAID1: total=11.97GiB, used=8.83GiB
@@ -351,7 +351,7 @@ can be used to reclaim unused block groups to make it available.
 # btrfs balance start -dusage=0 /path
 --------------------
 
-This should lead to decrease in the 'total' numbers in the *btrfs fi df* output.
+This should lead to decrease in the 'total' numbers in the *btrfs filesystem df* output.
 
 EXIT STATUS
 -----------
diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc
index 633cbbf6..28ed9dd7 100644
--- a/Documentation/btrfs-check.asciidoc
+++ b/Documentation/btrfs-check.asciidoc
@@ -30,11 +30,11 @@ 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
+extents, backreferences, 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.
+filesystem, similarly the run time.
 
 SAFE OR ADVISORY OPTIONS
 ------------------------
@@ -49,7 +49,7 @@ 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.
+spare copies.
 
 --chunk-root <bytenr>::
 use the given offset 'bytenr' for the chunk tree root
@@ -111,7 +111,7 @@ NOTE: Do not use unless you know what you're doing.
 select mode of operation regarding memory and IO
 +
 The 'MODE' can be one of 'original' and 'lowmem'. The original mode is mostly
-unoptimized regarding memory consumpption and can lead to out-of-memory
+unoptimized regarding memory consumption and can lead to out-of-memory
 conditions on large filesystems. The possible workaround is to export the block
 device over network to a machine with enough memory. The low memory mode is
 supposed to address the memory consumption, at the cost of increased IO when it
diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
index eedcac85..88822ece 100644
--- a/Documentation/btrfs-device.asciidoc
+++ b/Documentation/btrfs-device.asciidoc
@@ -20,18 +20,18 @@ 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
+`mkfs.btrfs`(8) 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*.
+removed or replaced, by commands provided 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* command 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
+constraints in connection with the number of devices. The profile applies to
 data and metadata block groups separately.
 
 RAID level::
@@ -43,7 +43,7 @@ See the section *TYPICAL USECASES* for some examples.
 
 SUBCOMMAND
 ----------
-*add* [-Kf] <dev> [<dev>...] <path>::
+*add* [-Kf] <device> [<device>...] <path>::
 Add device(s) to the filesystem identified by <path>.
 +
 If applicable, a whole device discard (TRIM) operation is performed prior to
@@ -62,7 +62,7 @@ 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>|<devid> [<device>|<devid>...] <path>::
 Remove device(s) from a filesystem identified by <path>
 +
 Device removal must satisfy the profile constraints, otherwise the command
@@ -72,15 +72,19 @@ 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.
+It is possible to delete the device that was used to mount the filesystem. The
+device entry in mount table will be replaced by another device name with the
+lowest device id.
 
-*delete* <dev>|<devid> [<dev>|<devid>...] <path>::
+*delete* <device>|<devid> [<device>|<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.
+Wait until all devices of a multiple-device filesystem are scanned and
+registered within the kernel module. This is to provide a way for automatic
+filesystem mounting tools to wait before the mount can start. The device scan
+is only one of the preconditions and the mount can fail for other reasons.
+Normal users usually do not need this command and may safely ignore it.
 
 *scan* [(--all-devices|-d)|<device> [<device>...]]::
 Scan devices for a btrfs filesystem and register them with the kernel module.
@@ -182,7 +186,7 @@ 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).
+logical mappings).
 
 What changed:
 
diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc
index 0f7ea495..b60ef74b 100644
--- a/Documentation/btrfs-filesystem.asciidoc
+++ b/Documentation/btrfs-filesystem.asciidoc
@@ -14,7 +14,7 @@ DESCRIPTION
 *btrfs filesystem* is used to perform several whole filesystem level tasks,
 including all the regular filesystem operations like resizing, space stats,
 label setting/getting, and defragmentation. There are other whole filesystem
-taks like scrub or balance that are grouped in separate commands.
+tasks like scrub or balance that are grouped in separate commands.
 
 SUBCOMMAND
 ----------
@@ -120,7 +120,7 @@ defragment files recursively in given directories
 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 will increase system load. This can also lead
+accumulates from several files and will increase system load. This can also lead
 to ENOSPC if there's too much dirty data to write and it's not possible to make
 the reservations for the new data (ie. how the COW design works).
 +
@@ -141,7 +141,7 @@ 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
+Each argument to 'btrfs filesystem 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.
@@ -170,7 +170,7 @@ show sizes in GiB, or GB with --si.
 --tbytes::::
 show sizes in TiB, or TB with --si.
 
-*label* [<dev>|<mountpoint>] [<newlabel>]::
+*label* [<device>|<mountpoint>] [<newlabel>]::
 Show or update the label of a filesystem. This works on a mounted filesystem or
 a filesystem image.
 +
@@ -196,7 +196,7 @@ 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
+unit 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
@@ -262,7 +262,7 @@ root user (due to use of restricted ioctl). For both there's a summary section
 with information about space usage:
 +
 -------------------------
-$ btrfs fi usage /path
+$ btrfs filesystem usage /path
 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
 Overall:
     Device size:                   1.82TiB
diff --git a/Documentation/btrfs-find-root.asciidoc b/Documentation/btrfs-find-root.asciidoc
index e04cd3e8..3d6af2df 100644
--- a/Documentation/btrfs-find-root.asciidoc
+++ b/Documentation/btrfs-find-root.asciidoc
@@ -7,7 +7,7 @@ btrfs-find-root - filter to find btrfs root
 
 SYNOPSIS
 --------
-*btrfs-find-root* [options] <dev>
+*btrfs-find-root* [options] <device>
 
 DESCRIPTION
 -----------
diff --git a/Documentation/btrfs-inspect-internal.asciidoc b/Documentation/btrfs-inspect-internal.asciidoc
index 44615e76..62b10294 100644
--- a/Documentation/btrfs-inspect-internal.asciidoc
+++ b/Documentation/btrfs-inspect-internal.asciidoc
@@ -26,7 +26,7 @@ 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
+Besides verification 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.
 +
@@ -51,8 +51,8 @@ for debugging (disables the '-f' option)
 If there are multiple options specified, only the last one 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
+attempt to print the superblock even if a valid BTRFS signature is not found;
+the result may be completely wrong if the data does not resemble a superblock
 +
 -s|--super <bytenr>::::
 (see compatibility note above)
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index acc4e429..8d9031f5 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -36,16 +36,6 @@ Enable/disable support for Posix Access Control Lists (ACLs).  See the
 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)
@@ -130,10 +120,15 @@ but a warning is printed if it's more than 300 seconds (5 minutes).
 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.
+the compression will allways be attempted, but the data may end up uncompressed
+if the compression would make them larger.
++
+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. As this is too simple, the
+'compress-force' is a workaround that will compress most of the files at the
+cost of some wasted CPU cycles on failed attempts. The heuristics of 'compress'
+will improve in the future so this will not be necessary.
 +
 NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
 
@@ -288,12 +283,6 @@ 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)
 +
@@ -314,9 +303,10 @@ 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.
+Skip automatic resume of an interrupted balance operation. The operation can
+later be resumed with *btrfs balance resume*, or the paused state can be
+removed with *btrfs balance cancel*. The default behaviour is to resume an
+interrupted balance immediately after a volume is mounted.
 
 *space_cache*::
 *space_cache='version'*::
@@ -347,19 +337,20 @@ If a version is not explicitly specified, the default implementation will be
 chosen, which is 'v1' as of 4.9.
 
 *ssd*::
-*nossd*::
 *ssd_spread*::
+*nossd*::
 (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.
+rotational or non-rotational device is in use (contents of
+'/sys/block/DEV/queue/rotational'). If it is, the 'ssd' option is turned on.
+The option 'nossd' will disable the 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.
+implies 'ssd', enabling all other SSD heuristics as well. The option 'nossd'
+will disable all SSD options.
 
 *subvol='path'*::
 Mount subvolume from 'path' rather than the toplevel subvolume. The
@@ -374,12 +365,6 @@ 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) )
 +
@@ -419,6 +404,31 @@ NOTE: This option has replaced 'recovery'.
 Allow subvolumes to be deleted by their respective owner. Otherwise, only the
 root user can do that.
 
+DEPRECATED MOUNT OPTIONS
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+List of mount options that have been removed, kept for backward compatibility.
+
+*alloc_start='bytes'*::
+(default: 1M, minimum: 1M, deprecated since: 4.13)
++
+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).
+
+*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.
+
+*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.
+
+
 FILESYSTEM FEATURES
 -------------------
 
@@ -440,9 +450,9 @@ dump-super device* will dump a superblock, you can map the value of
 
 after mkfs, on a mounted filesystem::
 The features of a filesystem (with a given UUID) are listed in
-`/sys/fs/btrfs/UUID/features/`, one file per feature. The status of is stored
-insid the file. The value '1' is for enabled, '0' means the feature had
-been enabled at the mount time and turned off afterwards.
+`/sys/fs/btrfs/UUID/features/`, one file per feature. The status is stored
+inside the file. The value '1' is for enabled and active, while '0' means the
+feature was enabled at mount time but turned off afterwards.
 +
 Whether a particular feature can be turned on a mounted filesystem can be found
 in the directory `/sys/fs/btrfs/features/`, one file per feature. The value '1'
@@ -450,34 +460,36 @@ means the feature can be enabled.
 
 List of features (see also `mkfs.btrfs`(8) section 'FILESYSTEM FEATURES'):
 
-big_metadata::
+*big_metadata*::
 (since: 3.4)
 +
-the filesystem uses 'nodesize' bigger than the page size
-compress_lzo::
+the filesystem uses 'nodesize' for metadata blocks, this can be bigger than the
+page size
+
+*compress_lzo*::
 (since: 2.6.38)
 +
 the 'lzo' compression has been used on the filesystem, either as a mount option
 or via *btrfs filesystem defrag*.
 
-default_subvol::
+*default_subvol*::
 (since: 2.6.34)
 +
 the default subvolume has been set on the filesystem
 
-extended_iref::
+*extended_iref*::
 (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
 
-mixed_backref::
+*mixed_backref*::
 (since: 2.6.31)
 +
-the last major disk format change, improved backreferences
+the last major disk format change, improved backreferences, now default
 
-mixed_groups::
+*mixed_groups*::
 (since: 2.6.37)
 +
 mixed data and metadata block groups, ie. the data and metadata are not
@@ -489,17 +501,18 @@ and vice versa)
 on the other hand, the final layout is quite unpredictable and possibly highly
 fragmented, which means worse performance
 
-no_holes::
+*no_holes*::
 (since: 3.14)
++
 improved representation of file extents where holes are not explicitly
 stored as an extent, saves a few percent of metadata if sparse files are used
 
-raid56::
+*raid56*::
 (since: 3.9)
 +
 the filesystem contains or contained a raid56 profile of block groups
-+
-skinny_metadata::
+
+*skinny_metadata*::
 (since: 3.10)
 +
 reduced-size metadata for extent references, saves a few percent of metadata
@@ -532,7 +545,7 @@ 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
+attribute can be set/unset but no other special handling is done
 
 *D*::
 'synchronous directory updates', for more details search `open`(2) for 'O_SYNC'
@@ -567,7 +580,7 @@ crw------- 1 root root 10, 234 Jan  1 12:00 /dev/btrfs-control
 --------------------
 
 The device accepts some ioctl calls that can perform following actions on the
-filesyste module:
+filesystem module:
 
 * scan devices for btrfs filesystem (ie. to let multi-device filesystems mount
   automatically) and register them with the kernel module
@@ -575,16 +588,16 @@ filesyste module:
   for a given filesystem
 * get the supported features (can be also found under '/sys/fs/btrfs/features')
 
-
-The device is usually created by ..., but can be created manually:
+The device is usually created by a system device node manager (eg. udev), but
+can be created manually:
 
 --------------------
 # mknod --mode=600 c 10 234 /dev/btrfs-control
 --------------------
 
-The device is not strictly required but the device scanning will not work and a
-workaround would need to be used to mount a multi-device filesystem. The mount
-option 'device' can trigger the device scanning during mount.
+The control device is not strictly required but the device scanning will not
+work and a workaround would need to be used to mount a multi-device filesystem.
+The mount option 'device' can trigger the device scanning during mount.
 
 SEE ALSO
 --------
diff --git a/Documentation/btrfs-property.asciidoc b/Documentation/btrfs-property.asciidoc
index 8b9b7f03..05ab0bc7 100644
--- a/Documentation/btrfs-property.asciidoc
+++ b/Documentation/btrfs-property.asciidoc
@@ -28,14 +28,14 @@ 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
+The option '-t' 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
+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::::
diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc
index 77d4c685..ef2e5d33 100644
--- a/Documentation/btrfs-quota.asciidoc
+++ b/Documentation/btrfs-quota.asciidoc
@@ -52,7 +52,7 @@ On the other hand, the traditional approach has only a poor solution to
 restrict directories.
 At installation time, the harddisk can be partitioned so that every directory
 (eg. /usr, /var/, ...) that needs a limit gets its own partition.  The obvious
-problem is, that those limits cannot be changed without a reinstall ation.  The
+problem is, that those limits cannot be changed without a reinstallation.  The
 btrfs subvolume feature builds a bridge.  Subvolumes correspond in many ways to
 partitions, as every subvolume looks like its own filesystem.  With subvolume
 quota, it is now possible to restrict each subvolume like a partition, but keep
@@ -69,7 +69,7 @@ both! But somebody else might not want to charge the snapshots to the users.
 
 Btrfs subvolume quota solves these problems by introducing groups of subvolumes
 and let the user put limits on them.  It is even possible to have groups of
-groups.  In the following, we refer to them as 'qgruops'.
+groups.  In the following, we refer to them as 'qgroups'.
 
 Each qgroup primarily tracks two numbers, the amount of total referenced
 space and the amount of exclusively referenced space.
@@ -84,7 +84,7 @@ from within this qgroup.
 SUBVOLUME QUOTA GROUPS
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The basic notion of the Subvolume Quota feature is the qouta group, short
+The basic notion of the Subvolume Quota feature is the quota group, short
 qgroup.  Qgroups are notated as 'level/id', eg.  the qgroup 3/2 is a qgroup of
 level 3. For level 0, the leading '0/' can be omitted.
 Qgroups of level 0 get created automatically when a subvolume/snapshot gets
@@ -182,7 +182,7 @@ when the subvolume is deleted.
 
 When you have several users on a machine, with home directories probably under
 /home, you might want to restrict /home as a whole, while restricting every
-user to an indiviual limit as well.  This is easily accomplished by creating a
+user to an individual limit as well.  This is easily accomplished by creating a
 qgroup for /home , eg. 1/1, and assigning all user subvolumes to it.
 Restricting this qgroup will limit /home, while every user subvolume can get
 its own (lower) limit.
diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc
index a6838e5e..1f6847a9 100644
--- a/Documentation/btrfs-receive.asciidoc
+++ b/Documentation/btrfs-receive.asciidoc
@@ -23,7 +23,7 @@ previously generated by *btrfs send*. The received subvolumes are stored to
 If '--dump' option is specified, *btrfs receive* will only do the validation of
 the stream, and print the stream metadata, one operation per line.
 
-*btrfs receive* will fail int the following cases:
+*btrfs receive* will fail in the following cases:
 
 1. receiving subvolume already exists
 
@@ -31,7 +31,7 @@ the stream, and print the stream metadata, one operation per line.
 
 3. default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume
 
-A subvolume is made read-only after the receiving process finishes succesfully.
+A subvolume is made read-only after the receiving process finishes successfully (see BUGS below).
 
 `Options`
 
@@ -66,7 +66,27 @@ tell us where this filesystem is mounted.
 --dump::
 dump the stream metadata, one line per operation
 +
-Does not require the 'path' parameter. The filesystem chanded.
+Does not require the 'path' parameter. The filesystem remains unchanged.
+
+BUGS
+----
+*btrfs receive* sets the subvolume read-only after it completes
+successfully.  However, while the receive is in progress, users who have
+write access to files or directories in the receiving 'path' can add,
+remove, or modify files, in which case the resulting read-only subvolume
+will not be an exact copy of the sent subvolume.
+
+If the intention is to create an exact copy, the receiving 'path'
+should be protected from access by users until the receive operation
+has completed and the subvolume is set to read-only.
+
+Additionally, receive does not currently do a very good job of validating
+that an incremental send streams actually makes sense, and it is thus
+possible for a specially crafted send stream to create a subvolume with
+reflinks to arbitrary files in the same filesystem.  Because of this,
+users are advised to not use *btrfs receive* on send streams from
+untrusted sources, and to protect trusted streams when sending them
+across untrusted networks.
 
 EXIT STATUS
 -----------
diff --git a/Documentation/btrfs-replace.asciidoc b/Documentation/btrfs-replace.asciidoc
index a259f96d..9a8a9ea1 100644
--- a/Documentation/btrfs-replace.asciidoc
+++ b/Documentation/btrfs-replace.asciidoc
@@ -28,7 +28,7 @@ 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
+of the filesystem which is mounted at <path>, otherwise it 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>.
diff --git a/Documentation/btrfs-rescue.asciidoc b/Documentation/btrfs-rescue.asciidoc
index 42aca645..a9b471fe 100644
--- a/Documentation/btrfs-rescue.asciidoc
+++ b/Documentation/btrfs-rescue.asciidoc
@@ -42,19 +42,19 @@ 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:
 ----
@@ -66,7 +66,7 @@ backtrace:
 ? 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
diff --git a/Documentation/btrfs-restore.asciidoc b/Documentation/btrfs-restore.asciidoc
index 41e90e2f..090dcc55 100644
--- a/Documentation/btrfs-restore.asciidoc
+++ b/Documentation/btrfs-restore.asciidoc
@@ -36,7 +36,7 @@ https://btrfs.wiki.kernel.org/index.php/Restore
 OPTIONS
 -------
 -s|--snapshots::
-get also snapshots that are skippped by default
+get also snapshots that are skipped by default
 
 -x|--xattr::
 get extended attributes
diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc
index f579c39e..eb90a1c4 100644
--- a/Documentation/btrfs-scrub.asciidoc
+++ b/Documentation/btrfs-scrub.asciidoc
@@ -25,11 +25,10 @@ default 'idle' so background scrub should not interfere with normal filesystem
 operation significantly.
 
 The scrubbing status is recorded in '/var/lib/btrfs/' in textual files named
-'scrub.status.UUID' for a filesystem identified by the given UUID. (An
-itermediate progress is communicated through a named pipe in file
-'scrub.progress.UUID' in the same directory.) The status file is updated
-periodically every 5 seconds. An resumed scrub will continue from the last
-saved position.
+'scrub.status.UUID' for a filesystem identified by the given UUID. (Progress
+state is communicated through a named pipe in file 'scrub.progress.UUID' in the
+same directory.) The status file is updated every 5 seconds. A resumed scrub
+will continue from the last saved position.
 
 SUBCOMMAND
 ----------
diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc
index 96659eed..ef345f68 100644
--- a/Documentation/btrfs-send.asciidoc
+++ b/Documentation/btrfs-send.asciidoc
@@ -3,7 +3,7 @@ btrfs-send(8)
 
 NAME
 ----
-btrfs-send - generate a stream of changes between two subvolumes
+btrfs-send - generate a stream of changes between two subvolume snapshots
 
 SYNOPSIS
 --------
@@ -13,20 +13,21 @@ 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.
+between two subvolume snapshots. The stream can be consumed by the *btrfs
+receive* command to replicate the sent snapshot 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).
+All snapshots involved in one send command must be read-only, and this status
+cannot be changed as long as there's a running send operation that uses the
+snapshot.
 
-In the full mode, the entire subvolume data and metadata will end up in the
+In the full mode, the entire snapshot 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.
+In the incremental mode (options '-p' and '-c'), previously sent snapshots that
+are available on both the sending and receiving side can be used to reduce the
+amount of information that has to be sent to reconstruct the sent snapshot on a
+different filesystem.
 
 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
@@ -45,8 +46,8 @@ 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
+output is normally written to standard output so it can be, for example, piped
+to btrfs receive. Use this option to write it to a file instead.
 --no-data::
 send in 'NO_FILE_DATA' mode
 +
@@ -58,7 +59,7 @@ useful to show the differences in metadata.
 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
+suppress all messages except errors
 
 EXIT STATUS
 -----------
diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
index 3419b138..5cfe8856 100644
--- a/Documentation/btrfs-subvolume.asciidoc
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -66,10 +66,13 @@ 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.
+removed later in the background. The command returns immediatelly. See `btrfs
+subvolume sync` how to wait until the subvolume gets completely removed.
++
+The deletion does not involve full transaction 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 device.
 +
 `Options`
 +
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 04295ee3..cd7bb532 100644
--- a/Documentation/btrfstune.asciidoc
+++ b/Documentation/btrfstune.asciidoc
@@ -7,7 +7,7 @@ btrfstune - tune various filesystem parameters
 
 SYNOPSIS
 --------
-*btrfstune* [options] <dev> [<dev>...]
+*btrfstune* [options] <device> [<device>...]
 
 DESCRIPTION
 -----------
@@ -29,11 +29,13 @@ OPTIONS
 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::
 (since kernel: 3.7)
 +
 Enable extended inode refs (hardlink limit per file in a directory is 65536),
 enabled by mkfs feature 'extref'.
+
 -x::
 (since kernel: 3.10)
 +
@@ -43,17 +45,21 @@ enabled by mkfs feature 'skinny-metadata'.
 All newly created extents will use the new representation. To completely switch
 the entire filesystem, run a full balance of the metadata. Please refer to
 `btrfs-balance`(8).
+
 -n::
 (since kernel: 3.14)
 +
 Enable no-holes feature (more efficient representation of file holes), enabled
 by mkfs feature 'no-holes'.
+
 -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'.
 +
diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
index 46a4d2d5..d53d9e26 100644
--- a/Documentation/mkfs.btrfs.asciidoc
+++ b/Documentation/mkfs.btrfs.asciidoc
@@ -76,8 +76,8 @@ 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.
+multiple of the sectorsize and a power of 2, 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