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 #include <stdbool.h> 20 #include <stdio.h> 21 22 #include <rte_common.h> 23 #include <rte_compat.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 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 * @warning 40 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 41 * 42 * Test if trace feature is enabled at compile time. 43 * 44 * @return 45 * true if trace feature is enabled, false otherwise. 46 */ 47 __rte_experimental 48 static __rte_always_inline bool 49 rte_trace_feature_is_enabled(void) 50 { 51 #ifdef RTE_TRACE 52 return true; 53 #else 54 return false; 55 #endif 56 } 57 58 /** 59 * Enumerate trace mode operation. 60 */ 61 enum rte_trace_mode { 62 /** 63 * In this mode, when no space is left in the trace buffer, the 64 * subsequent events overwrite the old events. 65 */ 66 RTE_TRACE_MODE_OVERWRITE, 67 /** 68 * In this mode, when no space is left in the trace buffer, the 69 * subsequent events shall not be recorded. 70 */ 71 RTE_TRACE_MODE_DISCARD, 72 }; 73 74 /** 75 * Set the trace mode. 76 * 77 * @param mode 78 * Trace mode. 79 */ 80 __rte_experimental 81 void rte_trace_mode_set(enum rte_trace_mode mode); 82 83 /** 84 * Get the trace mode. 85 * 86 * @return 87 * The current trace mode. 88 */ 89 __rte_experimental 90 enum rte_trace_mode rte_trace_mode_get(void); 91 92 /** 93 * Enable/Disable a set of tracepoints based on globbing pattern. 94 * 95 * @param pattern 96 * The globbing pattern identifying the tracepoint. 97 * @param enable 98 * true to enable tracepoint, false to disable the tracepoint, upon match. 99 * @return 100 * - 0: Success and no pattern match. 101 * - 1: Success and found pattern match. 102 * - (-ERANGE): Tracepoint object is not registered. 103 */ 104 __rte_experimental 105 int rte_trace_pattern(const char *pattern, bool enable); 106 107 /** 108 * Enable/Disable a set of tracepoints based on regular expression. 109 * 110 * @param regex 111 * A regular expression identifying the tracepoint. 112 * @param enable 113 * true to enable tracepoint, false to disable the tracepoint, upon match. 114 * @return 115 * - 0: Success and no pattern match. 116 * - 1: Success and found pattern match. 117 * - (-ERANGE): Tracepoint object is not registered. 118 * - (-EINVAL): Invalid regular expression rule. 119 */ 120 __rte_experimental 121 int rte_trace_regexp(const char *regex, bool enable); 122 123 /** 124 * Save the trace buffer to the trace directory. 125 * 126 * By default, trace directory will be created at $HOME directory and this can 127 * be overridden by --trace-dir EAL parameter. 128 * 129 * @return 130 * - 0: Success. 131 * - <0 : Failure. 132 */ 133 __rte_experimental 134 int rte_trace_save(void); 135 136 /** 137 * Dump the trace metadata to a file. 138 * 139 * @param f 140 * A pointer to a file for output 141 * @return 142 * - 0: Success. 143 * - <0 : Failure. 144 */ 145 __rte_experimental 146 int rte_trace_metadata_dump(FILE *f); 147 148 /** 149 * Dump the trace subsystem status to a file. 150 * 151 * @param f 152 * A pointer to a file for output 153 */ 154 __rte_experimental 155 void rte_trace_dump(FILE *f); 156 157 #ifdef __cplusplus 158 } 159 #endif 160 161 #endif /* _RTE_TRACE_H_ */ 162