doc: net: Add more info for network connectivity with host

Added more detailed information how to connect Zephyr instance
to host system like Linux desktop.

Signed-off-by: Jukka Rissanen <jukka.rissanen@linux.intel.com>

boards/arm/qemu_cortex_m3/doc/index.rst

@@ -114,6 +114,10 @@ The board supports SLIP networking over an emulated serial port
 (``CONFIG_NET_SLIP_TAP=y``). The detailed setup is described in
 :ref:`networking_with_qemu`.
 
+It is also possible to use the QEMU built-in Ethernet adapter to connect
+to the host system. This is faster than using SLIP and is also the preferred
+way. See :ref:`networking_with_eth_qemu` for details.
+
 References
 **********
 

boards/x86/qemu_x86/doc/index.rst

@@ -122,3 +122,7 @@ Networking
 The board supports SLIP networking over an emulated serial port
 (``CONFIG_NET_SLIP_TAP=y``). The detailed setup is described in
 :ref:`networking_with_qemu`.
+
+It is also possible to use the QEMU built-in Ethernet adapter to connect
+to the host system. This is faster than using SLIP and is also the preferred
+way. See :ref:`networking_with_eth_qemu` for details.

doc/guides/networking/index.rst

@@ -13,6 +13,8 @@ operation of the stacks and how they were implemented.
    overview.rst
    ip-stack-architecture.rst
    networking-api-usage.rst
-   qemu_setup.rst
+   networking_with_host.rst
    native_posix_setup.rst
+   qemu_eth_setup.rst
+   qemu_setup.rst
    usbnet_setup.rst

doc/guides/networking/networking_with_host.rst

@@ -0,0 +1,37 @@
+.. _networking_with_host:
+
+Networking with the host system
+###############################
+
+While developing networking software, it is usually necessary to connect and
+exchange data with the host system like a Linux desktop computer.
+Depending on what board is used for development, the following options are
+possible:
+
+* QEMU using SLIP (Serial Line Internet Protocol).
+
+  * Here IP packets are exchanged between Zephyr and the host system via serial
+    port. This is the legacy way of transferring data. It is also quite slow so
+    use it only when necessary. See :ref:`networking_with_qemu` for details.
+
+* QEMU using built-in Ethernet driver.
+
+  * Here IP packets are exchanged between Zephyr and the host system via QEMU's
+    built-in Ethernet driver. Not all QEMU boards support built-in Ethernet so
+    in some cases, you might need to use the SLIP method for host connectivity.
+    See :ref:`networking_with_eth_qemu` for details.
+
+* native_posix board.
+
+  * The Zepher instance can be executed as a user space process in the host
+    system. This is the most convenient way to debug the Zephyr system as one
+    can attach host debugger directly to the running Zephyr instance. This
+    requires that there is an adaptation driver in Zephyr for interfacing
+    with the host system. An Ethernet driver exists in Zephyr for this purpose.
+    See :ref:`networking_with_native_posix` for details.
+
+* USB device networking.
+
+  * Here, the Zephyr instance is run on a real board and the connectivity to
+    the host system is done via USB.
+    See :ref:`usb_device_networking_setup` for details.

doc/guides/networking/qemu_eth_setup.rst

@@ -0,0 +1,78 @@
+.. _networking_with_eth_qemu:
+
+Networking with QEMU Ethernet
+#############################
+
+This page describes how to set up a virtual network between a (Linux) host
+and a Zephyr application running in QEMU.
+
+In this example, the :ref:`sockets-echo-server-sample` sample application from
+the Zephyr source distribution is run in QEMU. The Zephyr instance is
+connected to a Linux host using a tuntap device which is modeled in Linux as
+an Ethernet network interface.
+
+Prerequisites
+*************
+
+On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located
+in a separate Git repository:
+
+.. code-block:: console
+
+   git clone https://github.com/zephyrproject-rtos/net-tools
+
+
+Basic Setup
+***********
+
+For the steps below, you will need two terminal windows:
+
+* Terminal #1 is terminal window with net-tools being the current
+  directory (``cd net-tools``)
+* Terminal #2 is your usual Zephyr development terminal,
+  with the Zephyr environment initialized.
+
+When configuring the Zephyr instance, you must select the correct Ethernet
+driver for QEMU connectivity:
+
+* For ``qemu_x86``, select ``Intel(R) PRO/1000 Gigabit Ethernet driver``
+  Ethernet driver. Driver is called ``e1000`` in Zephyr source tree.
+* For ``qemu_cortex_m3``, select ``TI Stellaris MCU family ethernet driver``
+  Ethernet driver. Driver is called ``stellaris`` in Zephyr source tree.
+* For ``mps2_an385``, select ``SMSC911x/9220 Ethernet driver`` Ethernet driver.
+  Driver is called ``smsc911x`` in Zephyr source tree.
+
+Step 1 - Create Ethernet interface
+==================================
+
+Before starting QEMU with network connectivity, a network interface
+should be created in the host system.
+
+In terminal #1, type:
+
+.. code-block:: console
+
+   ./net-setup.sh
+
+You can tweak the behavior of the ``net-setup.sh`` script. See various options
+by running ``net-setup.sh`` like this:
+
+.. code-block:: console
+
+   ./net-setup.sh --help
+
+
+Step 2 - Start app in QEMU board
+================================
+
+Build and start the :ref:`sockets-echo-server-sample` sample application.
+In this example, the qemu_x86 board is used.
+
+In terminal #2, type:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/net/sockets/echo_server
+   :host-os: unix
+   :board: qemu_x86
+   :goals: run
+   :compact:

samples/net/dhcpv4_client/README.rst

@@ -13,7 +13,7 @@ information to a serial console.
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/dns_resolve/README.rst

@@ -29,7 +29,7 @@ For more information about DNS configuration variables, see:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 - screen terminal emulator or equivalent.
 

samples/net/gptp/README.rst

@@ -17,7 +17,8 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_native_posix`
+For generic host connectivity, that can be used for debugging purposes, see
+:ref:`networking_with_native_posix` for details.
 
 Building and Running
 ********************

samples/net/ipv4_autoconf/README.rst

@@ -14,7 +14,7 @@ parties try to allocate an identical address.
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/lldp/README.rst

@@ -15,7 +15,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/sockets/big_http_download/README.rst

@@ -20,7 +20,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking
 - NAT/routing should be set up to allow connections to the Internet
 - DNS server should be available on the host to resolve domain names

samples/net/sockets/coap_client/README.rst

@@ -28,8 +28,8 @@ be obtained by using a tool such as tcpdump or wireshark.
 
 See the `net-tools`_ project for more details.
 
-This sample can be built and executed on QEMU as described
-in :ref:`networking_with_qemu`.
+This sample can be built and executed on QEMU or native_posix board as described
+in :ref:`networking_with_host`.
 
 Sample output
 =============

samples/net/sockets/coap_server/README.rst

@@ -38,8 +38,8 @@ or wireshark.
 
 See the `net-tools`_ project for more details
 
-This sample can be built and executed on QEMU as described
-in :ref:`networking_with_qemu`.
+This sample can be built and executed on QEMU or native_posix board as
+described in :ref:`networking_with_host`.
 
 Use this command on the host to run the `libcoap`_ implementation of
 the ETSI test cases:

samples/net/sockets/dumb_http_server/README.rst

@@ -23,7 +23,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking
 
 Building and Running

samples/net/sockets/echo/README.rst

@@ -17,7 +17,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking
 
 Building and Running

samples/net/sockets/echo_async/README.rst

@@ -19,7 +19,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking (including 6LoWPAN)
 
 Building and Running

samples/net/sockets/echo_async_select/README.rst

@@ -17,7 +17,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking (including 6LoWPAN)
 
 Building and Running

samples/net/sockets/echo_client/README.rst

@@ -16,7 +16,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/sockets/echo_server/README.rst

@@ -17,7 +17,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/sockets/http_get/README.rst

@@ -18,7 +18,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 - or, a board with hardware networking
 - NAT/routing should be set up to allow connections to the Internet
 - DNS server should be available on the host to resolve domain names

samples/net/sockets/packet/README.rst

@@ -22,7 +22,7 @@ sent and received packets.
 
 See the `net-tools`_ project for more details.
 
-This sample can be built and executed on QEMU as described
-in :ref:`networking_with_qemu`.
+This sample can be built and executed on QEMU or native_posix board as
+described in :ref:`networking_with_host`.
 
 .. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools

samples/net/sockets/sntp_client/README.rst

@@ -23,7 +23,7 @@ printed.
 
 See the `net-tools`_ project for more details.
 
-This sample can be built and executed on QEMU as described
-in :ref:`networking_with_qemu`.
+This sample can be built and executed on QEMU or native_posix board as
+described in :ref:`networking_with_qemu`.
 
 .. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools

samples/net/stats/README.rst

@@ -15,13 +15,13 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************
 
-A good way to run this sample application is with QEMU as described in
-:ref:`networking_with_qemu`.
+A good way to run this sample application is with QEMU or native_posix board
+as described in :ref:`networking_with_host`.
 
 Follow these steps to build the network statistics sample application:
 

samples/net/syslog_net/README.rst

@@ -17,7 +17,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************

samples/net/vlan/README.rst

@@ -15,7 +15,7 @@ The source code for this sample application can be found at:
 Requirements
 ************
 
-- :ref:`networking_with_qemu`
+- :ref:`networking_with_host`
 
 Building and Running
 ********************