README.rst
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
