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 :ref:`sockets-echo-server-sample` 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, fetch the Zephyr ``net-tools`` project, which is located
22in a separate Git repository:
23
24.. code-block:: console
25
26   git clone https://github.com/zephyrproject-rtos/net-tools
27
28
29Basic Setup
30***********
31
32For the steps below, you will need two terminal windows:
33
34* Terminal #1 is terminal window with net-tools being the current
35  directory (``cd net-tools``)
36* Terminal #2 is your usual Zephyr development terminal,
37  with the Zephyr environment initialized.
38
39When configuring the Zephyr instance, you must select the correct Ethernet
40driver for QEMU connectivity:
41
42* For ``qemu_x86``, select ``Intel(R) PRO/1000 Gigabit Ethernet driver``
43  Ethernet driver. Driver is called ``e1000`` in Zephyr source tree.
44* For ``qemu_cortex_m3``, select ``TI Stellaris MCU family ethernet driver``
45  Ethernet driver. Driver is called ``stellaris`` in Zephyr source tree.
46* For ``mps2_an385``, select ``SMSC911x/9220 Ethernet driver`` Ethernet driver.
47  Driver is called ``smsc911x`` in Zephyr source tree.
48
49Step 1 - Create Ethernet interface
50==================================
51
52Before starting QEMU with network connectivity, a network interface
53should be created in the host system.
54
55In terminal #1, type:
56
57.. code-block:: console
58
59   ./net-setup.sh
60
61You can tweak the behavior of the ``net-setup.sh`` script. See various options
62by running ``net-setup.sh`` like this:
63
64.. code-block:: console
65
66   ./net-setup.sh --help
67
68
69Step 2 - Start app in QEMU board
70================================
71
72Build and start the :ref:`sockets-echo-server-sample` sample application.
73In this example, the qemu_x86 board is used.
74
75In terminal #2, type:
76
77.. zephyr-app-commands::
78   :zephyr-app: samples/net/sockets/echo_server
79   :host-os: unix
80   :board: qemu_x86
81   :gen-args: -DEXTRA_CONF_FILE=overlay-e1000.conf
82   :goals: run
83   :compact:
84
85Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
86