1.. zephyr:code-sample:: eth-ivshmem
2   :name: Inter-VM Shared Memory (ivshmem) Ethernet
3   :relevant-api: ivshmem ethernet
4
5   Communicate with another "cell" in the Jailhouse hypervisor using IVSHMEM Ethernet.
6
7Overview
8********
9
10This application demonstrates how to use IVSHMEM Ethernet to communicate with
11another "cell" in the Jailhouse hypervisor. Currently only the qemu_cortex_a53
12board is supported.
13
14Building Jailhouse Linux for QEMU
15*********************************
16
17Clone Jailhouse yocto project. At the time of writing, the "next" branch has
18some fixes that are not yet on the "master" branch:
19
20.. code-block:: console
21
22    git clone https://github.com/siemens/jailhouse-images.git
23    cd jailhouse-images
24    git checkout origin/next
25
26Open the menu, select "QEMU ARM64 virtual target" then "Save & Build"
27(this will take a while):
28
29.. code-block:: console
30
31    ./kas-container menu
32
33Edit "start-qemu.sh":
34 * change ``-cpu cortex-a57`` -> ``-cpu cortex-a53``
35   under the ``arm64|aarch64`` case
36 * Enable SSH access by appending ``,hostfwd=tcp::2222-:22`` to
37   ``-netdev user,id=net`` in the QEMU process arguments
38   (2222 can be replaced with any unused port)
39
40Start QEMU:
41
42.. code-block:: console
43
44    ./start-qemu.sh arm64
45
46This should boot Linux and drop into a shell.
47
48Build the Zephyr sample
49***********************
50
51.. zephyr-app-commands::
52   :zephyr-app: samples/drivers/ethernet/eth_ivshmem
53   :board: qemu_cortex_a53
54   :goals: build
55
56Running the sample
57******************
58
59Copy the generated zephyr.bin to the Jailhouse Linux root cell:
60
61.. code-block:: console
62
63    scp -P 2222 path/to/zephyr.bin root@localhost:/root
64
65Jailhouse has a prebuilt Zephyr cell configuration that works for
66this sample "qemu-arm64-zephyr-demo".
67
68Back in Jailhouse Linux shell, create the Zephyr cell:
69
70.. code-block:: console
71
72    jailhouse enable /etc/jailhouse/qemu-arm64.cell
73    jailhouse console
74    jailhouse cell create /etc/jailhouse/qemu-arm64-zephyr-demo.cell
75
76You may see a quirk here where the Linux shell stops taking input...
77If you get this, open a second shell via SSH:
78
79.. code-block:: console
80
81    ssh -p 2222 root@localhost
82
83Load and start the Zephyr cell:
84
85.. code-block:: console
86
87    jailhouse cell load qemu-arm64-zephyr-demo zephyr.bin --address 0x70000000
88    jailhouse cell start qemu-arm64-zephyr-demo
89
90Now you can run Zephyr and Linux shell commands to communicate between
91the cells.
92
93Ping Linux from Zephyr
94**********************
95
96.. code-block:: console
97
98    *** Booting Zephyr OS build v3.3.0-475-g45b9e84c6013 ***
99    uart:~$ net ping 192.168.19.1
100    PING 192.168.19.1
101    28 bytes from 192.168.19.1 to 192.168.19.2: icmp_seq=1 ttl=64 time=5.06 ms
102    28 bytes from 192.168.19.1 to 192.168.19.2: icmp_seq=2 ttl=64 time=7.99 ms
103    28 bytes from 192.168.19.1 to 192.168.19.2: icmp_seq=3 ttl=64 time=1.77 ms
104
105Ping Zephyr from Linux
106**********************
107
108.. code-block:: console
109
110    root@demo:~# ping -c 3 192.168.19.2
111    PING 192.168.19.2 (192.168.19.2) 56(84) bytes of data.
112    64 bytes from 192.168.19.2: icmp_seq=1 ttl=64 time=0.646 ms
113    64 bytes from 192.168.19.2: icmp_seq=2 ttl=64 time=1.45 ms
114    64 bytes from 192.168.19.2: icmp_seq=3 ttl=64 time=1.28 ms
115
116    --- 192.168.19.2 ping statistics ---
117    3 packets transmitted, 3 received, 0% packet loss, time 2006ms
118    rtt min/avg/max/mdev = 0.646/1.124/1.450/0.345 ms
119
120Run zperf / iPerf
121*****************
122
123:ref:`zperf` / iPerf can be used to perform network throughput measurements.
124
125In Zephyr:
126
127.. code-block:: console
128
129    # Start zperf TCP server
130    zperf tcp download 5001
131
132In Linux:
133
134.. code-block:: console
135
136    # Install iPerf 2.0.5
137    apt install wget
138    wget https://iperf.fr/download/ubuntu/iperf_2.0.5+dfsg1-2_arm64.deb
139    apt install ./iperf_2.0.5+dfsg1-2_arm64.deb
140    rm iperf_2.0.5+dfsg1-2_arm64.deb
141
142    # Connect iPerf TCP client
143    iperf -l 1K -V -c 192.168.19.2 -p 5001
144
145Zephyr output:
146
147.. code-block:: console
148
149    TCP server started on port 5001
150    New TCP session started.
151    TCP session ended
152     Duration:              10.01 s
153     rate:                  57.72 Mbps
154
155Linux output:
156
157.. code-block:: console
158
159    ------------------------------------------------------------
160    Client connecting to 192.168.19.2, TCP port 5001
161    TCP window size: 85.0 KByte (default)
162    ------------------------------------------------------------
163    [  3] local 192.168.19.1 port 58430 connected with 192.168.19.2 port 5001
164    [ ID] Interval       Transfer     Bandwidth
165    [  3]  0.0-10.0 sec  72.2 MBytes  60.6 Mbits/sec
166