1.. _networking_with_eth_qemu:
2
3Networking with QEMU Ethernet
4#############################
5
6.. contents::
7    :local:
8    :depth: 2
9
10This page describes how to set up a virtual network between a (Linux) host
11and a Zephyr application running in QEMU.
12
13In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from
14the Zephyr source distribution is run in QEMU. The Zephyr instance is
15connected to a Linux host using a tuntap device which is modeled in Linux as
16an Ethernet network interface.
17
18Prerequisites
19*************
20
21On the Linux Host, find the Zephyr `net-tools`_ project, which can either be
22found in a Zephyr standard installation under the ``tools/net-tools`` directory
23or installed stand alone from its own git repository:
24
25.. code-block:: console
26
27   git clone https://github.com/zephyrproject-rtos/net-tools
28
29
30Basic Setup
31***********
32
33For the steps below, you will need two terminal windows:
34
35* Terminal #1 is terminal window with net-tools being the current
36  directory (``cd net-tools``)
37* Terminal #2 is your usual Zephyr development terminal,
38  with the Zephyr environment initialized.
39
40When configuring the Zephyr instance, you must select the correct Ethernet
41driver for QEMU connectivity:
42
43* For ``qemu_x86``, select ``Intel(R) PRO/1000 Gigabit Ethernet driver``
44  Ethernet driver. Driver is called ``e1000`` in Zephyr source tree.
45* For ``qemu_cortex_m3``, select ``TI Stellaris MCU family ethernet driver``
46  Ethernet driver. Driver is called ``stellaris`` in Zephyr source tree.
47* For ``mps2_an385``, select ``SMSC911x/9220 Ethernet driver`` Ethernet driver.
48  Driver is called ``smsc911x`` in Zephyr source tree.
49* For ``qemu_cortex_a53``, ``Intel(R) PRO/1000 Gigabit Ethernet driver``
50  Ethernet driver is selected by default.
51
52Step 1 - Create Ethernet interface
53==================================
54
55Before starting QEMU with network connectivity, a network interface
56should be created in the host system.
57
58In terminal #1, type:
59
60.. code-block:: console
61
62   ./net-setup.sh
63
64You can tweak the behavior of the ``net-setup.sh`` script. See various options
65by running ``net-setup.sh`` like this:
66
67.. code-block:: console
68
69   ./net-setup.sh --help
70
71
72Step 2 - Start app in QEMU board
73================================
74
75Build and start the :zephyr:code-sample:`sockets-echo-server` sample application.
76In this example, the qemu_x86 board is used.
77
78In terminal #2, type:
79
80.. zephyr-app-commands::
81   :zephyr-app: samples/net/sockets/echo_server
82   :host-os: unix
83   :board: qemu_x86
84   :gen-args: -DEXTRA_CONF_FILE=overlay-e1000.conf
85   :goals: run
86   :compact:
87
88Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
89
90.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
91