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_ */ 142