devtools: standardize script arguments
[dpdk.git] / lib / librte_latencystats / rte_latencystats.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2017 Intel Corporation
3  */
4
5 #ifndef _RTE_LATENCYSTATS_H_
6 #define _RTE_LATENCYSTATS_H_
7
8 /**
9  * @file
10  * RTE latency stats
11  *
12  * library to provide application and flow based latency stats.
13  */
14
15 #include <stdint.h>
16 #include <rte_metrics.h>
17 #include <rte_mbuf.h>
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /**
24  *  Note: This function pointer is for future flow based latency stats
25  *  implementation.
26  *
27  * Function type used for identifying flow types of a Rx packet.
28  *
29  * The callback function is called on Rx for each packet.
30  * This function is used for flow based latency calculations.
31  *
32  * @param pkt
33  *   Packet that has to be identified with its flow types.
34  * @param user_param
35  *   The arbitrary user parameter passed in by the application when
36  *   the callback was originally configured.
37  * @return
38  *   The flow_mask, representing the multiple flow types of a packet.
39  */
40 typedef uint16_t (*rte_latency_stats_flow_type_fn)(struct rte_mbuf *pkt,
41                                                         void *user_param);
42
43 /**
44  *  Registers Rx/Tx callbacks for each active port, queue.
45  *
46  * @param samp_intvl
47  *  Sampling time period in nano seconds, at which packet
48  *  should be marked with time stamp.
49  * @param user_cb
50  *  Note: This param is for future flow based latency stats
51  *  implementation.
52  *  User callback to be called to get flow types of a packet.
53  *  Used for flow based latency calculation.
54  *  If the value is NULL, global stats will be calculated,
55  *  else flow based latency stats will be calculated.
56  *  For now just pass on the NULL value to this param.
57  *  @return
58  *   -1     : On error
59  *   -ENOMEM: On error
60  *    0     : On success
61  */
62 int rte_latencystats_init(uint64_t samp_intvl,
63                         rte_latency_stats_flow_type_fn user_cb);
64
65 /**
66  * Calculates the latency and jitter values internally, exposing the updated
67  * values via *rte_latencystats_get* or the rte_metrics API.
68  * @return:
69  *  0      : on Success
70  *  < 0    : Error in updating values.
71  */
72 int32_t rte_latencystats_update(void);
73
74 /**
75  *  Removes registered Rx/Tx callbacks for each active port, queue.
76  *
77  *  @return
78  *   -1: On error
79  *    0: On success
80  */
81 int rte_latencystats_uninit(void);
82
83 /**
84  * Retrieve names of latency statistics
85  *
86  * @param names
87  *  Block of memory to insert names into. Must be at least size in capacity.
88  *  If set to NULL, function returns required capacity.
89  * @param size
90  *  Capacity of latency stats names (number of names).
91  * @return
92  *   - positive value lower or equal to size: success. The return value
93  *     is the number of entries filled in the stats table.
94  *   - positive value higher than size: error, the given statistics table
95  *     is too small. The return value corresponds to the size that should
96  *     be given to succeed. The entries in the table are not valid and
97  *     shall not be used by the caller.
98  */
99 int rte_latencystats_get_names(struct rte_metric_name *names,
100                                 uint16_t size);
101
102 /**
103  * Retrieve latency statistics.
104  *
105  * @param values
106  *   A pointer to a table of structure of type *rte_metric_value*
107  *   to be filled with latency statistics ids and values.
108  *   This parameter can be set to NULL if size is 0.
109  * @param size
110  *   The size of the stats table, which should be large enough to store
111  *   all the latency stats.
112  * @return
113  *   - positive value lower or equal to size: success. The return value
114  *     is the number of entries filled in the stats table.
115  *   - positive value higher than size: error, the given statistics table
116  *     is too small. The return value corresponds to the size that should
117  *     be given to succeed. The entries in the table are not valid and
118  *     shall not be used by the caller.
119  *   -ENOMEM: On failure.
120  */
121 int rte_latencystats_get(struct rte_metric_value *values,
122                         uint16_t size);
123
124 #ifdef __cplusplus
125 }
126 #endif
127
128 #endif /* _RTE_LATENCYSTATS_H_ */