doc: clean up QEMU networking doc

Noticed a typo in the first sentence, then some missing articles further
down, and some other clarity and grammar edits came along.

Signed-off-by: David B. Kinder <[email protected]>

Author: dbkinder

doc/subsystems/networking/qemu_setup.rst

@@ -3,19 +3,21 @@
 Networking with QEMU
 ####################
 
-This page describes how to set up a "virtual" networking between a (Linux) host
+This page describes how to set up a virtual network between a (Linux) host
 and a Zephyr application running in a QEMU virtual machine (built for Zephyr
-targets like qemu_x86, qemu_cortex_m3, etc.) In this example, the
-``echo_server`` sample application from Zephyr source distribution is run in
-QEMU. The QEMU instance is connected to Linux host using serial port and SLIP is
-used to transfer data between Zephyr and Linux (over a chain of virtual
-connections).
+targets such as qemu_x86 and qemu_cortex_m3).
+
+In this example, the :ref:`echo-server-sample` sample application from
+the Zephyr source distribution is run in QEMU. The QEMU instance is
+connected to a Linux host using a serial port, and SLIP is used to
+transfer data between the Zephyr application and Linux (over a chain of
+virtual connections).
 
 Prerequisites
 *************
 
-On the Linux Host you need to fetch Zephyr net-tools project, which is located
-in a separate git repository:
+On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located
+in a separate Git repository:
 
 .. code-block:: console
 
@@ -25,18 +27,18 @@ in a separate git repository:
 
 .. note::
 
-   If you get error about AX_CHECK_COMPILE_FLAG, install package autoconf-archive
-   package on Debian/Ubuntu.
+   If you get an error about AX_CHECK_COMPILE_FLAG, install package
+   ``autoconf-archive`` package on Debian/Ubuntu.
 
 Basic Setup
 ***********
 
 For the steps below, you will need at least 4 terminal windows:
 
-* Terminal #1 is your usual Zephyr development terminal, with Zephyr environment
+* Terminal #1 is your usual Zephyr development terminal, with the Zephyr environment
   initialized.
-* Terminals #2, #3, #4 - fresh terminal windows with net-tools being the current
-  directory ("cd net-tools")
+* Terminals #2, #3, and #4 are terminal windows with net-tools being the current
+  directory (``cd net-tools``)
 
 Step 1 - Create helper socket
 =============================
@@ -75,7 +77,7 @@ In terminal #1, type:
    :goals: run
    :compact:
 
-If you see error from QEMU about unix:/tmp/slip.sock, it means you missed Step 1
+If you see an error from QEMU about unix:/tmp/slip.sock, it means you missed Step 1
 above.
 
 Step 4 - Run apps on host
@@ -91,7 +93,7 @@ You can start with pings:
    ping 192.0.2.1
    ping6 2001:db8::1
 
-For example, using netcat ("nc") utility, connecting using UDP:
+You can use the netcat ("nc") utility, connecting using UDP:
 
 .. code-block:: console
 
@@ -104,7 +106,7 @@ For example, using netcat ("nc") utility, connecting using UDP:
    foobar
 
 If echo_server is compiled with TCP support (now enabled by default for
-echo_server sample, CONFIG_NET_TCP=y):
+the echo_server sample, CONFIG_NET_TCP=y):
 
 .. code-block:: console
 
@@ -113,7 +115,7 @@ echo_server sample, CONFIG_NET_TCP=y):
 
 .. note::
 
-   You will need to Ctrl+C manually.
+   Use Ctrl+C to exit.
 
 You can also use the telnet command to achieve the above.
 
@@ -122,36 +124,35 @@ Step 5 - Stop supporting daemons
 
 When you are finished with network testing using QEMU, you should stop
 any daemons or helpers started in the initial steps, to avoid possible
-networking or routing problems such as address conflicts in local network
-interfaces. For example, you definitely need to stop them if you switch
-from testing networking with QEMU to using real hardware. For example,
-there was a report of an airport WiFi connection not working during
-travel due to an address conflict.
+networking or routing problems such as address conflicts in local
+network interfaces. For example, stop them if you switch from testing
+networking with QEMU to using real hardware, or to return your host
+laptop to normal WiFi use.
 
-To stop the daemons, just press Ctrl+C in the corresponding terminal windows
+To stop the daemons, press Ctrl+C in the corresponding terminal windows
 (you need to stop both ``loop-slip-tap.sh`` and ``loop-socat.sh``).
 
 
 Setting up Zephyr and NAT/masquerading on QEMU host to access Internet
 **********************************************************************
 
-To access the Internet from a Zephyr application using IPv4,
+To access the internet from a Zephyr application using IPv4,
 a gateway should be set via DHCP or configured manually.
 For applications using the :ref:`net_app_api` facility (with the config option
 :option:`CONFIG_NET_APP` enabled),
 set the :option:`CONFIG_NET_APP_MY_IPV4_GW` option to the IP address
 of the gateway. For apps not using the :ref:`net_app_api` facility, set up the
 gateway by calling the :c:func:`net_if_ipv4_set_gw` at runtime.
 
-To access Internet from a custom application running in a QEMU, NAT
+To access the internet from a custom application running in QEMU, NAT
 (masquerading) should be set up for QEMU's source address. Assuming 192.0.2.1 is
 used, the following command should be run as root:
 
 .. code-block:: console
 
    iptables -t nat -A POSTROUTING -j MASQUERADE -s 192.0.2.1
 
-Additionally, IPv4 forwarding should be enabled on host, and you may need to
+Additionally, IPv4 forwarding should be enabled on the host, and you may need to
 check that other firewall (iptables) rules don't interfere with masquerading.
 To enable IPv4 forwarding the following command should be run as root:
 
@@ -162,9 +163,10 @@ To enable IPv4 forwarding the following command should be run as root:
 Network connection between two QEMU VMs
 ***************************************
 
-Unlike VM-Host setup described above, VM-VM setup is automatic - for sample
-applications which support such mode such as the echo_server and echo_client
-samples, you will need 2 terminal windows, set up for Zephyr development.
+Unlike the VM-to-Host setup described above, VM-to-VM setup is
+automatic. For sample
+applications that support this mode (such as the echo_server and echo_client
+samples), you will need two terminal windows, set up for Zephyr development.
 
 Terminal #1:
 ============
@@ -177,7 +179,7 @@ Terminal #1:
    :build-args: server
    :compact:
 
-This will start QEMU, waiting for connection from a client QEMU.
+This will start QEMU, waiting for a connection from a client QEMU.
 
 Terminal #2:
 ============
@@ -190,18 +192,19 @@ Terminal #2:
    :build-args: client
    :compact:
 
-This will start 2nd QEMU instance, and you should see logging of data sent and
+This will start a second QEMU instance, where you should see logging of data sent and
 received in both.
 
 Running multiple QEMU VMs of the same sample
 ********************************************
 
-If you find yourself needing to run multiple instances of the same Zephyr
-sample application, which do not need to be able to talk to each other, the
-``QEMU_INSTANCE`` argument is what you need.
+If you find yourself wanting to run multiple instances of the same Zephyr
+sample application, which do not need to talk to each other, use the
+``QEMU_INSTANCE`` argument.
 
-Start socat and tunslip6 manually (avoiding loop-x.sh scripts) for as many
-instances as you want. Use the following as a guide, replacing MAIN or OTHER.
+Start ``socat`` and ``tunslip6`` manually (instead of using the
+``loop-xxx.sh`` scripts) for as many instances as you want. Use the
+following as a guide, replacing MAIN or OTHER.
 
 Terminal #1:
 ============