btrfs-progs: Documentaion: rename to .asciidoc

A few minor benefits:

* editors set highliting according to the extensions
* web access to the git repository (github) renders the .asciidoc
  files:
  * we can link to them from the wiki
  * the files are editable via browser and such editations can be
    submitted for merge easily

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

1 files changed, 140 insertions, 0 deletions

diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
new file mode 100644
index 00000000..6d2fd0c3
--- /dev/null
+++ b/Documentation/btrfs-balance.asciidoc
@@ -0,0 +1,140 @@
+btrfs-balance(8)
+================
+
+NAME
+----
+btrfs-balance - balance btrfs filesystem
+
+SYNOPSIS
+--------
+*btrfs balance* <subcommand> <args>
+
+DESCRIPTION
+-----------
+*btrfs balance* is used to balance chunks in a btrfs filesystem across
+multiple or even single device.
+
+See `btrfs-device`(8) for more details about the effect on device management.
+
+NOTE: The balance subcommand also exists under the *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.
+
+*resume* <path>::
+Resume interrupted balance.
+
+*start* [options] <path>::
+Balance chunks across the devices *online*.
++
+Balance and/or convert (change allocation profile of) chunks that
+passed all filters in a comma-separated list of filters for a
+particular chunk type.
+If filter list is not given balance all chunks of that type.
+In case none of the -d, -m or -s options is
+given balance all chunks in a filesystem.
++
+`Options`
++
+-d[<filters>]::::
+act on data chunks. 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 (only under -f). See `FILTERS` section for details about <filters>.
+-v::::
+be verbose
+-f::::
+force reducing of metadata integrity
+
+*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 RAID-1). 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 stucture: ::
+'type'[='params'][,'type'=...]
+
+The available types are:
+
+*profiles*::
+Balances only block groups with the given replication profiles. Parameters
+are a list of profile names separated by |.
+
+*usage*::
+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 space allocated. You may want to use usage=0 in
+case balance is returnin ENOSPC and your filesystem is not too full.
+
+*devid*::
+Balances only block groups which have at least one chunk on the given
+device (by btrfs device ID -- use btrfs fi show to list device IDs)
+
+*drange*::
+Balances 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*::
+Balances 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*::
+Convert each selected block group to the given profile name identified by
+parameters.
+
+*limit*::
+Process only given number of chunks, after all filters apply. 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.
+
+*soft*::
+Takes no parameters. Only has meaning when converting between profiles.
+When doing convert from one profile to another and soft mode is on,
+restriper won't touch chunks that already have the target profile. This is
+useful if e.g. half of the FS was converted earlier.
++
+The soft mode switch is (like every other filter) per-type. This means
+that we can convert for example meta 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'.
+
+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)