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 size_t datatype */
142 #define rte_trace_point_emit_size_t(val)
143 /** Tracepoint function payload for float datatype */
144 #define rte_trace_point_emit_float(val)
145 /** Tracepoint function payload for double datatype */
146 #define rte_trace_point_emit_double(val)
147 /** Tracepoint function payload for pointer datatype */
148 #define rte_trace_point_emit_ptr(val)
149 /** Tracepoint function payload for string datatype */
150 #define rte_trace_point_emit_string(val)
152 #endif /* __DOXYGEN__ */
154 /** @internal Macro to define maximum emit length of string datatype. */
155 #define __RTE_TRACE_EMIT_STRING_LEN_MAX 32
156 /** @internal Macro to define event header size. */
157 #define __RTE_TRACE_EVENT_HEADER_SZ sizeof(uint64_t)
160 * Enable recording events of the given tracepoint in the trace buffer.
163 * The tracepoint object to enable.
166 * - (-ERANGE): Trace object is not registered.
169 int rte_trace_point_enable(rte_trace_point_t *tp);
172 * Disable recording events of the given tracepoint in the trace buffer.
175 * The tracepoint object to disable.
178 * - (-ERANGE): Trace object is not registered.
181 int rte_trace_point_disable(rte_trace_point_t *tp);
184 * Test if recording events from the given tracepoint is enabled.
187 * The tracepoint object.
189 * true if tracepoint is enabled, false otherwise.
192 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
195 * Lookup a tracepoint object from its name.
198 * The name of the tracepoint.
200 * The tracepoint object or NULL if not found.
203 rte_trace_point_t *rte_trace_point_lookup(const char *name);
208 * Test if the tracepoint fast path compile-time option is enabled.
211 * true if tracepoint fast path enabled, false otherwise.
214 static __rte_always_inline bool
215 __rte_trace_point_fp_is_enabled(void)
217 #ifdef RTE_ENABLE_TRACE_FP
227 * Allocate trace memory buffer per thread.
231 void __rte_trace_mem_per_thread_alloc(void);
236 * Helper function to emit field.
239 * The tracepoint size.
241 * The name of the trace event.
243 * The datatype of the trace event as string.
249 void __rte_trace_point_emit_field(size_t sz, const char *field,
255 * Helper function to register a dynamic tracepoint.
256 * Use RTE_TRACE_POINT_REGISTER macro for tracepoint registration.
259 * The tracepoint object created using RTE_TRACE_POINT_DEFINE.
261 * The name of the tracepoint object.
263 * Trace registration function.
265 * - 0: Successfully registered the tracepoint.
266 * - <0: Failure to register the tracepoint.
269 int __rte_trace_point_register(rte_trace_point_t *trace, const char *name,
270 void (*register_fn)(void));
274 #ifndef _RTE_TRACE_POINT_REGISTER_H_
275 #ifdef ALLOW_EXPERIMENTAL_API
277 #define __RTE_TRACE_EVENT_HEADER_ID_SHIFT (48)
279 #define __RTE_TRACE_FIELD_SIZE_SHIFT 0
280 #define __RTE_TRACE_FIELD_SIZE_MASK (0xffffULL << __RTE_TRACE_FIELD_SIZE_SHIFT)
281 #define __RTE_TRACE_FIELD_ID_SHIFT (16)
282 #define __RTE_TRACE_FIELD_ID_MASK (0xffffULL << __RTE_TRACE_FIELD_ID_SHIFT)
283 #define __RTE_TRACE_FIELD_ENABLE_MASK (1ULL << 63)
284 #define __RTE_TRACE_FIELD_ENABLE_DISCARD (1ULL << 62)
286 struct __rte_trace_stream_header {
290 char thread_name[__RTE_TRACE_EMIT_STRING_LEN_MAX];
293 struct __rte_trace_header {
296 struct __rte_trace_stream_header stream_header;
300 RTE_DECLARE_PER_LCORE(void *, trace_mem);
302 static __rte_always_inline void *
303 __rte_trace_mem_get(uint64_t in)
305 struct __rte_trace_header *trace = RTE_PER_LCORE(trace_mem);
306 const uint16_t sz = in & __RTE_TRACE_FIELD_SIZE_MASK;
308 /* Trace memory is not initialized for this thread */
309 if (unlikely(trace == NULL)) {
310 __rte_trace_mem_per_thread_alloc();
311 trace = RTE_PER_LCORE(trace_mem);
312 if (unlikely(trace == NULL))
315 /* Check the wrap around case */
316 uint32_t offset = trace->offset;
317 if (unlikely((offset + sz) >= trace->len)) {
318 /* Disable the trace event if it in DISCARD mode */
319 if (unlikely(in & __RTE_TRACE_FIELD_ENABLE_DISCARD))
324 /* Align to event header size */
325 offset = RTE_ALIGN_CEIL(offset, __RTE_TRACE_EVENT_HEADER_SZ);
326 void *mem = RTE_PTR_ADD(&trace->mem[0], offset);
328 trace->offset = offset;
333 static __rte_always_inline void *
334 __rte_trace_point_emit_ev_header(void *mem, uint64_t in)
338 /* Event header [63:0] = id [63:48] | timestamp [47:0] */
339 val = rte_get_tsc_cycles() &
340 ~(0xffffULL << __RTE_TRACE_EVENT_HEADER_ID_SHIFT);
341 val |= ((in & __RTE_TRACE_FIELD_ID_MASK) <<
342 (__RTE_TRACE_EVENT_HEADER_ID_SHIFT -
343 __RTE_TRACE_FIELD_ID_SHIFT));
345 *(uint64_t *)mem = val;
346 return RTE_PTR_ADD(mem, __RTE_TRACE_EVENT_HEADER_SZ);
349 #define __rte_trace_point_emit_header_generic(t) \
352 const uint64_t val = __atomic_load_n(t, __ATOMIC_ACQUIRE); \
353 if (likely(!(val & __RTE_TRACE_FIELD_ENABLE_MASK))) \
355 mem = __rte_trace_mem_get(val); \
356 if (unlikely(mem == NULL)) \
358 mem = __rte_trace_point_emit_ev_header(mem, val); \
361 #define __rte_trace_point_emit_header_fp(t) \
362 if (!__rte_trace_point_fp_is_enabled()) \
364 __rte_trace_point_emit_header_generic(t)
366 #define __rte_trace_point_emit(in, type) \
368 memcpy(mem, &(in), sizeof(in)); \
369 mem = RTE_PTR_ADD(mem, sizeof(in)); \
372 #define rte_trace_point_emit_string(in) \
374 if (unlikely(in == NULL)) \
376 rte_strscpy(mem, in, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
377 mem = RTE_PTR_ADD(mem, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
382 #define __rte_trace_point_emit_header_generic(t) RTE_SET_USED(t)
383 #define __rte_trace_point_emit_header_fp(t) RTE_SET_USED(t)
384 #define __rte_trace_point_emit(in, type) RTE_SET_USED(in)
385 #define rte_trace_point_emit_string(in) RTE_SET_USED(in)
387 #endif /* ALLOW_EXPERIMENTAL_API */
388 #endif /* _RTE_TRACE_POINT_REGISTER_H_ */
390 #define rte_trace_point_emit_u64(in) __rte_trace_point_emit(in, uint64_t)
391 #define rte_trace_point_emit_i64(in) __rte_trace_point_emit(in, int64_t)
392 #define rte_trace_point_emit_u32(in) __rte_trace_point_emit(in, uint32_t)
393 #define rte_trace_point_emit_i32(in) __rte_trace_point_emit(in, int32_t)
394 #define rte_trace_point_emit_u16(in) __rte_trace_point_emit(in, uint16_t)
395 #define rte_trace_point_emit_i16(in) __rte_trace_point_emit(in, int16_t)
396 #define rte_trace_point_emit_u8(in) __rte_trace_point_emit(in, uint8_t)
397 #define rte_trace_point_emit_i8(in) __rte_trace_point_emit(in, int8_t)
398 #define rte_trace_point_emit_int(in) __rte_trace_point_emit(in, int32_t)
399 #define rte_trace_point_emit_long(in) __rte_trace_point_emit(in, long)
400 #define rte_trace_point_emit_size_t(in) __rte_trace_point_emit(in, size_t)
401 #define rte_trace_point_emit_float(in) __rte_trace_point_emit(in, float)
402 #define rte_trace_point_emit_double(in) __rte_trace_point_emit(in, double)
403 #define rte_trace_point_emit_ptr(in) __rte_trace_point_emit(in, uintptr_t)
405 #endif /* __DOXYGEN__ */
411 #endif /* _RTE_TRACE_POINT_H_ */