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;
38 * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
40 * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
42 #define RTE_TRACE_POINT_ARGS
44 /** @internal Helper macro to support RTE_TRACE_POINT and RTE_TRACE_POINT_FP */
45 #define __RTE_TRACE_POINT(_mode, _tp, _args, ...) \
46 extern rte_trace_point_t __##_tp; \
47 static __rte_always_inline void \
50 __rte_trace_point_emit_header_##_mode(&__##_tp); \
55 * Create a tracepoint.
57 * A tracepoint is defined by specifying:
58 * - its input arguments: they are the C function style parameters to define
59 * the arguments of tracepoint function. These input arguments are embedded
60 * using the RTE_TRACE_POINT_ARGS macro.
61 * - its output event fields: they are the sources of event fields that form
62 * the payload of any event that the execution of the tracepoint macro emits
63 * for this particular tracepoint. The application uses
64 * rte_trace_point_emit_* macros to emit the output event fields.
67 * Tracepoint object. Before using the tracepoint, an application needs to
68 * define the tracepoint using RTE_TRACE_POINT_REGISTER macro.
70 * C function style input arguments to define the arguments to tracepoint
73 * Define the payload of trace function. The payload will be formed using
74 * rte_trace_point_emit_* macros. Use ";" delimiter between two payloads.
76 * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_REGISTER, rte_trace_point_emit_*
78 #define RTE_TRACE_POINT(tp, args, ...) \
79 __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
82 * Create a tracepoint for fast path.
84 * Similar to RTE_TRACE_POINT, except that it is removed at compilation time
85 * unless the RTE_ENABLE_TRACE_FP configuration parameter is set.
88 * Tracepoint object. Before using the tracepoint, an application needs to
89 * define the tracepoint using RTE_TRACE_POINT_REGISTER macro.
91 * C function style input arguments to define the arguments to tracepoint.
94 * Define the payload of trace function. The payload will be formed using
95 * rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
97 * @see RTE_TRACE_POINT
99 #define RTE_TRACE_POINT_FP(tp, args, ...) \
100 __RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
105 * Register a tracepoint.
108 * The tracepoint object created using RTE_TRACE_POINT_REGISTER.
110 * The name of the tracepoint object.
112 * - 0: Successfully registered the tracepoint.
113 * - <0: Failure to register the tracepoint.
115 #define RTE_TRACE_POINT_REGISTER(trace, name)
117 /** Tracepoint function payload for uint64_t datatype */
118 #define rte_trace_point_emit_u64(val)
119 /** Tracepoint function payload for int64_t datatype */
120 #define rte_trace_point_emit_i64(val)
121 /** Tracepoint function payload for uint32_t datatype */
122 #define rte_trace_point_emit_u32(val)
123 /** Tracepoint function payload for int32_t datatype */
124 #define rte_trace_point_emit_i32(val)
125 /** Tracepoint function payload for uint16_t datatype */
126 #define rte_trace_point_emit_u16(val)
127 /** Tracepoint function payload for int16_t datatype */
128 #define rte_trace_point_emit_i16(val)
129 /** Tracepoint function payload for uint8_t datatype */
130 #define rte_trace_point_emit_u8(val)
131 /** Tracepoint function payload for int8_t datatype */
132 #define rte_trace_point_emit_i8(val)
133 /** Tracepoint function payload for int datatype */
134 #define rte_trace_point_emit_int(val)
135 /** Tracepoint function payload for long datatype */
136 #define rte_trace_point_emit_long(val)
137 /** Tracepoint function payload for size_t datatype */
138 #define rte_trace_point_emit_size_t(val)
139 /** Tracepoint function payload for float datatype */
140 #define rte_trace_point_emit_float(val)
141 /** Tracepoint function payload for double datatype */
142 #define rte_trace_point_emit_double(val)
143 /** Tracepoint function payload for pointer datatype */
144 #define rte_trace_point_emit_ptr(val)
145 /** Tracepoint function payload for string datatype */
146 #define rte_trace_point_emit_string(val)
148 #endif /* __DOXYGEN__ */
150 /** @internal Macro to define maximum emit length of string datatype. */
151 #define __RTE_TRACE_EMIT_STRING_LEN_MAX 32
152 /** @internal Macro to define event header size. */
153 #define __RTE_TRACE_EVENT_HEADER_SZ sizeof(uint64_t)
156 * Enable recording events of the given tracepoint in the trace buffer.
159 * The tracepoint object to enable.
162 * - (-ERANGE): Trace object is not registered.
165 int rte_trace_point_enable(rte_trace_point_t *tp);
168 * Disable recording events of the given tracepoint in the trace buffer.
171 * The tracepoint object to disable.
174 * - (-ERANGE): Trace object is not registered.
177 int rte_trace_point_disable(rte_trace_point_t *tp);
180 * Test if recording events from the given tracepoint is enabled.
183 * The tracepoint object.
185 * true if tracepoint is enabled, false otherwise.
188 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
191 * Lookup a tracepoint object from its name.
194 * The name of the tracepoint.
196 * The tracepoint object or NULL if not found.
199 rte_trace_point_t *rte_trace_point_lookup(const char *name);
204 * Test if the tracepoint fast path compile-time option is enabled.
207 * true if tracepoint fast path enabled, false otherwise.
210 static __rte_always_inline bool
211 __rte_trace_point_fp_is_enabled(void)
213 #ifdef RTE_ENABLE_TRACE_FP
223 * Allocate trace memory buffer per thread.
227 void __rte_trace_mem_per_thread_alloc(void);
232 * Helper function to emit field.
235 * The tracepoint size.
237 * The name of the trace event.
239 * The datatype of the trace event as string.
245 void __rte_trace_point_emit_field(size_t sz, const char *field,
251 * Helper function to register a dynamic tracepoint.
252 * Use RTE_TRACE_POINT_REGISTER macro for tracepoint registration.
255 * The tracepoint object created using RTE_TRACE_POINT_REGISTER.
257 * The name of the tracepoint object.
259 * Trace registration function.
261 * - 0: Successfully registered the tracepoint.
262 * - <0: Failure to register the tracepoint.
265 int __rte_trace_point_register(rte_trace_point_t *trace, const char *name,
266 void (*register_fn)(void));
270 #ifndef _RTE_TRACE_POINT_REGISTER_H_
271 #ifdef ALLOW_EXPERIMENTAL_API
273 #define __RTE_TRACE_EVENT_HEADER_ID_SHIFT (48)
275 #define __RTE_TRACE_FIELD_SIZE_SHIFT 0
276 #define __RTE_TRACE_FIELD_SIZE_MASK (0xffffULL << __RTE_TRACE_FIELD_SIZE_SHIFT)
277 #define __RTE_TRACE_FIELD_ID_SHIFT (16)
278 #define __RTE_TRACE_FIELD_ID_MASK (0xffffULL << __RTE_TRACE_FIELD_ID_SHIFT)
279 #define __RTE_TRACE_FIELD_ENABLE_MASK (1ULL << 63)
280 #define __RTE_TRACE_FIELD_ENABLE_DISCARD (1ULL << 62)
282 struct __rte_trace_stream_header {
286 char thread_name[__RTE_TRACE_EMIT_STRING_LEN_MAX];
289 struct __rte_trace_header {
292 struct __rte_trace_stream_header stream_header;
296 RTE_DECLARE_PER_LCORE(void *, trace_mem);
298 static __rte_always_inline void *
299 __rte_trace_mem_get(uint64_t in)
301 struct __rte_trace_header *trace =
302 (struct __rte_trace_header *)(RTE_PER_LCORE(trace_mem));
303 const uint16_t sz = in & __RTE_TRACE_FIELD_SIZE_MASK;
305 /* Trace memory is not initialized for this thread */
306 if (unlikely(trace == NULL)) {
307 __rte_trace_mem_per_thread_alloc();
308 trace = (struct __rte_trace_header *)(RTE_PER_LCORE(trace_mem));
309 if (unlikely(trace == NULL))
312 /* Check the wrap around case */
313 uint32_t offset = trace->offset;
314 if (unlikely((offset + sz) >= trace->len)) {
315 /* Disable the trace event if it in DISCARD mode */
316 if (unlikely(in & __RTE_TRACE_FIELD_ENABLE_DISCARD))
321 /* Align to event header size */
322 offset = RTE_ALIGN_CEIL(offset, __RTE_TRACE_EVENT_HEADER_SZ);
323 void *mem = RTE_PTR_ADD(&trace->mem[0], offset);
325 trace->offset = offset;
330 static __rte_always_inline void *
331 __rte_trace_point_emit_ev_header(void *mem, uint64_t in)
335 /* Event header [63:0] = id [63:48] | timestamp [47:0] */
336 val = rte_get_tsc_cycles() &
337 ~(0xffffULL << __RTE_TRACE_EVENT_HEADER_ID_SHIFT);
338 val |= ((in & __RTE_TRACE_FIELD_ID_MASK) <<
339 (__RTE_TRACE_EVENT_HEADER_ID_SHIFT -
340 __RTE_TRACE_FIELD_ID_SHIFT));
342 *(uint64_t *)mem = val;
343 return RTE_PTR_ADD(mem, __RTE_TRACE_EVENT_HEADER_SZ);
346 #define __rte_trace_point_emit_header_generic(t) \
349 const uint64_t val = __atomic_load_n(t, __ATOMIC_ACQUIRE); \
350 if (likely(!(val & __RTE_TRACE_FIELD_ENABLE_MASK))) \
352 mem = __rte_trace_mem_get(val); \
353 if (unlikely(mem == NULL)) \
355 mem = __rte_trace_point_emit_ev_header(mem, val); \
358 #define __rte_trace_point_emit_header_fp(t) \
359 if (!__rte_trace_point_fp_is_enabled()) \
361 __rte_trace_point_emit_header_generic(t)
363 #define __rte_trace_point_emit(in, type) \
365 memcpy(mem, &(in), sizeof(in)); \
366 mem = RTE_PTR_ADD(mem, sizeof(in)); \
369 #define rte_trace_point_emit_string(in) \
371 if (unlikely(in == NULL)) \
373 rte_strscpy(mem, in, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
374 mem = RTE_PTR_ADD(mem, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
379 #define __rte_trace_point_emit_header_generic(t) RTE_SET_USED(t)
380 #define __rte_trace_point_emit_header_fp(t) RTE_SET_USED(t)
381 #define __rte_trace_point_emit(in, type) RTE_SET_USED(in)
382 #define rte_trace_point_emit_string(in) RTE_SET_USED(in)
384 #endif /* ALLOW_EXPERIMENTAL_API */
385 #endif /* _RTE_TRACE_POINT_REGISTER_H_ */
387 #define rte_trace_point_emit_u64(in) __rte_trace_point_emit(in, uint64_t)
388 #define rte_trace_point_emit_i64(in) __rte_trace_point_emit(in, int64_t)
389 #define rte_trace_point_emit_u32(in) __rte_trace_point_emit(in, uint32_t)
390 #define rte_trace_point_emit_i32(in) __rte_trace_point_emit(in, int32_t)
391 #define rte_trace_point_emit_u16(in) __rte_trace_point_emit(in, uint16_t)
392 #define rte_trace_point_emit_i16(in) __rte_trace_point_emit(in, int16_t)
393 #define rte_trace_point_emit_u8(in) __rte_trace_point_emit(in, uint8_t)
394 #define rte_trace_point_emit_i8(in) __rte_trace_point_emit(in, int8_t)
395 #define rte_trace_point_emit_int(in) __rte_trace_point_emit(in, int32_t)
396 #define rte_trace_point_emit_long(in) __rte_trace_point_emit(in, long)
397 #define rte_trace_point_emit_size_t(in) __rte_trace_point_emit(in, size_t)
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_ */