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_branch_prediction.h>
27 #include <rte_common.h>
28 #include <rte_compat.h>
29 #include <rte_cycles.h>
30 #include <rte_per_lcore.h>
31 #include <rte_string_fns.h>
34 /** The tracepoint object. */
35 typedef uint64_t rte_trace_point_t;
37 /** Macro to define the tracepoint. */
38 #define RTE_TRACE_POINT_DEFINE(tp) \
39 rte_trace_point_t __attribute__((section("__rte_trace_point"))) __##tp
42 * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
44 * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
46 #define RTE_TRACE_POINT_ARGS
48 /** @internal Helper macro to support RTE_TRACE_POINT and RTE_TRACE_POINT_FP */
49 #define __RTE_TRACE_POINT(_mode, _tp, _args, ...) \
50 extern rte_trace_point_t __##_tp; \
51 static __rte_always_inline void \
54 __rte_trace_point_emit_header_##_mode(&__##_tp); \
59 * Create a tracepoint.
61 * A tracepoint is defined by specifying:
62 * - its input arguments: they are the C function style parameters to define
63 * the arguments of tracepoint function. These input arguments are embedded
64 * using the RTE_TRACE_POINT_ARGS macro.
65 * - its output event fields: they are the sources of event fields that form
66 * the payload of any event that the execution of the tracepoint macro emits
67 * for this particular tracepoint. The application uses
68 * rte_trace_point_emit_* macros to emit the output event fields.
71 * Tracepoint object. Before using the tracepoint, an application needs to
72 * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
74 * C function style input arguments to define the arguments to tracepoint
77 * Define the payload of trace function. The payload will be formed using
78 * rte_trace_point_emit_* macros. Use ";" delimiter between two payloads.
80 * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_DEFINE, rte_trace_point_emit_*
82 #define RTE_TRACE_POINT(tp, args, ...) \
83 __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
86 * Create a tracepoint for fast path.
88 * Similar to RTE_TRACE_POINT, except that it is removed at compilation time
89 * unless the RTE_ENABLE_TRACE_FP configuration parameter is set.
92 * Tracepoint object. Before using the tracepoint, an application needs to
93 * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
95 * C function style input arguments to define the arguments to tracepoint.
98 * Define the payload of trace function. The payload will be formed using
99 * rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
101 * @see RTE_TRACE_POINT
103 #define RTE_TRACE_POINT_FP(tp, args, ...) \
104 __RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
109 * Register a tracepoint.
112 * The tracepoint object created using RTE_TRACE_POINT_DEFINE.
114 * The name of the tracepoint object.
116 * - 0: Successfully registered the tracepoint.
117 * - <0: Failure to register the tracepoint.
119 #define RTE_TRACE_POINT_REGISTER(trace, name)
121 /** Tracepoint function payload for uint64_t datatype */
122 #define rte_trace_point_emit_u64(val)
123 /** Tracepoint function payload for int64_t datatype */
124 #define rte_trace_point_emit_i64(val)
125 /** Tracepoint function payload for uint32_t datatype */
126 #define rte_trace_point_emit_u32(val)
127 /** Tracepoint function payload for int32_t datatype */
128 #define rte_trace_point_emit_i32(val)
129 /** Tracepoint function payload for uint16_t datatype */
130 #define rte_trace_point_emit_u16(val)
131 /** Tracepoint function payload for int16_t datatype */
132 #define rte_trace_point_emit_i16(val)
133 /** Tracepoint function payload for uint8_t datatype */
134 #define rte_trace_point_emit_u8(val)
135 /** Tracepoint function payload for int8_t datatype */
136 #define rte_trace_point_emit_i8(val)
137 /** Tracepoint function payload for int datatype */
138 #define rte_trace_point_emit_int(val)
139 /** Tracepoint function payload for long datatype */
140 #define rte_trace_point_emit_long(val)
141 /** Tracepoint function payload for float datatype */
142 #define rte_trace_point_emit_float(val)
143 /** Tracepoint function payload for double datatype */
144 #define rte_trace_point_emit_double(val)
145 /** Tracepoint function payload for pointer datatype */
146 #define rte_trace_point_emit_ptr(val)
147 /** Tracepoint function payload for string datatype */
148 #define rte_trace_point_emit_string(val)
150 #endif /* __DOXYGEN__ */
152 /** @internal Macro to define maximum emit length of string datatype. */
153 #define __RTE_TRACE_EMIT_STRING_LEN_MAX 32
154 /** @internal Macro to define event header size. */
155 #define __RTE_TRACE_EVENT_HEADER_SZ sizeof(uint64_t)
158 * Enable recording events of the given tracepoint in the trace buffer.
161 * The tracepoint object to enable.
164 * - (-ERANGE): Trace object is not registered.
167 int rte_trace_point_enable(rte_trace_point_t *tp);
170 * Disable recording events of the given tracepoint in the trace buffer.
173 * The tracepoint object to disable.
176 * - (-ERANGE): Trace object is not registered.
179 int rte_trace_point_disable(rte_trace_point_t *tp);
182 * Test if recording events from the given tracepoint is enabled.
185 * The tracepoint object.
187 * true if tracepoint is enabled, false otherwise.
190 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
193 * Lookup a tracepoint object from its name.
196 * The name of the tracepoint.
198 * The tracepoint object or NULL if not found.
201 rte_trace_point_t *rte_trace_point_lookup(const char *name);
206 * Test if the tracepoint fast path compile-time option is enabled.
209 * true if tracepoint fast path enabled, false otherwise.
212 static __rte_always_inline bool
213 __rte_trace_point_fp_is_enabled(void)
215 #ifdef RTE_ENABLE_TRACE_FP
225 * Allocate trace memory buffer per thread.
229 void __rte_trace_mem_per_thread_alloc(void);
234 * Helper function to emit field.
237 * The tracepoint size.
239 * The name of the trace event.
241 * The datatype of the trace event as string.
247 void __rte_trace_point_emit_field(size_t sz, const char *field,
253 * Helper function to register a dynamic tracepoint.
254 * Use RTE_TRACE_POINT_REGISTER macro for tracepoint registration.
257 * The tracepoint object created using RTE_TRACE_POINT_DEFINE.
259 * The name of the tracepoint object.
261 * Trace registration function.
263 * - 0: Successfully registered the tracepoint.
264 * - <0: Failure to register the tracepoint.
267 int __rte_trace_point_register(rte_trace_point_t *trace, const char *name,
268 void (*register_fn)(void));
272 #ifndef _RTE_TRACE_POINT_REGISTER_H_
273 #ifdef ALLOW_EXPERIMENTAL_API
275 #define __RTE_TRACE_EVENT_HEADER_ID_SHIFT (48)
277 #define __RTE_TRACE_FIELD_SIZE_SHIFT 0
278 #define __RTE_TRACE_FIELD_SIZE_MASK (0xffffULL << __RTE_TRACE_FIELD_SIZE_SHIFT)
279 #define __RTE_TRACE_FIELD_ID_SHIFT (16)
280 #define __RTE_TRACE_FIELD_ID_MASK (0xffffULL << __RTE_TRACE_FIELD_ID_SHIFT)
281 #define __RTE_TRACE_FIELD_ENABLE_MASK (1ULL << 63)
282 #define __RTE_TRACE_FIELD_ENABLE_DISCARD (1ULL << 62)
284 struct __rte_trace_stream_header {
288 char thread_name[__RTE_TRACE_EMIT_STRING_LEN_MAX];
291 struct __rte_trace_header {
294 struct __rte_trace_stream_header stream_header;
298 RTE_DECLARE_PER_LCORE(void *, trace_mem);
300 static __rte_always_inline void *
301 __rte_trace_mem_get(uint64_t in)
303 struct __rte_trace_header *trace = RTE_PER_LCORE(trace_mem);
304 const uint16_t sz = in & __RTE_TRACE_FIELD_SIZE_MASK;
306 /* Trace memory is not initialized for this thread */
307 if (unlikely(trace == NULL)) {
308 __rte_trace_mem_per_thread_alloc();
309 trace = RTE_PER_LCORE(trace_mem);
310 if (unlikely(trace == NULL))
313 /* Check the wrap around case */
314 uint32_t offset = trace->offset;
315 if (unlikely((offset + sz) >= trace->len)) {
316 /* Disable the trace event if it in DISCARD mode */
317 if (unlikely(in & __RTE_TRACE_FIELD_ENABLE_DISCARD))
322 /* Align to event header size */
323 offset = RTE_ALIGN_CEIL(offset, __RTE_TRACE_EVENT_HEADER_SZ);
324 void *mem = RTE_PTR_ADD(&trace->mem[0], offset);
326 trace->offset = offset;
331 static __rte_always_inline void *
332 __rte_trace_point_emit_ev_header(void *mem, uint64_t in)
336 /* Event header [63:0] = id [63:48] | timestamp [47:0] */
337 val = rte_get_tsc_cycles() &
338 ~(0xffffULL << __RTE_TRACE_EVENT_HEADER_ID_SHIFT);
339 val |= ((in & __RTE_TRACE_FIELD_ID_MASK) <<
340 (__RTE_TRACE_EVENT_HEADER_ID_SHIFT -
341 __RTE_TRACE_FIELD_ID_SHIFT));
343 *(uint64_t *)mem = val;
344 return RTE_PTR_ADD(mem, __RTE_TRACE_EVENT_HEADER_SZ);
347 #define __rte_trace_point_emit_header_generic(t) \
350 const uint64_t val = __atomic_load_n(t, __ATOMIC_ACQUIRE); \
351 if (likely(!(val & __RTE_TRACE_FIELD_ENABLE_MASK))) \
353 mem = __rte_trace_mem_get(val); \
354 if (unlikely(mem == NULL)) \
356 mem = __rte_trace_point_emit_ev_header(mem, val); \
359 #define __rte_trace_point_emit_header_fp(t) \
360 if (!__rte_trace_point_fp_is_enabled()) \
362 __rte_trace_point_emit_header_generic(t)
364 #define __rte_trace_point_emit(in, type) \
366 memcpy(mem, &(in), sizeof(in)); \
367 mem = RTE_PTR_ADD(mem, sizeof(in)); \
370 #define rte_trace_point_emit_string(in) \
372 if (unlikely(in == NULL)) \
374 rte_strscpy(mem, in, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
375 mem = RTE_PTR_ADD(mem, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
380 #define __rte_trace_point_emit_header_generic(t) RTE_SET_USED(t)
381 #define __rte_trace_point_emit_header_fp(t) RTE_SET_USED(t)
382 #define __rte_trace_point_emit(in, type) RTE_SET_USED(in)
383 #define rte_trace_point_emit_string(in) RTE_SET_USED(in)
385 #endif /* ALLOW_EXPERIMENTAL_API */
386 #endif /* _RTE_TRACE_POINT_REGISTER_H_ */
388 #define rte_trace_point_emit_u64(in) __rte_trace_point_emit(in, uint64_t)
389 #define rte_trace_point_emit_i64(in) __rte_trace_point_emit(in, int64_t)
390 #define rte_trace_point_emit_u32(in) __rte_trace_point_emit(in, uint32_t)
391 #define rte_trace_point_emit_i32(in) __rte_trace_point_emit(in, int32_t)
392 #define rte_trace_point_emit_u16(in) __rte_trace_point_emit(in, uint16_t)
393 #define rte_trace_point_emit_i16(in) __rte_trace_point_emit(in, int16_t)
394 #define rte_trace_point_emit_u8(in) __rte_trace_point_emit(in, uint8_t)
395 #define rte_trace_point_emit_i8(in) __rte_trace_point_emit(in, int8_t)
396 #define rte_trace_point_emit_int(in) __rte_trace_point_emit(in, int32_t)
397 #define rte_trace_point_emit_long(in) __rte_trace_point_emit(in, long)
398 #define rte_trace_point_emit_float(in) __rte_trace_point_emit(in, float)
399 #define rte_trace_point_emit_double(in) __rte_trace_point_emit(in, double)
400 #define rte_trace_point_emit_ptr(in) __rte_trace_point_emit(in, uintptr_t)
402 #endif /* __DOXYGEN__ */
408 #endif /* _RTE_TRACE_POINT_H_ */