1.. _zperf:
2
3zperf: Network Traffic Generator
4################################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13zperf is a shell utility which allows to generate network traffic in Zephyr. The
14tool may be used to evaluate network bandwidth.
15
16zperf is compatible with iPerf 2.0.10 and newer. For compatibility with older versions,
17enable :kconfig:option:`CONFIG_NET_ZPERF_LEGACY_HEADER_COMPAT`.
18
19zperf can be enabled in any application, a dedicated sample is also present
20in Zephyr. See :zephyr:code-sample:`zperf sample application <zperf>` for details.
21
22Sample Usage
23************
24
25If Zephyr acts as a client, iPerf must be executed in server mode.
26For example, the following command line must be used for UDP testing:
27
28.. code-block:: console
29
30   $ iperf -s -l 1K -u -V -B 2001:db8::2
31
32For TCP testing, the command line would look like this:
33
34.. code-block:: console
35
36   $ iperf -s -l 1K -V -B 2001:db8::2
37
38
39In the Zephyr console, zperf can be executed as follows:
40
41.. code-block:: console
42
43   zperf udp upload 2001:db8::2 5001 10 1K 1M
44
45
46For TCP the zperf command would look like this:
47
48.. code-block:: console
49
50   zperf tcp upload 2001:db8::2 5001 10 1K 1M
51
52
53If the IP addresses of Zephyr and the host machine are specified in the
54config file, zperf can be started as follows:
55
56.. code-block:: console
57
58   zperf udp upload2 v6 10 1K 1M
59
60
61or like this if you want to test TCP:
62
63.. code-block:: console
64
65   zperf tcp upload2 v6 10 1K 1M
66
67
68If Zephyr is acting as a server, set the download mode as follows for UDP:
69
70.. code-block:: console
71
72   zperf udp download 5001
73
74
75or like this for TCP:
76
77.. code-block:: console
78
79   zperf tcp download 5001
80
81
82and in the host side, iPerf must be executed with the following
83command line if you are testing UDP:
84
85.. code-block:: console
86
87   $ iperf -l 1K -u -V -c 2001:db8::1 -p 5001
88
89
90and this if you are testing TCP:
91
92.. code-block:: console
93
94   $ iperf -l 1K -V -c 2001:db8::1 -p 5001
95
96
97iPerf output can be limited by using the -b option if Zephyr is not
98able to receive all the packets in orderly manner.
99
100Session Management
101******************
102
103If :kconfig:option:`CONFIG_ZPERF_SESSION_PER_THREAD` option is set, then
104multiple upload sessions can be done at the same time if user supplies ``-a``
105option when starting the upload. Each session will have their own work queue
106to run the test. The session test results can be viewed also after the tests
107have finished. The sessions can be started with ``-w`` option which then
108lets the worker threads to wait a start signal so that all the threads can
109be started at the same time. This will prevent the case where the zperf shell
110cannot run because it is running in lower priority than the already started
111session thread. If you have only one upload session, then the ``-w`` is not
112really needed.
113
114Following zperf shell commands are available for session management:
115
116.. csv-table::
117   :header: "zperf shell command", "Description"
118   :widths: auto
119
120   "``jobs``", "Show currently active or finished sessions"
121   "``jobs all``", "Show statistics of finished sessions"
122   "``jobs clear``", "Clear finished session statistics"
123   "``jobs start``", "Start all the waiting sessions"
124
125Example:
126
127.. code-block:: console
128
129   uart:~$ zperf udp upload -a -t 5 192.0.2.2 5001 10 1K 1M
130   Remote port is 5001
131   Connecting to 192.0.2.2
132   Duration:       10.00 s
133   Packet size:    1000 bytes
134   Rate:           1000 kbps
135   Starting...
136   Rate:           1.00 Mbps
137   Packet duration 7 ms
138
139   uart:~$ zperf jobs all
140   No sessions sessions found
141   uart:~$ zperf jobs
142              Thread    Remaining
143   Id  Proto  Priority  time (sec)
144   [1] UDP    5            4
145
146   Active sessions have not yet finished
147   -
148   Upload completed!
149   Statistics:             server  (client)
150   Duration:               30.01 s (30.01 s)
151   Num packets:            3799    (3799)
152   Num packets out order:  0
153   Num packets lost:       0
154   Jitter:                 63 us
155   Rate:                   1.01 Mbps       (1.01 Mbps)
156   Thread priority:        5
157   Protocol:               UDP
158   Session id:             1
159
160   uart:~$ zperf jobs all
161   -
162   Upload completed!
163   Statistics:             server  (client)
164   Duration:               30.01 s (30.01 s)
165   Num packets:            3799    (3799)
166   Num packets out order:  0
167   Num packets lost:       0
168   Jitter:                 63 us
169   Rate:                   1.01 Mbps       (1.01 Mbps)
170   Thread priority:        5
171   Protocol:               UDP
172   Session id:             1
173   Total 1 sessions done
174
175   uart:~$ zperf jobs clear
176   Cleared data from 1 sessions
177
178   uart:~$ zperf jobs
179   No active upload sessions
180   No finished sessions found
181
182The ``-w`` option can be used like this to delay the startup of the jobs.
183
184.. code-block:: console
185
186   uart:~$ zperf tcp upload -a -t 6 -w 192.0.2.2 5001 10 1K
187   Remote port is 5001
188   Connecting to 192.0.2.2
189   Duration:       10.00 s
190   Packet size:    1000 bytes
191   Rate:           10 kbps
192   Waiting "zperf jobs start" command.
193   [01:06:51.392,288] <inf> net_zperf: [0] TCP waiting for start
194
195   uart:~$ zperf udp upload -a -t 6 -w 192.0.2.2 5001 10 1K 10M
196   Remote port is 5001
197   Connecting to 192.0.2.2
198   Duration:       10.00 s
199   Packet size:    1000 bytes
200   Rate:           10000 kbps
201   Waiting "zperf jobs start" command.
202   Rate:           10.00 Mbps
203   Packet duration 781 us
204   [01:06:58.064,552] <inf> net_zperf: [0] UDP waiting for start
205
206   uart:~$ zperf jobs start
207   -
208   Upload completed!
209   -
210   Upload completed!
211
212   # Note that the output may be garbled as two threads printed
213   # output at the same time. Just print out the fresh listing
214   # like this.
215
216   uart:~$ zperf jobs all
217   -
218   Upload completed!
219   Statistics:             server  (client)
220   Duration:               9.99 s  (10.00 s)
221   Num packets:            11429   (11429)
222   Num packets out order:  0
223   Num packets lost:       0
224   Jitter:                 164 us
225   Rate:                   9.14 Mbps       (9.14 Mbps)
226   Thread priority:        6
227   Protocol:               UDP
228   Session id:             0
229   -
230   Upload completed!
231   Duration:               10.00 s
232   Num packets:            15487
233   Num errors:             0 (retry or fail)
234   Rate:                   12.38 Mbps
235   Thread priority:        6
236   Protocol:               TCP
237   Session id:             0
238   Total 2 sessions done
239
240Custom Data Upload
241******************
242
243zperf supports more advanced data upload profiling by setting a custom data
244source through :c:member:`zperf_upload_params.data_loader`. This enables the
245generation of custom packet contents instead of sending a constant packet
246consisting solely of the ``z`` character. An example use case would be
247determining the maximum throughput of uploading data from an external flash
248memory chip.
249