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 struct zperf_upload_params {
39 	struct sockaddr peer_addr;
40 	uint32_t duration_ms;
41 	uint32_t rate_kbps;
42 	uint16_t packet_size;
43 	char if_name[IFNAMSIZ];
44 	struct {
45 		uint8_t tos;
46 		int tcp_nodelay;
47 		int priority;
48 		uint32_t report_interval_ms;
49 	} options;
50 };
51 
52 struct zperf_download_params {
53 	uint16_t port;
54 	struct sockaddr addr;
55 	char if_name[IFNAMSIZ];
56 };
57 
58 /** @endcond */
59 
60 /** Performance results */
61 struct zperf_results {
62 	uint32_t nb_packets_sent;     /**< Number of packets sent */
63 	uint32_t nb_packets_rcvd;     /**< Number of packets received */
64 	uint32_t nb_packets_lost;     /**< Number of packets lost */
65 	uint32_t nb_packets_outorder; /**< Number of packets out of order */
66 	uint64_t total_len;           /**< Total length of the transferred data */
67 	uint64_t time_in_us;          /**< Total time of the transfer in microseconds */
68 	uint32_t jitter_in_us;        /**< Jitter in microseconds */
69 	uint64_t client_time_in_us;   /**< Client connection time in microseconds */
70 	uint32_t packet_size;         /**< Packet size */
71 	uint32_t nb_packets_errors;   /**< Number of packet errors */
72 };
73 
74 /**
75  * @brief Zperf callback function used for asynchronous operations.
76  *
77  * @param status Session status.
78  * @param result Session results. May be NULL for certain events.
79  * @param user_data A pointer to the user provided data.
80  */
81 typedef void (*zperf_callback)(enum zperf_status status,
82 			       struct zperf_results *result,
83 			       void *user_data);
84 
85 /**
86  * @brief Synchronous UDP upload operation. The function blocks until the upload
87  *        is complete.
88  *
89  * @param param Upload parameters.
90  * @param result Session results.
91  *
92  * @return 0 if session completed successfully, a negative error code otherwise.
93  */
94 int zperf_udp_upload(const struct zperf_upload_params *param,
95 		     struct zperf_results *result);
96 
97 /**
98  * @brief Synchronous TCP upload operation. The function blocks until the upload
99  *        is complete.
100  *
101  * @param param Upload parameters.
102  * @param result Session results.
103  *
104  * @return 0 if session completed successfully, a negative error code otherwise.
105  */
106 int zperf_tcp_upload(const struct zperf_upload_params *param,
107 		     struct zperf_results *result);
108 
109 /**
110  * @brief Asynchronous UDP upload operation.
111  *
112  * @note Only one asynchronous upload can be performed at a time.
113  *
114  * @param param Upload parameters.
115  * @param callback Session results callback.
116  * @param user_data A pointer to the user data to be provided with the callback.
117  *
118  * @return 0 if session was scheduled successfully, a negative error code
119  *         otherwise.
120  */
121 int zperf_udp_upload_async(const struct zperf_upload_params *param,
122 			   zperf_callback callback, void *user_data);
123 
124 /**
125  * @brief Asynchronous TCP upload operation.
126  *
127  * @note Only one asynchronous upload can be performed at a time.
128  *
129  * @param param Upload parameters.
130  * @param callback Session results callback.
131  * @param user_data A pointer to the user data to be provided with the callback.
132  *
133  * @return 0 if session was scheduled successfully, a negative error code
134  *         otherwise.
135  */
136 int zperf_tcp_upload_async(const struct zperf_upload_params *param,
137 			   zperf_callback callback, void *user_data);
138 
139 /**
140  * @brief Start UDP server.
141  *
142  * @note Only one UDP server instance can run at a time.
143  *
144  * @param param Download parameters.
145  * @param callback Session results callback.
146  * @param user_data A pointer to the user data to be provided with the callback.
147  *
148  * @return 0 if server was started, a negative error code otherwise.
149  */
150 int zperf_udp_download(const struct zperf_download_params *param,
151 		       zperf_callback callback, void *user_data);
152 
153 /**
154  * @brief Start TCP server.
155  *
156  * @note Only one TCP server instance can run at a time.
157  *
158  * @param param Download parameters.
159  * @param callback Session results callback.
160  * @param user_data A pointer to the user data to be provided with the callback.
161  *
162  * @return 0 if server was started, a negative error code otherwise.
163  */
164 int zperf_tcp_download(const struct zperf_download_params *param,
165 		       zperf_callback callback, void *user_data);
166 
167 /**
168  * @brief Stop UDP server.
169  *
170  * @return 0 if server was stopped successfully, a negative error code otherwise.
171  */
172 int zperf_udp_download_stop(void);
173 
174 /**
175  * @brief Stop TCP server.
176  *
177  * @return 0 if server was stopped successfully, a negative error code otherwise.
178  */
179 int zperf_tcp_download_stop(void);
180 
181 #ifdef __cplusplus
182 }
183 #endif
184 
185 /**
186  * @}
187  */
188 
189 #endif /* ZEPHYR_INCLUDE_NET_ZPERF_H_ */
190