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_common.h>
  27 #include <rte_compat.h>
  28
  29 /** The tracepoint object. */
  30 typedef uint64_t rte_trace_point_t;
  31
  32 /** Macro to define the tracepoint. */
  33 #define RTE_TRACE_POINT_DEFINE(tp) \
  34 rte_trace_point_t __attribute__((section("__rte_trace_point"))) __##tp
  35
  36 /**
  37  * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
  38
  39  * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
  40  */
  41 #define RTE_TRACE_POINT_ARGS
  42
  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 \
  47 _tp _args \
  48 { \
  49         __rte_trace_point_emit_header_##_mode(&__##_tp); \
  50         __VA_ARGS__ \
  51 }
  52
  53 /**
  54  * Create a tracepoint.
  55  *
  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.
  64  *
  65  * @param tp
  66  *   Tracepoint object. Before using the tracepoint, an application needs to
  67  *   define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
  68  * @param args
  69  *   C function style input arguments to define the arguments to tracepoint
  70  *   function.
  71  * @param ...
  72  *   Define the payload of trace function. The payload will be formed using
  73  *   rte_trace_point_emit_* macros. Use ";" delimiter between two payloads.
  74  *
  75  * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_DEFINE, rte_trace_point_emit_*
  76  */
  77 #define RTE_TRACE_POINT(tp, args, ...) \
  78         __RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
  79
  80 /**
  81  * Create a tracepoint for fast path.
  82  *
  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.
  85  *
  86  * @param tp
  87  *   Tracepoint object. Before using the tracepoint, an application needs to
  88  *   define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
  89  * @param args
  90  *   C function style input arguments to define the arguments to tracepoint.
  91  *   function.
  92  * @param ...
  93  *   Define the payload of trace function. The payload will be formed using
  94  *   rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
  95  *
  96  * @see RTE_TRACE_POINT
  97  */
  98 #define RTE_TRACE_POINT_FP(tp, args, ...) \
  99         __RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
 100
 101 #ifdef __DOXYGEN__
 102
 103 /**
 104  * Macro to select rte_trace_point_emit_* definition for trace register function
 105  *
 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.
 109  *
 110  * @see RTE_TRACE_POINT_REGISTER
 111  */
 112 #define RTE_TRACE_POINT_REGISTER_SELECT
 113
 114 /**
 115  * Register a tracepoint.
 116  *
 117  * @param trace
 118  *   The tracepoint object created using RTE_TRACE_POINT_DEFINE.
 119  * @param name
 120  *   The name of the tracepoint object.
 121  * @return
 122  *   - 0: Successfully registered the tracepoint.
 123  *   - <0: Failure to register the tracepoint.
 124  *
 125  * @see RTE_TRACE_POINT_REGISTER_SELECT
 126  */
 127 #define RTE_TRACE_POINT_REGISTER(trace, name)
 128
 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)
 157
 158 #endif /* __DOXYGEN__ */
 159
 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)
 164
 165 /**
 166  * Enable recording events of the given tracepoint in the trace buffer.
 167  *
 168  * @param tp
 169  *   The tracepoint object to enable.
 170  * @return
 171  *   - 0: Success.
 172  *   - (-ERANGE): Trace object is not registered.
 173  */
 174 __rte_experimental
 175 int rte_trace_point_enable(rte_trace_point_t *tp);
 176
 177 /**
 178  * Disable recording events of the given tracepoint in the trace buffer.
 179  *
 180  * @param tp
 181  *   The tracepoint object to disable.
 182  * @return
 183  *   - 0: Success.
 184  *   - (-ERANGE): Trace object is not registered.
 185  */
 186 __rte_experimental
 187 int rte_trace_point_disable(rte_trace_point_t *tp);
 188
 189 /**
 190  * Test if recording events from the given tracepoint is enabled.
 191  *
 192  * @param tp
 193  *    The tracepoint object.
 194  * @return
 195  *    true if tracepoint is enabled, false otherwise.
 196  */
 197 __rte_experimental
 198 bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
 199
 200 /**
 201  * Lookup a tracepoint object from its name.
 202  *
 203  * @param name
 204  *   The name of the tracepoint.
 205  * @return
 206  *   The tracepoint object or NULL if not found.
 207  */
 208 __rte_experimental
 209 rte_trace_point_t *rte_trace_point_lookup(const char *name);
 210
 211 /**
 212  * @internal
 213  *
 214  * Test if the tracepoint fast path compile-time option is enabled.
 215  *
 216  * @return
 217  *   true if tracepoint fast path enabled, false otherwise.
 218  */
 219 __rte_experimental
 220 static __rte_always_inline bool
 221 __rte_trace_point_fp_is_enabled(void)
 222 {
 223 #ifdef RTE_ENABLE_TRACE_FP
 224         return true;
 225 #else
 226         return false;
 227 #endif
 228 }
 229
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233
 234 #endif /* _RTE_TRACE_POINT_H_ */