de99e83163dc2a146c93a3ab91c3b87d5aefd548
[dpdk.git] / lib / librte_telemetry / rte_telemetry.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2018 Intel Corporation
3  */
4
5 #include <stdint.h>
6 #include <rte_compat.h>
7
8 #ifndef _RTE_TELEMETRY_H_
9 #define _RTE_TELEMETRY_H_
10
11 /** Maximum number of telemetry callbacks. */
12 #define TELEMETRY_MAX_CALLBACKS 64
13 /** Maximum length for string used in object. */
14 #define RTE_TEL_MAX_STRING_LEN 64
15 /** Maximum length of string. */
16 #define RTE_TEL_MAX_SINGLE_STRING_LEN 8192
17 /** Maximum number of dictionary entries. */
18 #define RTE_TEL_MAX_DICT_ENTRIES 256
19 /** Maximum number of array entries. */
20 #define RTE_TEL_MAX_ARRAY_ENTRIES 512
21
22 /**
23  * @warning
24  * @b EXPERIMENTAL: all functions in this file may change without prior notice
25  *
26  * @file
27  * RTE Telemetry
28  *
29  * The telemetry library provides a method to retrieve statistics from
30  * DPDK by sending a request message over a socket. DPDK will send
31  * a JSON encoded response containing telemetry data.
32  ***/
33
34 /** opaque structure used internally for managing data from callbacks */
35 struct rte_tel_data;
36
37 /**
38  * The types of data that can be managed in arrays or dicts.
39  * For arrays, this must be specified at creation time, while for
40  * dicts this is specified implicitly each time an element is added
41  * via calling a type-specific function.
42  */
43 enum rte_tel_value_type {
44         RTE_TEL_STRING_VAL, /** a string value */
45         RTE_TEL_INT_VAL,    /** a signed 32-bit int value */
46         RTE_TEL_U64_VAL,    /** an unsigned 64-bit int value */
47 };
48
49 /**
50  * Start an array of the specified type for returning from a callback
51  *
52  * @param d
53  *   The data structure passed to the callback
54  * @param type
55  *   The type of the array of data
56  * @return
57  *   0 on success, negative errno on error
58  */
59 __rte_experimental
60 int
61 rte_tel_data_start_array(struct rte_tel_data *d, enum rte_tel_value_type type);
62
63 /**
64  * Start a dictionary of values for returning from a callback
65  *
66  * @param d
67  *   The data structure passed to the callback
68  * @return
69  *   0 on success, negative errno on error
70  */
71 __rte_experimental
72 int
73 rte_tel_data_start_dict(struct rte_tel_data *d);
74
75 /**
76  * Set a string for returning from a callback
77  *
78  * @param d
79  *   The data structure passed to the callback
80  * @param str
81  *   The string to be returned in the data structure
82  * @return
83  *   0 on success, negative errno on error, E2BIG on string truncation
84  */
85 __rte_experimental
86 int
87 rte_tel_data_string(struct rte_tel_data *d, const char *str);
88
89 /**
90  * Add a string to an array.
91  * The array must have been started by rte_tel_data_start_array() with
92  * RTE_TEL_STRING_VAL as the type parameter.
93  *
94  * @param d
95  *   The data structure passed to the callback
96  * @param str
97  *   The string to be returned in the array
98  * @return
99  *   0 on success, negative errno on error, E2BIG on string truncation
100  */
101 __rte_experimental
102 int
103 rte_tel_data_add_array_string(struct rte_tel_data *d, const char *str);
104
105 /**
106  * Add an int to an array.
107  * The array must have been started by rte_tel_data_start_array() with
108  * RTE_TEL_INT_VAL as the type parameter.
109  *
110  * @param d
111  *   The data structure passed to the callback
112  * @param x
113  *   The number to be returned in the array
114  * @return
115  *   0 on success, negative errno on error
116  */
117 __rte_experimental
118 int
119 rte_tel_data_add_array_int(struct rte_tel_data *d, int x);
120
121 /**
122  * Add a uint64_t to an array.
123  * The array must have been started by rte_tel_data_start_array() with
124  * RTE_TEL_U64_VAL as the type parameter.
125  *
126  * @param d
127  *   The data structure passed to the callback
128  * @param x
129  *   The number to be returned in the array
130  * @return
131  *   0 on success, negative errno on error
132  */
133 __rte_experimental
134 int
135 rte_tel_data_add_array_u64(struct rte_tel_data *d, uint64_t x);
136
137 /**
138  * Add a string value to a dictionary.
139  * The dict must have been started by rte_tel_data_start_dict().
140  *
141  * @param d
142  *   The data structure passed to the callback
143  * @param name
144  *   The name the value is to be stored under in the dict
145  * @param val
146  *   The string to be stored in the dict
147  * @return
148  *   0 on success, negative errno on error, E2BIG on string truncation of
149  *   either name or value.
150  */
151 __rte_experimental
152 int
153 rte_tel_data_add_dict_string(struct rte_tel_data *d, const char *name,
154                 const char *val);
155
156 /**
157  * Add an int value to a dictionary.
158  * The dict must have been started by rte_tel_data_start_dict().
159  *
160  * @param d
161  *   The data structure passed to the callback
162  * @param name
163  *   The name the value is to be stored under in the dict
164  * @param val
165  *   The number to be stored in the dict
166  * @return
167  *   0 on success, negative errno on error, E2BIG on string truncation of name.
168  */
169 __rte_experimental
170 int
171 rte_tel_data_add_dict_int(struct rte_tel_data *d, const char *name, int val);
172
173 /**
174  * Add a uint64_t value to a dictionary.
175  * The dict must have been started by rte_tel_data_start_dict().
176  *
177  * @param d
178  *   The data structure passed to the callback
179  * @param name
180  *   The name the value is to be stored under in the dict
181  * @param val
182  *   The number to be stored in the dict
183  * @return
184  *   0 on success, negative errno on error, E2BIG on string truncation of name.
185  */
186 __rte_experimental
187 int
188 rte_tel_data_add_dict_u64(struct rte_tel_data *d,
189                 const char *name, uint64_t val);
190
191 /**
192  * This telemetry callback is used when registering a telemetry command.
193  * It handles getting and formatting information to be returned to telemetry
194  * when requested.
195  *
196  * @param cmd
197  * The cmd that was requested by the client.
198  * @param params
199  * Contains data required by the callback function.
200  * @param info
201  * The information to be returned to the caller.
202  *
203  * @return
204  * Length of buffer used on success.
205  * @return
206  * Negative integer on error.
207  */
208 typedef int (*telemetry_cb)(const char *cmd, const char *params,
209                 struct rte_tel_data *info);
210
211 /**
212  * Used for handling data received over a telemetry socket.
213  *
214  * @param sock_id
215  * ID for the socket to be used by the handler.
216  *
217  * @return
218  * Void.
219  */
220 typedef void * (*handler)(void *sock_id);
221
222 /**
223  * Used when registering a command and callback function with telemetry.
224  *
225  * @param cmd
226  * The command to register with telemetry.
227  * @param fn
228  * Callback function to be called when the command is requested.
229  * @param help
230  * Help text for the command.
231  *
232  * @return
233  *  0 on success.
234  * @return
235  *  -EINVAL for invalid parameters failure.
236  *  @return
237  *  -ENOENT if max callbacks limit has been reached.
238  */
239 __rte_experimental
240 int
241 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
242
243 /**
244  * Initialize Telemetry.
245  *
246  * @return
247  *  0 on success.
248  * @return
249  *  -1 on failure.
250  */
251 __rte_experimental
252 int
253 rte_telemetry_init(void);
254 #endif