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, 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* For ``qemu_cortex_a53``, ``Intel(R) PRO/1000 Gigabit Ethernet driver``
49  Ethernet driver is selected by default.
50
51Step 1 - Create Ethernet interface
52==================================
53
54Before starting QEMU with network connectivity, a network interface
55should be created in the host system.
56
57In terminal #1, type:
58
59.. code-block:: console
60
61   ./net-setup.sh
62
63You can tweak the behavior of the ``net-setup.sh`` script. See various options
64by running ``net-setup.sh`` like this:
65
66.. code-block:: console
67
68   ./net-setup.sh --help
69
70
71Step 2 - Start app in QEMU board
72================================
73
74Build and start the :zephyr:code-sample:`sockets-echo-server` sample application.
75In this example, the qemu_x86 board is used.
76
77In terminal #2, type:
78
79.. zephyr-app-commands::
80   :zephyr-app: samples/net/sockets/echo_server
81   :host-os: unix
82   :board: qemu_x86
83   :gen-args: -DEXTRA_CONF_FILE=overlay-e1000.conf
84   :goals: run
85   :compact:
86
87Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
88