Merging pull request 1926

Signed-off-by: Lukáš Doktor <[email protected]>

* https://github.com/avocado-framework/avocado-vt:
  docs: Add note to RunningEmulationTCG about JeOS-RHEL
  docs: Add documentation on how to use TCG with Avocado-vt

docs/source/Experimental.rst

@@ -4,6 +4,7 @@
 Experimental features
 =====================
 
+.. _riscv64_setup:
 
 riscv64
 =======

docs/source/RunningInEmulationTCG.rst

@@ -0,0 +1,109 @@
+.. _emulation:
+
+===============================
+Running in emulation mode (TCG)
+===============================
+
+Sometimes it's useful to run Avocado-vt in emulation mode (eg. when
+checking PR about different architecture, or to debug certain feature
+while executing the test). As this is not default, extra arguments are
+usually required.
+
+Shared for all architectures is that you need the image. We supply
+JeOS for most of the architectures, so you should be able to get
+it via::
+
+    $ avocado vt-bootstrap --vt-guest-os JeOS.$VERSION.$ARCH
+
+where:
+
+* ``VERSION`` is JeOS version (when writing this document it was ``27``)
+* ``ARCH`` is the desired architecture (eg. aarch64)
+
+Or you can run any of the ``unattended_install`` tests with
+``--vt-guest-os`` of your choice (very slow).
+
+When running the tests, on top of the usual arguments, you usually
+need to specify:
+
+* ``--vt-qemu-bin`` - path to binary that supports expected architecture
+  (eg. ``/usr/local/bin/qemu-system-aarch64``)
+* ``--vt-qemu-dst-bin`` - for migration tests you need also to specify
+  the destination qemu binary (otherwise default one is used)
+* ``enable_kvm=no`` - to disable KVM (if necessary)
+
+.. note::
+
+   Some test require additional dependencies and are marked as ``no JeOS``
+   (another group is marked as ``only RHEL``) but it might be useful for
+   debugging purposes to use them with JeOS. You can do that by symlinking
+   the ``$avocado-vt-data/images/jeos-$version-$arch.qcow2`` to
+   ``$avocado-vt-data/images/rhel${version}devel-$arch.qcow2`` and using
+   the boot test with ``--vt-guest-os RHEL.$version``. To add extra
+   packages use ``ctrl+Z`` when it's about to ssh in. Then you can
+   ssh to that guest from your machine, run ``dnf install ...``
+   to install the extra packages (``gcc`` suffices for most test), shut
+   the machine down, backup it to ``$name.backup`` and resume the ``boot``
+   test by ``ctrl+Z``. Obviously the test will fail, refreshes the image
+   from ``$name.backup`` but since then you have slightly fattier JeOS
+   symlinked to RHEL capable of running some extended tests without
+   the need to run full installation in TCG mode. Beware, vt-bootstrap
+   might overwrite the `.backup` from archive.
+
+aarch64
+=======
+
+ARM always requires `cpu_model` as well as `machine_type`. To
+get list of available models you can run ``qemu-system-aarch64
+-cpu help -M virt`` (note: not all listed cpus are bootable).
+By default Avocado-vt uses ``-machine $machine_type,gic-version=host``
+to use host's GIC version, but this is not possible to evaluate
+in TCG (especially without GIC on x86) so one needs to either
+pick a fixed version or simply use qemu default by cleaning
+the ``machine_type_extra_params``. Complete example would be::
+
+   $ avocado vt-bootstrap --vt-guest-os JeOS.27.aarch64
+   $ avocado --show all run --vt-extra-params enable_kvm=no cpu_model=cortex-a57 \
+       machine_type_extra_params='' --vt-machine-type aarch64 --vt-arch arm64-pci \
+       --vt-qemu-bin /usr/local/bin/qemu-system-aarch64 -- boot
+
+
+ppc64/ppc64le
+=============
+
+PowerPC can use either BE or LE instructions, but from qemu point of view
+nothing changes. Still for Avocado-vt you either have to specify
+``--vt-arch ppc64`` or ``--vt-arch ppc64le`` to choose the right distribution
+image (both were available as JeOS when writing this document). Apart from
+this no additional tweaks are necessary::
+
+   $ avocado vt-bootstrap --vt-guest-os JeOS.27.ppc64
+   $ avocado --show all run --vt-extra-params enable_kvm=no --vt-arch ppc64 \
+       --vt-machine-type pseries --vt-qemu-bin /usr/local/bin/qemu-system-ppc64 -- boot
+
+   $ avocado vt-bootstrap --vt-guest-os JeOS.27.ppc64le
+   $ avocado --show all run --vt-extra-params enable_kvm=no --vt-arch ppc64le \
+       --vt-machine-type pseries --vt-qemu-bin /usr/local/bin/qemu-system-ppc64 -- boot
+
+
+s390x
+=====
+
+For KVM execution Avocado-vt uses ``-cpu host`` on s390x, which is not
+possible without KVM. To execute in TCG mode you need to replace it with
+either a supported CPU type or simply leave it blank::
+
+   $ avocado vt-bootstrap --vt-guest-os JeOS.27.s390x
+   $ avocado --show all run --vt-extra-params enable_kvm=no cpu_model='' --vt-arch s390x \
+       --vt-machine-type s390-virtio --vt-qemu-bin /usr/local/bin/qemu-system-s390x -- boot
+
+riscv64
+=======
+
+When writing this document, riscv64 was not available as JeOS and even
+Fedora support was not straight forward. See `riscv64_setup`_ for setup
+instructions. Apart from the setup running riscv64 does not require any
+additional arguments::
+
+   $ avocado run --vt-machine-type riscv64-mmio --vt-arch riscv64 \
+       --vt-extra-params enable_kvm=no --vt-guest-os Fedora.28 -- boot

docs/source/index.rst

@@ -35,6 +35,7 @@ Contents:
    InstallWinVirtio
    RunQemuUnittests
    ParallelJobs
+   RunningInEmulationTCG
    contributing/index
    Experimental