Line data Source code
1 1 : /*
2 : * Copyright (c) 2016 Intel Corporation
3 : * Copyright (c) 2022 Nordic Semiconductor ASA
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file zperf.h
10 : *
11 : * @brief Zperf API
12 : * @defgroup zperf Zperf API
13 : * @since 3.3
14 : * @version 0.8.0
15 : * @ingroup networking
16 : * @{
17 : */
18 :
19 : #ifndef ZEPHYR_INCLUDE_NET_ZPERF_H_
20 : #define ZEPHYR_INCLUDE_NET_ZPERF_H_
21 :
22 : #include <zephyr/net/net_ip.h>
23 : #include <zephyr/net/socket.h>
24 :
25 : #ifdef __cplusplus
26 : extern "C" {
27 : #endif
28 :
29 : /** @cond INTERNAL_HIDDEN */
30 :
31 : enum zperf_status {
32 : ZPERF_SESSION_STARTED,
33 : ZPERF_SESSION_PERIODIC_RESULT,
34 : ZPERF_SESSION_FINISHED,
35 : ZPERF_SESSION_ERROR
36 : } __packed;
37 :
38 : /**
39 : * @brief Zperf callback function to load custom data for upload
40 : *
41 : * @param user_ctx User context for data load
42 : * @param offset Current offset of custom data
43 : * @param data Pointer to load data into
44 : * @param len Length of data to load in bytes
45 : *
46 : * @retval 0 On successful data load
47 : * @retval -errno Data load failed, terminate data upload
48 : */
49 : typedef int (*zperf_data_load_custom)(void *user_ctx, uint64_t offset,
50 : uint8_t *data, uint32_t len);
51 :
52 : struct zperf_upload_params {
53 : uint64_t unix_offset_us;
54 : zperf_data_load_custom data_loader;
55 : void *data_loader_ctx;
56 : struct sockaddr peer_addr;
57 : uint32_t duration_ms;
58 : uint32_t rate_kbps;
59 : uint16_t packet_size;
60 : char if_name[IFNAMSIZ];
61 : struct {
62 : uint8_t tos;
63 : int tcp_nodelay;
64 : int priority;
65 : #ifdef CONFIG_ZPERF_SESSION_PER_THREAD
66 : int thread_priority;
67 : bool wait_for_start;
68 : #endif
69 : uint32_t report_interval_ms;
70 : } options;
71 : };
72 :
73 : struct zperf_download_params {
74 : uint16_t port;
75 : struct sockaddr addr;
76 : char if_name[IFNAMSIZ];
77 : };
78 :
79 : /** @endcond */
80 :
81 : /** Performance results */
82 1 : struct zperf_results {
83 1 : uint32_t nb_packets_sent; /**< Number of packets sent */
84 1 : uint32_t nb_packets_rcvd; /**< Number of packets received */
85 1 : uint32_t nb_packets_lost; /**< Number of packets lost */
86 1 : uint32_t nb_packets_outorder; /**< Number of packets out of order */
87 1 : uint64_t total_len; /**< Total length of the transferred data */
88 1 : uint64_t time_in_us; /**< Total time of the transfer in microseconds */
89 1 : uint32_t jitter_in_us; /**< Jitter in microseconds */
90 1 : uint64_t client_time_in_us; /**< Client connection time in microseconds */
91 1 : uint32_t packet_size; /**< Packet size */
92 1 : uint32_t nb_packets_errors; /**< Number of packet errors */
93 1 : bool is_multicast; /**< True if this session used IP multicast */
94 : };
95 :
96 : /**
97 : * @brief Zperf callback function used for asynchronous operations.
98 : *
99 : * @param status Session status.
100 : * @param result Session results. May be NULL for certain events.
101 : * @param user_data A pointer to the user provided data.
102 : */
103 1 : typedef void (*zperf_callback)(enum zperf_status status,
104 : struct zperf_results *result,
105 : void *user_data);
106 :
107 : /**
108 : * @brief Synchronous UDP upload operation. The function blocks until the upload
109 : * is complete.
110 : *
111 : * @param param Upload parameters.
112 : * @param result Session results.
113 : *
114 : * @return 0 if session completed successfully, a negative error code otherwise.
115 : */
116 1 : int zperf_udp_upload(const struct zperf_upload_params *param,
117 : struct zperf_results *result);
118 :
119 : /**
120 : * @brief Synchronous TCP upload operation. The function blocks until the upload
121 : * is complete.
122 : *
123 : * @param param Upload parameters.
124 : * @param result Session results.
125 : *
126 : * @return 0 if session completed successfully, a negative error code otherwise.
127 : */
128 1 : int zperf_tcp_upload(const struct zperf_upload_params *param,
129 : struct zperf_results *result);
130 :
131 : /**
132 : * @brief Asynchronous UDP upload operation.
133 : *
134 : * @note Only one asynchronous upload can be performed at a time.
135 : *
136 : * @param param Upload parameters.
137 : * @param callback Session results callback.
138 : * @param user_data A pointer to the user data to be provided with the callback.
139 : *
140 : * @return 0 if session was scheduled successfully, a negative error code
141 : * otherwise.
142 : */
143 1 : int zperf_udp_upload_async(const struct zperf_upload_params *param,
144 : zperf_callback callback, void *user_data);
145 :
146 : /**
147 : * @brief Asynchronous TCP upload operation.
148 : *
149 : * @note Only one asynchronous upload can be performed at a time.
150 : *
151 : * @param param Upload parameters.
152 : * @param callback Session results callback.
153 : * @param user_data A pointer to the user data to be provided with the callback.
154 : *
155 : * @return 0 if session was scheduled successfully, a negative error code
156 : * otherwise.
157 : */
158 1 : int zperf_tcp_upload_async(const struct zperf_upload_params *param,
159 : zperf_callback callback, void *user_data);
160 :
161 : /**
162 : * @brief Start UDP server.
163 : *
164 : * @note Only one UDP server instance can run at a time.
165 : *
166 : * @param param Download parameters.
167 : * @param callback Session results callback.
168 : * @param user_data A pointer to the user data to be provided with the callback.
169 : *
170 : * @return 0 if server was started, a negative error code otherwise.
171 : */
172 1 : int zperf_udp_download(const struct zperf_download_params *param,
173 : zperf_callback callback, void *user_data);
174 :
175 : /**
176 : * @brief Start TCP server.
177 : *
178 : * @note Only one TCP server instance can run at a time.
179 : *
180 : * @param param Download parameters.
181 : * @param callback Session results callback.
182 : * @param user_data A pointer to the user data to be provided with the callback.
183 : *
184 : * @return 0 if server was started, a negative error code otherwise.
185 : */
186 1 : int zperf_tcp_download(const struct zperf_download_params *param,
187 : zperf_callback callback, void *user_data);
188 :
189 : /**
190 : * @brief Stop UDP server.
191 : *
192 : * @return 0 if server was stopped successfully, a negative error code otherwise.
193 : */
194 1 : int zperf_udp_download_stop(void);
195 :
196 : /**
197 : * @brief Stop TCP server.
198 : *
199 : * @return 0 if server was stopped successfully, a negative error code otherwise.
200 : */
201 1 : int zperf_tcp_download_stop(void);
202 :
203 : #ifdef __cplusplus
204 : }
205 : #endif
206 :
207 : /**
208 : * @}
209 : */
210 :
211 : #endif /* ZEPHYR_INCLUDE_NET_ZPERF_H_ */
|
