1 files changed, 63 insertions, 55 deletions

diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 766691b97b..19f3e40d63 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -44,31 +44,29 @@ To use QEMU, you need to have QEMU installed and initialized as well as
 have the proper artifacts (i.e. image files and root filesystems)
 available. Follow these general steps to run QEMU:
 
-1. *Install QEMU:* QEMU is made available with the Yocto Project a
+#. *Install QEMU:* QEMU is made available with the Yocto Project a
    number of ways. One method is to install a Software Development Kit
    (SDK). See ":ref:`sdk-manual/intro:the qemu emulator`" section in the
    Yocto Project Application Development and the Extensible Software
    Development Kit (eSDK) manual for information on how to install QEMU.
 
-2. *Setting Up the Environment:* How you set up the QEMU environment
+#. *Setting Up the Environment:* How you set up the QEMU environment
    depends on how you installed QEMU:
 
    -  If you cloned the ``poky`` repository or you downloaded and
       unpacked a Yocto Project release tarball, you can source the build
-      environment script (i.e. :ref:`structure-core-script`):
-      ::
+      environment script (i.e. :ref:`structure-core-script`)::
 
-         $ cd ~/poky
+         $ cd poky
          $ source oe-init-build-env
 
    -  If you installed a cross-toolchain, you can run the script that
       initializes the toolchain. For example, the following commands run
-      the initialization script from the default ``poky_sdk`` directory:
-      ::
+      the initialization script from the default ``poky_sdk`` directory::
 
-         . ~/poky_sdk/environment-setup-core2-64-poky-linux
+         . poky_sdk/environment-setup-core2-64-poky-linux
 
-3. *Ensure the Artifacts are in Place:* You need to be sure you have a
+#. *Ensure the Artifacts are in Place:* You need to be sure you have a
    pre-built kernel that will boot in QEMU. You also need the target
    root filesystem for your target machine's architecture:
 
@@ -86,8 +84,7 @@ available. Follow these general steps to run QEMU:
    Extensible Software Development Kit (eSDK) manual for information on
    how to extract a root filesystem.
 
-4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
-   ::
+#. *Run QEMU:* The basic ``runqemu`` command syntax is as follows::
 
       $ runqemu [option ] [...]
 
@@ -102,12 +99,13 @@ available. Follow these general steps to run QEMU:
    Here are some additional examples to help illustrate further QEMU:
 
    -  This example starts QEMU with MACHINE set to "qemux86-64".
-      Assuming a standard
-      :term:`Build Directory`, ``runqemu``
+      Assuming a standard :term:`Build Directory`, ``runqemu``
       automatically finds the ``bzImage-qemux86-64.bin`` image file and
       the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4``
       (assuming the current build created a ``core-image-minimal``
-      image).
+      image)::
+
+        $ runqemu qemux86-64
 
       .. note::
 
@@ -115,38 +113,31 @@ available. Follow these general steps to run QEMU:
          and uses the most recently built image according to the
          timestamp.
 
-      ::
-
-        $ runqemu qemux86-64
-
    -  This example produces the exact same results as the previous
       example. This command, however, specifically provides the image
-      and root filesystem type.
-      ::
+      and root filesystem type::
 
          $ runqemu qemux86-64 core-image-minimal ext4
 
-   -  This example specifies to boot an initial RAM disk image and to
-      enable audio in QEMU. For this case, ``runqemu`` set the internal
-      variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
-      an appropriate driver must be installed (see the previous
-      description for the ``audio`` option for more information).
-      ::
+   -  This example specifies to boot an :term:`Initramfs` image and to
+      enable audio in QEMU. For this case, ``runqemu`` sets the internal
+      variable ``FSTYPE`` to ``cpio.gz``. Also, for audio to be enabled,
+      an appropriate driver must be installed (see the ``audio`` option
+      in :ref:`dev-manual/qemu:\`\`runqemu\`\` command-line options`
+      for more information)::
 
          $ runqemu qemux86-64 ramfs audio
 
    -  This example does not provide enough information for QEMU to
       launch. While the command does provide a root filesystem type, it
-      must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
-      ::
+      must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option::
 
          $ runqemu ext4
 
    -  This example specifies to boot a virtual machine image
       (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
       determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
-      the root filesystem type to be "vmdk".
-      ::
+      the root filesystem type to be "vmdk"::
 
          $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
 
@@ -193,7 +184,7 @@ the system does not need root privileges to run. It uses a user space
 NFS server to avoid that. Follow these steps to set up for running QEMU
 using an NFS server.
 
-1. *Extract a Root Filesystem:* Once you are able to run QEMU in your
+#. *Extract a Root Filesystem:* Once you are able to run QEMU in your
    environment, you can use the ``runqemu-extract-sdk`` script, which is
    located in the ``scripts`` directory along with the ``runqemu``
    script.
@@ -207,7 +198,7 @@ using an NFS server.
 
       runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
 
-2. *Start QEMU:* Once you have extracted the file system, you can run
+#. *Start QEMU:* Once you have extracted the file system, you can run
    ``runqemu`` normally with the additional location of the file system.
    You can then also make changes to the files within ``./test-nfs`` and
    see those changes appear in the image in real time. Here is an
@@ -222,18 +213,15 @@ using an NFS server.
    Should you need to start, stop, or restart the NFS share, you can use
    the following commands:
 
-   -  The following command starts the NFS share:
-      ::
+   -  To start the NFS share::
 
          runqemu-export-rootfs start file-system-location
 
-   -  The following command stops the NFS share:
-      ::
+   -  To stop the NFS share::
 
          runqemu-export-rootfs stop file-system-location
 
-   -  The following command restarts the NFS share:
-      ::
+   -  To restart the NFS share::
 
          runqemu-export-rootfs restart file-system-location
 
@@ -252,11 +240,10 @@ be a problem when QEMU is running with KVM enabled. Specifically,
 software compiled with a certain CPU feature crashes when run on a CPU
 under KVM that does not support that feature. To work around this
 problem, you can override QEMU's runtime CPU setting by changing the
-``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the
-:term:`Build Directory` ``deploy/image``
-directory. This setting specifies a ``-cpu`` option passed into QEMU in
-the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of
-available supported CPU types.
+``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the :term:`Build Directory`
+``deploy/image`` directory. This setting specifies a ``-cpu`` option passed
+into QEMU in the ``runqemu`` script. Running ``qemu -cpu help`` returns a
+list of available supported CPU types.
 
 QEMU Performance
 ================
@@ -281,7 +268,7 @@ present, the toolchain is also automatically used.
 
 .. note::
 
-   Several mechanisms exist that let you connect to the system running
+   There are several mechanisms to connect to the system running
    on the QEMU emulator:
 
    -  QEMU provides a framebuffer interface that makes standard consoles
@@ -292,7 +279,7 @@ present, the toolchain is also automatically used.
       that port to run a console. The connection uses standard IP
       networking.
 
-   -  SSH servers exist in some QEMU images. The ``core-image-sato``
+   -  SSH servers are available in some QEMU images. The ``core-image-sato``
       QEMU image has a Dropbear secure shell (SSH) server that runs with
       the root password disabled. The ``core-image-full-cmdline`` and
       ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.
@@ -306,15 +293,14 @@ present, the toolchain is also automatically used.
       tarball by using the ``runqemu-extract-sdk`` command. After
       running the command, you must then point the ``runqemu`` script to
       the extracted directory instead of a root filesystem image file.
-      See the "`Running Under a Network File System (NFS)
-      Server <#qemu-running-under-a-network-file-system-nfs-server>`__"
+      See the
+      ":ref:`dev-manual/qemu:running under a network file system (nfs) server`"
       section for more information.
 
 QEMU Command-Line Syntax
 ========================
 
-The basic ``runqemu`` command syntax is as follows:
-::
+The basic ``runqemu`` command syntax is as follows::
 
    $ runqemu [option ] [...]
 
@@ -325,8 +311,7 @@ timestamp when it needs to look for an image. Minimally, through the use
 of options, you must provide either a machine name, a virtual machine
 image (``*wic.vmdk``), or a kernel image (``*.bin``).
 
-Following is the command-line help output for the ``runqemu`` command:
-::
+Here is the command-line help output for the ``runqemu`` command::
 
    $ runqemu --help
 
@@ -338,7 +323,7 @@ Following is the command-line help output for the ``runqemu`` command:
      Simplified QEMU command-line options can be passed with:
        nographic - disable video console
        serial - enable a serial console on /dev/ttyS0
-       slirp - enable user networking, no root privileges is required
+       slirp - enable user networking, no root privileges required
        kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
        kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
        publicvnc - enable a VNC server open to all hosts
@@ -368,7 +353,7 @@ Following is the command-line help output for the ``runqemu`` command:
 ``runqemu`` Command-Line Options
 ================================
 
-Following is a description of ``runqemu`` options you can provide on the
+Here is a description of ``runqemu`` options you can provide on the
 command line:
 
 .. note::
@@ -402,7 +387,7 @@ command line:
    options are basically identical. If you do not provide a MACHINE
    option, ``runqemu`` tries to determine it based on other options.
 
--  ``ramfs``: Indicates you are booting an initial RAM disk (initramfs)
+-  ``ramfs``: Indicates you are booting an :term:`Initramfs`
    image, which means the ``FSTYPE`` is ``cpio.gz``.
 
 -  ``iso``: Indicates you are booting an ISO image, which means the
@@ -436,6 +421,29 @@ command line:
    networking that does not need root access but also is not as easy to
    use or comprehensive as the default.
 
+   Using ``slirp`` by default will forward the guest machine's
+   22 and 23 TCP ports to host machine's 2222 and 2323 ports
+   (or the next free ports). Specific forwarding rules can be configured
+   by setting ``QB_SLIRP_OPT`` as environment variable or in ``qemuboot.conf``
+   in the :term:`Build Directory` ``deploy/image`` directory.
+   Examples::
+
+      QB_SLIRP_OPT="-netdev user,id=net0,hostfwd=tcp::8080-:80"
+
+      QB_SLIRP_OPT="-netdev user,id=net0,hostfwd=tcp::8080-:80,hostfwd=tcp::2222-:22"
+
+   The first example forwards TCP port 80 from the emulated system to
+   port 8080 (or the next free port) on the host system,
+   allowing access to an http server running in QEMU from
+   ``http://<host ip>:8080/``.
+
+   The second example does the same, but also forwards TCP port 22 on the
+   guest system to 2222 (or the next free port) on the host system,
+   allowing ssh access to the emulated system using
+   ``ssh -P 2222 <user>@<host ip>``.
+
+   Keep in mind that proper configuration of firewall software is required.
+
 -  ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU
    architectures. For KVM to work, all the following conditions must be
    met:
@@ -452,7 +460,7 @@ command line:
    or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the
    following conditions must be met:
 
-   -  `kvm <#kvm-cond>`__ option conditions must be met.
+   -  ``kvm`` option conditions defined above must be met.
 
    -  Your build host has to have virtio net device, which are
       ``/dev/vhost-net``.