lib/librte_eal/include/rte_trace_point.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(C) 2020 Marvell International Ltd.
   3  */
   4
   5 #ifndef _RTE_TRACE_POINT_H_
   6 #define _RTE_TRACE_POINT_H_
   7
   8 /**
   9  * @file
  10  *
  11  * RTE Tracepoint API
  12  *
  13  * This file provides the tracepoint API to RTE applications.
  14  *
  15  * @warning
  16  * @b EXPERIMENTAL: this API may change without prior notice
  17  */
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #include <stdbool.h>
  24 #include <stdio.h>
  25
  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>
  32 #include <rte_uuid.h>
  33
  34 /** The tracepoint object. */
  35 typedef uint64_t rte_trace_point_t;
  36
  37 /** Macro to define the tracepoint. */
  38 #define RTE_TRACE_POINT_DEFINE(tp) \
  39 rte_trace_point_t __attribute__((section("__rte_trace_point"))) __##tp
  40
  41 /**
  42  * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
  43
  44  * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
  45  */
  46 #define RTE_TRACE_POINT_ARGS
  47
  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 \
  52 _tp _args \
  53 { \
  54         __rte_trace_point_emit_header_##_mode(&__##_tp); \
  55         __VA_ARGS__ \
  56 }
  57
  58 /**
  59  * Create a tracepoint.
  60  *
  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.
  69  *
  70  * @param tp
  71  *   Tracepoint object. Before using the tracepoint, an application needs to
  72  *   define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
  73  * @param args
  74  *   C function style input arguments to define the arguments to tracepoint
  75  *   function.
  76  * @param ...
  77  *   Define the payload of trace function. The payload will be formed using
  78  *   rte_trace_point_emit_* macros. Use ";" delimiter between two payloads.
  79  *
  80  * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_DEFINE, rte_trace_point_emit_*
  81  */
  82 #define RTE_TRACE_POINT(tp, args, ...) \
  83         __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
  84
  85 /**
  86  * Create a tracepoint for fast path.
  87  *
  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.
  90  *
  91  * @param tp
  92  *   Tracepoint object. Before using the tracepoint, an application needs to
  93  *   define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
  94  * @param args
  95  *   C function style input arguments to define the arguments to tracepoint.
  96  *   function.
  97  * @param ...
  98  *   Define the payload of trace function. The payload will be formed using
  99  *   rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
 100  *
 101  * @see RTE_TRACE_POINT
 102  */
 103 #define RTE_TRACE_POINT_FP(tp, args, ...) \
 104         __RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
 105
 106 #ifdef __DOXYGEN__
 107
 108 /**
 109  * Register a tracepoint.
 110  *
 111  * @param trace
 112  *   The tracepoint object created using RTE_TRACE_POINT_DEFINE.
 113  * @param name
 114  *   The name of the tracepoint object.
 115  * @return
 116  *   - 0: Successfully registered the tracepoint.
 117  *   - <0: Failure to register the tracepoint.
 118  */
 119 #define RTE_TRACE_POINT_REGISTER(trace, name)
 120
 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)
 151
 152 #endif /* __DOXYGEN__ */
 153
 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)
 158
 159 /**
 160  * Enable recording events of the given tracepoint in the trace buffer.
 161  *
 162  * @param tp
 163  *   The tracepoint object to enable.
 164  * @return
 165  *   - 0: Success.
 166  *   - (-ERANGE): Trace object is not registered.
 167  */
 168 __rte_experimental
 169 int rte_trace_point_enable(rte_trace_point_t *tp);
 170
 171 /**
 172  * Disable recording events of the given tracepoint in the trace buffer.
 173  *
 174  * @param tp
 175  *   The tracepoint object to disable.
 176  * @return
 177  *   - 0: Success.
 178  *   - (-ERANGE): Trace object is not registered.
 179  */
 180 __rte_experimental
 181 int rte_trace_point_disable(rte_trace_point_t *tp);
 182
 183 /**
 184  * Test if recording events from the given tracepoint is enabled.
 185  *
 186  * @param tp
 187  *    The tracepoint object.
 188  * @return
 189  *    true if tracepoint is enabled, false otherwise.
 190  */
 191 __rte_experimental
 192 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
 193
 194 /**
 195  * Lookup a tracepoint object from its name.
 196  *
 197  * @param name
 198  *   The name of the tracepoint.
 199  * @return
 200  *   The tracepoint object or NULL if not found.
 201  */
 202 __rte_experimental
 203 rte_trace_point_t *rte_trace_point_lookup(const char *name);
 204
 205 /**
 206  * @internal
 207  *
 208  * Test if the tracepoint fast path compile-time option is enabled.
 209  *
 210  * @return
 211  *   true if tracepoint fast path enabled, false otherwise.
 212  */
 213 __rte_experimental
 214 static __rte_always_inline bool
 215 __rte_trace_point_fp_is_enabled(void)
 216 {
 217 #ifdef RTE_ENABLE_TRACE_FP
 218         return true;
 219 #else
 220         return false;
 221 #endif
 222 }
 223
 224 /**
 225  * @internal
 226  *
 227  * Allocate trace memory buffer per thread.
 228  *
 229  */
 230 __rte_experimental
 231 void __rte_trace_mem_per_thread_alloc(void);
 232
 233 /**
 234  * @internal
 235  *
 236  * Helper function to emit field.
 237  *
 238  * @param sz
 239  *   The tracepoint size.
 240  * @param field
 241  *   The name of the trace event.
 242  * @param type
 243  *   The datatype of the trace event as string.
 244  * @return
 245  *   - 0: Success.
 246  *   - <0: Failure.
 247  */
 248 __rte_experimental
 249 void __rte_trace_point_emit_field(size_t sz, const char *field,
 250         const char *type);
 251
 252 /**
 253  * @internal
 254  *
 255  * Helper function to register a dynamic tracepoint.
 256  * Use RTE_TRACE_POINT_REGISTER macro for tracepoint registration.
 257  *
 258  * @param trace
 259  *   The tracepoint object created using RTE_TRACE_POINT_DEFINE.
 260  * @param name
 261  *   The name of the tracepoint object.
 262  * @param register_fn
 263  *   Trace registration function.
 264  * @return
 265  *   - 0: Successfully registered the tracepoint.
 266  *   - <0: Failure to register the tracepoint.
 267  */
 268 __rte_experimental
 269 int __rte_trace_point_register(rte_trace_point_t *trace, const char *name,
 270         void (*register_fn)(void));
 271
 272 #ifndef __DOXYGEN__
 273
 274 #ifndef _RTE_TRACE_POINT_REGISTER_H_
 275 #ifdef ALLOW_EXPERIMENTAL_API
 276
 277 #define __RTE_TRACE_EVENT_HEADER_ID_SHIFT (48)
 278
 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)
 285
 286 struct __rte_trace_stream_header {
 287         uint32_t magic;
 288         rte_uuid_t uuid;
 289         uint32_t lcore_id;
 290         char thread_name[__RTE_TRACE_EMIT_STRING_LEN_MAX];
 291 } __rte_packed;
 292
 293 struct __rte_trace_header {
 294         uint32_t offset;
 295         uint32_t len;
 296         struct __rte_trace_stream_header stream_header;
 297         uint8_t mem[];
 298 };
 299
 300 RTE_DECLARE_PER_LCORE(void *, trace_mem);
 301
 302 static __rte_always_inline void *
 303 __rte_trace_mem_get(uint64_t in)
 304 {
 305         struct __rte_trace_header *trace = RTE_PER_LCORE(trace_mem);
 306         const uint16_t sz = in & __RTE_TRACE_FIELD_SIZE_MASK;
 307
 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))
 313                         return NULL;
 314         }
 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))
 320                         return NULL;
 321
 322                 offset = 0;
 323         }
 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);
 327         offset += sz;
 328         trace->offset = offset;
 329
 330         return mem;
 331 }
 332
 333 static __rte_always_inline void *
 334 __rte_trace_point_emit_ev_header(void *mem, uint64_t in)
 335 {
 336         uint64_t val;
 337
 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));
 344
 345         *(uint64_t *)mem = val;
 346         return RTE_PTR_ADD(mem, __RTE_TRACE_EVENT_HEADER_SZ);
 347 }
 348
 349 #define __rte_trace_point_emit_header_generic(t) \
 350 void *mem; \
 351 do { \
 352         const uint64_t val = __atomic_load_n(t, __ATOMIC_ACQUIRE); \
 353         if (likely(!(val & __RTE_TRACE_FIELD_ENABLE_MASK))) \
 354                 return; \
 355         mem = __rte_trace_mem_get(val); \
 356         if (unlikely(mem == NULL)) \
 357                 return; \
 358         mem = __rte_trace_point_emit_ev_header(mem, val); \
 359 } while (0)
 360
 361 #define __rte_trace_point_emit_header_fp(t) \
 362         if (!__rte_trace_point_fp_is_enabled()) \
 363                 return; \
 364         __rte_trace_point_emit_header_generic(t)
 365
 366 #define __rte_trace_point_emit(in, type) \
 367 do { \
 368         memcpy(mem, &(in), sizeof(in)); \
 369         mem = RTE_PTR_ADD(mem, sizeof(in)); \
 370 } while (0)
 371
 372 #define rte_trace_point_emit_string(in) \
 373 do { \
 374         if (unlikely(in == NULL)) \
 375                 return; \
 376         rte_strscpy(mem, in, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
 377         mem = RTE_PTR_ADD(mem, __RTE_TRACE_EMIT_STRING_LEN_MAX); \
 378 } while (0)
 379
 380 #else
 381
 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)
 386
 387 #endif /* ALLOW_EXPERIMENTAL_API */
 388 #endif /* _RTE_TRACE_POINT_REGISTER_H_ */
 389
 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)
 404
 405 #endif /* __DOXYGEN__ */
 406
 407 #ifdef __cplusplus
 408 }
 409 #endif
 410
 411 #endif /* _RTE_TRACE_POINT_H_ */