lib/librte_eal/include/rte_trace.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(C) 2020 Marvell International Ltd.
   3  */
   4
   5 #ifndef _RTE_TRACE_H_
   6 #define _RTE_TRACE_H_
   7
   8 /**
   9  * @file
  10  *
  11  * RTE Trace API
  12  *
  13  * This file provides the trace 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 /**
  30  *  Test if trace is enabled.
  31  *
  32  *  @return
  33  *     true if trace is enabled, false otherwise.
  34  */
  35 __rte_experimental
  36 bool rte_trace_is_enabled(void);
  37
  38 /**
  39  * Enumerate trace mode operation.
  40  */
  41 enum rte_trace_mode {
  42         /**
  43          * In this mode, when no space is left in the trace buffer, the
  44          * subsequent events overwrite the old events.
  45          */
  46         RTE_TRACE_MODE_OVERWRITE,
  47         /**
  48          * In this mode, when no space is left in the trace buffer, the
  49          * subsequent events shall not be recorded.
  50          */
  51         RTE_TRACE_MODE_DISCARD,
  52 };
  53
  54 /**
  55  * Set the trace mode.
  56  *
  57  * @param mode
  58  *   Trace mode.
  59  */
  60 __rte_experimental
  61 void rte_trace_mode_set(enum rte_trace_mode mode);
  62
  63 /**
  64  * Get the trace mode.
  65  *
  66  * @return
  67  *   The current trace mode.
  68  */
  69 __rte_experimental
  70 enum rte_trace_mode rte_trace_mode_get(void);
  71
  72 /**
  73  * Enable/Disable a set of tracepoints based on globbing pattern.
  74  *
  75  * @param pattern
  76  *   The globbing pattern identifying the tracepoint.
  77  * @param enable
  78  *   true to enable tracepoint, false to disable the tracepoint, upon match.
  79  * @return
  80  *   - 0: Success and no pattern match.
  81  *   - 1: Success and found pattern match.
  82  *   - (-ERANGE): Tracepoint object is not registered.
  83  */
  84 __rte_experimental
  85 int rte_trace_pattern(const char *pattern, bool enable);
  86
  87 /**
  88  * Enable/Disable a set of tracepoints based on regular expression.
  89  *
  90  * @param regex
  91  *   A regular expression identifying the tracepoint.
  92  * @param enable
  93  *   true to enable tracepoint, false to disable the tracepoint, upon match.
  94  * @return
  95  *   - 0: Success and no pattern match.
  96  *   - 1: Success and found pattern match.
  97  *   - (-ERANGE): Tracepoint object is not registered.
  98  *   - (-EINVAL): Invalid regular expression rule.
  99  */
 100 __rte_experimental
 101 int rte_trace_regexp(const char *regex, bool enable);
 102
 103 /**
 104  * Save the trace buffer to the trace directory.
 105  *
 106  * By default, trace directory will be created at $HOME directory and this can
 107  * be overridden by --trace-dir EAL parameter.
 108  *
 109  * @return
 110  *   - 0: Success.
 111  *   - <0 : Failure.
 112  */
 113 __rte_experimental
 114 int rte_trace_save(void);
 115
 116 /**
 117  * Dump the trace metadata to a file.
 118  *
 119  * @param f
 120  *   A pointer to a file for output
 121  * @return
 122  *   - 0: Success.
 123  *   - <0 : Failure.
 124  */
 125 __rte_experimental
 126 int rte_trace_metadata_dump(FILE *f);
 127
 128 /**
 129  * Dump the trace subsystem status to a file.
 130  *
 131  * @param f
 132  *   A pointer to a file for output
 133  */
 134 __rte_experimental
 135 void rte_trace_dump(FILE *f);
 136
 137 #ifdef __cplusplus
 138 }
 139 #endif
 140
 141 #endif /* _RTE_TRACE_H_ */