Update the kvm-quickstart and kvm-xfstests documentation.

Signed-off-by: Theodore Ts'o <tytso@mit.edu>

2 files changed, 68 insertions, 59 deletions

diff --git a/Documentation/kvm-quickstart.md b/Documentation/kvm-quickstart.md
index 258c8a37..4e1122d6 100644
--- a/Documentation/kvm-quickstart.md
+++ b/Documentation/kvm-quickstart.md
@@ -1,48 +1,60 @@
 # Quick start instructions for kvm-xfstests
 
-1.  Make sure qemu with kvm support is installed on your system.
+1.  Make sure the necessary packages are installed.  For Debian/Ubuntu
+    systems:
 
-        apt-get install qemu-kvm
+        apt-get install qemu-kvm wget gcc git make
+
+    For Fedora systems:
+
+        dnf install qemu-kvm wget2 gcc git make
 
 2.  Run the following commands to install the xfstests-bld repository
-    and download a pre-compiled test appliance image.  We use the
-    32-bit test appliance here since it can support both 32-bit and
-    64-bit kernels.
+    and install the necessary scripts into the bin directory in your
+    home directory.  If ~/bin isn't in your PATH, edit your dotfiles
+    (e.g., your ~/.bashrc) so that it is.
 
-        git clone https://git.kernel.org/pub/scm/fs/ext2/xfstests-bld.git fstests
+        git clone https://github.com/tytso/xfstests-bld fstests
         cd fstests
-        wget -O test-appliance/root_fs.img https://www.kernel.org/pub/linux/kernel/people/tytso/kvm-xfstests/root_fs.img.i386
+        make ; make install
 
-3.  In the top-level directory of your checked out xfstests-bld
-    repository, run "make kvm-xfstests" and then copy this generated
-    file to a directory which is your shell's PATH.  This allows you
-    to run the kvm-xfstests binary without needing to set the
-    working directory to the kvm-xfstests directory.
+3.  Optionally, if you want to primarily developing a file system
+    other than ext4, you can specify the primary file system type in the
+    file ~/.config/kvm-xfstests:
 
-        make kvm-xfstests
-        cp kvm-xfstests ~/bin/kvm-xfstests
+        echo PRIMARY_FSTYPE=f2fs >> ~/.config/kvm-xfstests
 
-4.  In the fstests/run-fstests/ directory, take a look at the
-    "config.kvm" file and either edit that file in place, or (this is
-    preferred) put override values in ~/.config/kvm-xfstests.  The
-    most common values you will likely need to override are the
-    location of the compiled kernel and the preferred timezone if you
-    wish the log files to display times in your local timezone.
+    Again, optionally, if you want the log files to display times in
+    your local timezone, you can add a timezone to the
+    ~/.config/kvm-xfstests file.
 
-        TZ=America/New_York
-        KERNEL=/build/ext4/arch/x86/boot/bzImage
+        echo TZ=America/New_York >> ~/.config/kvm-xfstests
 
-5.  To build a kernel for use with kvm-xfstests, with the current
+4.  To build a kernel for use with kvm-xfstests, with the current
     directory in the kernel sources which you would like to use, run
     the commands:
 
-        kvm-xfstests install-kconfig
-        kvm-xfstests kbuild
+        install-kconfig
+        kbuild
+
+5.  In the top-level of the kernel sources where you have run "kbuild"
+    you can perform a smoke test:
+
+        kvm-xfstests smoke
+
+
+    Developers are *strongly* recommended to run a smoke test before
+    submitting a patch or patch series upstream for review.
+
+    Today, this is equivalent to "kvm-xfstests -c default -g quick".
+    However, this might change in the future to run a smaller set of
+    tests, as the quick group can take about an hour to run.
 
-6.  Run "kvm-xfstests smoke" to do a quick test.  Or "kvm-xfstests
-    -g auto" to do a full test.  You can also run specific tests on
-    specific configurations, i.e., "kvm-xfstests -c bigalloc_4k
-    generic/013 generic/127".   To run a shell, use "kvm-xfstests shell"
+    To do a full test, you can run "kvm-xfstests full".   Warning:
+    this will take a long time --- close to 24 hours if you are
+    testing ext4; you may be better off using
+    [gce-xfstests](gce-xfstests.md) if you are interested in doing the sort of
+    testing used by file system maintainers.
 
 For more information, please see the full [kvm-xfstests
 documentation](kvm-xfstests.md).
diff --git a/Documentation/kvm-xfstests.md b/Documentation/kvm-xfstests.md
index 0b397d6c..50f3e098 100644
--- a/Documentation/kvm-xfstests.md
+++ b/Documentation/kvm-xfstests.md
@@ -11,33 +11,26 @@ read this [introduction to xfstests](what-is-xfstests.md).
 The kvm-xfstests system consists of a series of shell scripts, and a
 test appliance virtual machine image.  You can build an image using
 the build infrastructure in the xfstests-bld git repository, but if
-you are just getting started, it will be much simpler if you download
-one of the pre-compiled VM images which can be found on
-[kernel.org](https://www.kernel.org/pub/linux/kernel/people/tytso/kvm-xfstests).
-
-You will find there a 32-bit test appliance named
-[root_fs.img.i386](https://www.kernel.org/pub/linux/kernel/people/tytso/kvm-xfstests/root_fs.img.i386)
-and a 64-bit test appliance named
-[root_fs.img.amd64](https://www.kernel.org/pub/linux/kernel/people/tytso/kvm-xfstests/root_fs.img.amd64).
-This file should be installed as root_fs.img in the test-appliance
-directory.
-
-A 64-bit x86 kernel can use both the 32-bit and 64-bit test appliance
-VM, since you can run 32-bit ELF binaries using a 64-bit kernel.
-However, the reverse is not true; a 32-bit x86 kernel can not run
-64-bit x86 binaries.  This makes the 64-bit test appliance more
-flexible.  In addition, if you use the 64-bit kernel with 32-bit
-interfaces, it tests the 32-bit compat ioctl code paths, which
-otherwise may not get sufficient testing.
-
-If you want to build your own test appliance VM, see
-[building-rootfs.md](building-rootfs.md).
+you are just getting started, it will be much simpler if you let
+kvm-xfstests automatically download a pre-compiled VM test appliance
+image from [kernel.org](https://www.kernel.org/pub/linux/kernel/people/tytso/kvm-xfstests).
+
+There are prebuilt test appliances for 32-bit and 64-bit x86 systems
+(root_fs.img.i386 and root_fs.img.amd64) as well as for the 64-bit ARM
+platform.  Thet test appliance images are installed in the
+test-appliance directory, but it's easist to just allow kvm-xfstests
+to download the image to the correct place, or to let the
+build-appliance write the newly created test appliance image where it
+should be located.  If you want to build your own test appliance VM,
+see [building-rootfs.md](building-rootfs.md).
 
 ## Setup and configuration
 
-The configuration file for kvm-xfstests is run-fstests/config.kvm.
-You can edit this file directly, but the better thing to do is to
-place override values in ~/.config/kvm-xfstests.
+The configuration file for kvm-xfstests is located
+~/.config/kvm-xfstests.  A sample of the parameters that can be set in
+the config file can be found in run-tests/config.kvm and
+run-tests/config.common, which show the default values if they are not
+overridden by settings in ~/.config/kvm-xfstests.
 
 Perhaps the most important configuration variable to set is KERNEL.
 This should point at the default location for the kernel that qemu
@@ -48,16 +41,20 @@ tree where there is a built kernel, kvm-xfstests will use it.
 Otherwise, it will use the kernel specified by the KERNEL variable.
 
 To build a correctly configured kernel for use with kvm-xfstests, run
-the command:
+the commands:
 
-        kvm-xfstests install-kconfig [--i386]
+        install-kconfig
+        kbuild
 
-(Add the --i386 option if you wish to build a 32-bit kernel.)
+If you wish to build kernels for the i386 or arm64 platforms, add
+"--arch i386" or "--arch amd64" to install-kconfig and kbuild
+commands.
 
 By default, the scratch disks used by test-appliance will be set up
 automatically, and are stored in the run-fstests directory with the
 names vdb, vdc, vdd, ... up to vdg.  However, it is slightly faster to
-use logical volumes.  To do this override the VDB..VDG variables:
+use logical volumes.  To do this override the VDB..VDG variables in
+the ~/.config/kvm-xfstests file.
 
         VG=closure
 
@@ -98,8 +95,8 @@ appliance is:
         kvm-xfstests [-c <cfg>] [-g <group>]|[<tests>] ...
 
 
-By default <cfg> defaults to all, which will run the following
-configurations: "4k", "1k", "ext3", "nojournal", "ext3conv",
+By default <cfg> defaults to all, which for ext4 will run the
+following configurations: "4k", "1k", "ext3", "nojournal", "ext3conv",
 "dioread_nolock, "data_journal", "inline", "bigalloc_4k", and
 "bigalloc_1k".  You may specify a single configuration or a comma
 separated list if you want to run a subset of all possible file system