1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(C) 2020 Marvell International Ltd.
5 #ifndef _RTE_TRACE_POINT_H_
6 #define _RTE_TRACE_POINT_H_
13 * This file provides the tracepoint API to RTE applications.
16 * @b EXPERIMENTAL: this API may change without prior notice
26 #include <rte_common.h>
27 #include <rte_compat.h>
29 /** The tracepoint object. */
30 typedef uint64_t rte_trace_point_t;
32 /** Macro to define the tracepoint. */
33 #define RTE_TRACE_POINT_DEFINE(tp) \
34 rte_trace_point_t __attribute__((section("__rte_trace_point"))) __##tp
37 * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
39 * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
41 #define RTE_TRACE_POINT_ARGS
43 /** @internal Helper macro to support RTE_TRACE_POINT and RTE_TRACE_POINT_FP */
44 #define __RTE_TRACE_POINT(_mode, _tp, _args, ...) \
45 extern rte_trace_point_t __##_tp; \
46 static __rte_always_inline void \
49 __rte_trace_point_emit_header_##_mode(&__##_tp); \
54 * Create a tracepoint.
56 * A tracepoint is defined by specifying:
57 * - its input arguments: they are the C function style parameters to define
58 * the arguments of tracepoint function. These input arguments are embedded
59 * using the RTE_TRACE_POINT_ARGS macro.
60 * - its output event fields: they are the sources of event fields that form
61 * the payload of any event that the execution of the tracepoint macro emits
62 * for this particular tracepoint. The application uses
63 * rte_trace_point_emit_* macros to emit the output event fields.
66 * Tracepoint object. Before using the tracepoint, an application needs to
67 * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
69 * C function style input arguments to define the arguments to tracepoint
72 * Define the payload of trace function. The payload will be formed using
73 * rte_trace_point_emit_* macros. Use ";" delimiter between two payloads.
75 * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_DEFINE, rte_trace_point_emit_*
77 #define RTE_TRACE_POINT(tp, args, ...) \
78 __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
81 * Create a tracepoint for fast path.
83 * Similar to RTE_TRACE_POINT, except that it is removed at compilation time
84 * unless the RTE_ENABLE_TRACE_FP configuration parameter is set.
87 * Tracepoint object. Before using the tracepoint, an application needs to
88 * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
90 * C function style input arguments to define the arguments to tracepoint.
93 * Define the payload of trace function. The payload will be formed using
94 * rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
96 * @see RTE_TRACE_POINT
98 #define RTE_TRACE_POINT_FP(tp, args, ...) \
99 __RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
104 * Macro to select rte_trace_point_emit_* definition for trace register function
106 * rte_trace_point_emit_* emits different definitions for trace function.
107 * Application must define RTE_TRACE_POINT_REGISTER_SELECT before including
108 * rte_trace_point.h in the C file where RTE_TRACE_POINT_REGISTER used.
110 * @see RTE_TRACE_POINT_REGISTER
112 #define RTE_TRACE_POINT_REGISTER_SELECT
115 * Register a tracepoint.
118 * The tracepoint object created using RTE_TRACE_POINT_DEFINE.
120 * The name of the tracepoint object.
122 * - 0: Successfully registered the tracepoint.
123 * - <0: Failure to register the tracepoint.
125 * @see RTE_TRACE_POINT_REGISTER_SELECT
127 #define RTE_TRACE_POINT_REGISTER(trace, name)
129 /** Tracepoint function payload for uint64_t datatype */
130 #define rte_trace_point_emit_u64(val)
131 /** Tracepoint function payload for int64_t datatype */
132 #define rte_trace_point_emit_i64(val)
133 /** Tracepoint function payload for uint32_t datatype */
134 #define rte_trace_point_emit_u32(val)
135 /** Tracepoint function payload for int32_t datatype */
136 #define rte_trace_point_emit_i32(val)
137 /** Tracepoint function payload for uint16_t datatype */
138 #define rte_trace_point_emit_u16(val)
139 /** Tracepoint function payload for int16_t datatype */
140 #define rte_trace_point_emit_i16(val)
141 /** Tracepoint function payload for uint8_t datatype */
142 #define rte_trace_point_emit_u8(val)
143 /** Tracepoint function payload for int8_t datatype */
144 #define rte_trace_point_emit_i8(val)
145 /** Tracepoint function payload for int datatype */
146 #define rte_trace_point_emit_int(val)
147 /** Tracepoint function payload for long datatype */
148 #define rte_trace_point_emit_long(val)
149 /** Tracepoint function payload for float datatype */
150 #define rte_trace_point_emit_float(val)
151 /** Tracepoint function payload for double datatype */
152 #define rte_trace_point_emit_double(val)
153 /** Tracepoint function payload for pointer datatype */
154 #define rte_trace_point_emit_ptr(val)
155 /** Tracepoint function payload for string datatype */
156 #define rte_trace_point_emit_string(val)
158 #endif /* __DOXYGEN__ */
160 /** @internal Macro to define maximum emit length of string datatype. */
161 #define __RTE_TRACE_EMIT_STRING_LEN_MAX 32
162 /** @internal Macro to define event header size. */
163 #define __RTE_TRACE_EVENT_HEADER_SZ sizeof(uint64_t)
166 * Enable recording events of the given tracepoint in the trace buffer.
169 * The tracepoint object to enable.
172 * - (-ERANGE): Trace object is not registered.
175 int rte_trace_point_enable(rte_trace_point_t *tp);
178 * Disable recording events of the given tracepoint in the trace buffer.
181 * The tracepoint object to disable.
184 * - (-ERANGE): Trace object is not registered.
187 int rte_trace_point_disable(rte_trace_point_t *tp);
190 * Test if recording events from the given tracepoint is enabled.
193 * The tracepoint object.
195 * true if tracepoint is enabled, false otherwise.
198 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
201 * Lookup a tracepoint object from its name.
204 * The name of the tracepoint.
206 * The tracepoint object or NULL if not found.
209 rte_trace_point_t *rte_trace_point_lookup(const char *name);
214 * Test if the tracepoint fast path compile-time option is enabled.
217 * true if tracepoint fast path enabled, false otherwise.
220 static __rte_always_inline bool
221 __rte_trace_point_fp_is_enabled(void)
223 #ifdef RTE_ENABLE_TRACE_FP
233 * Allocate trace memory buffer per thread.
237 void __rte_trace_mem_per_thread_alloc(void);
242 * Helper function to emit field.
245 * The tracepoint size.
247 * The name of the trace event.
249 * The datatype of the trace event as string.
255 void __rte_trace_point_emit_field(size_t sz, const char *field,
261 * Helper function to register a dynamic tracepoint.
262 * Use RTE_TRACE_POINT_REGISTER macro for tracepoint registration.
265 * The tracepoint object created using RTE_TRACE_POINT_DEFINE.
267 * The name of the tracepoint object.
269 * Trace registration function.
271 * - 0: Successfully registered the tracepoint.
272 * - <0: Failure to register the tracepoint.
275 int __rte_trace_point_register(rte_trace_point_t *trace, const char *name,
276 void (*register_fn)(void));
278 #ifdef RTE_TRACE_POINT_REGISTER_SELECT
279 #include <rte_trace_point_register.h>
281 #include <rte_trace_point_provider.h>
288 #endif /* _RTE_TRACE_POINT_H_ */