66290a3fdf579e852f0eb58326384de5f7626a7a
[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  * This telemetry callback is used when registering a telemetry command.
51  * It handles getting and formatting information to be returned to telemetry
52  * when requested.
53  *
54  * @param cmd
55  * The cmd that was requested by the client.
56  * @param params
57  * Contains data required by the callback function.
58  * @param info
59  * The information to be returned to the caller.
60  *
61  * @return
62  * Length of buffer used on success.
63  * @return
64  * Negative integer on error.
65  */
66 typedef int (*telemetry_cb)(const char *cmd, const char *params,
67                 struct rte_tel_data *info);
68
69 /**
70  * Used for handling data received over a telemetry socket.
71  *
72  * @param sock_id
73  * ID for the socket to be used by the handler.
74  *
75  * @return
76  * Void.
77  */
78 typedef void * (*handler)(void *sock_id);
79
80 /**
81  * @warning
82  * @b EXPERIMENTAL: this API may change without prior notice
83  *
84  * Initialize Telemetry
85  *
86  * @return
87  *  0 on successful initialisation.
88  * @return
89  *  -ENOMEM on memory allocation error
90  * @return
91  *  -EPERM on unknown error failure
92  * @return
93  *  -EALREADY if Telemetry is already initialised.
94  */
95 __rte_experimental
96 int32_t
97 rte_telemetry_init(void);
98
99 /**
100  * @warning
101  * @b EXPERIMENTAL: this API may change without prior notice
102  *
103  * Clean up and free memory.
104  *
105  * @return
106  *  0 on success
107  * @return
108  *  -EPERM on failure
109  */
110 __rte_experimental
111 int32_t
112 rte_telemetry_cleanup(void);
113
114 /**
115  * @warning
116  * @b EXPERIMENTAL: this API may change without prior notice
117  *
118  * Runs various tests to ensure telemetry initialisation and register/unregister
119  * functions are working correctly.
120  *
121  * @return
122  *  0 on success when all tests have passed
123  * @return
124  *  -1 on failure when the test has failed
125  */
126 __rte_experimental
127 int32_t
128 rte_telemetry_selftest(void);
129
130 /**
131  * Used when registering a command and callback function with telemetry.
132  *
133  * @param cmd
134  * The command to register with telemetry.
135  * @param fn
136  * Callback function to be called when the command is requested.
137  * @param help
138  * Help text for the command.
139  *
140  * @return
141  *  0 on success.
142  * @return
143  *  -EINVAL for invalid parameters failure.
144  *  @return
145  *  -ENOENT if max callbacks limit has been reached.
146  */
147 __rte_experimental
148 int
149 rte_telemetry_register_cmd(const char *cmd, telemetry_cb fn, const char *help);
150
151 /**
152  * Initialize new version of Telemetry.
153  *
154  * @return
155  *  0 on success.
156  * @return
157  *  -1 on failure.
158  */
159 __rte_experimental
160 int
161 rte_telemetry_new_init(void);
162 #endif