1 /* 2 * Interface for configuring and controlling the state of tracing events. 3 * 4 * Copyright (C) 2011-2016 Lluís Vilanova <vilanova@ac.upc.edu> 5 * 6 * This work is licensed under the terms of the GNU GPL, version 2 or later. 7 * See the COPYING file in the top-level directory. 8 */ 9 10 #ifndef TRACE__CONTROL_H 11 #define TRACE__CONTROL_H 12 13 #include "qemu-common.h" 14 #include "qemu/typedefs.h" 15 #include "trace/generated-events.h" 16 17 18 /** 19 * TraceEventID: 20 * 21 * Unique tracing event identifier. 22 * 23 * These are named as 'TRACE_${EVENT_NAME}'. 24 * 25 * See also: "trace/generated-events.h" 26 */ 27 enum TraceEventID; 28 29 /** 30 * trace_event_id: 31 * @id: Event identifier. 32 * 33 * Get an event by its identifier. 34 * 35 * This routine has a constant cost, as opposed to trace_event_name and 36 * trace_event_pattern. 37 * 38 * Pre-conditions: The identifier is valid. 39 * 40 * Returns: pointer to #TraceEvent. 41 * 42 */ 43 static TraceEvent *trace_event_id(TraceEventID id); 44 45 /** 46 * trace_event_name: 47 * @id: Event name. 48 * 49 * Search an event by its name. 50 * 51 * Returns: pointer to #TraceEvent or NULL if not found. 52 */ 53 TraceEvent *trace_event_name(const char *name); 54 55 /** 56 * trace_event_pattern: 57 * @pat: Event name pattern. 58 * @ev: Event to start searching from (not included). 59 * 60 * Get all events with a given name pattern. 61 * 62 * Returns: pointer to #TraceEvent or NULL if not found. 63 */ 64 TraceEvent *trace_event_pattern(const char *pat, TraceEvent *ev); 65 66 /** 67 * trace_event_is_pattern: 68 * 69 * Whether the given string is an event name pattern. 70 */ 71 static bool trace_event_is_pattern(const char *str); 72 73 /** 74 * trace_event_count: 75 * 76 * Return the number of events. 77 */ 78 static TraceEventID trace_event_count(void); 79 80 81 82 /** 83 * trace_event_get_id: 84 * 85 * Get the identifier of an event. 86 */ 87 static TraceEventID trace_event_get_id(TraceEvent *ev); 88 89 /** 90 * trace_event_get_name: 91 * 92 * Get the name of an event. 93 */ 94 static const char * trace_event_get_name(TraceEvent *ev); 95 96 /** 97 * trace_event_get_state: 98 * @id: Event identifier. 99 * 100 * Get the tracing state of an event (both static and dynamic). 101 * 102 * If the event has the disabled property, the check will have no performance 103 * impact. 104 * 105 * As a down side, you must always use an immediate #TraceEventID value. 106 */ 107 #define trace_event_get_state(id) \ 108 ((id ##_ENABLED) && trace_event_get_state_dynamic_by_id(id)) 109 110 /** 111 * trace_event_get_state_static: 112 * @id: Event identifier. 113 * 114 * Get the static tracing state of an event. 115 * 116 * Use the define 'TRACE_${EVENT_NAME}_ENABLED' for compile-time checks (it will 117 * be set to 1 or 0 according to the presence of the disabled property). 118 */ 119 static bool trace_event_get_state_static(TraceEvent *ev); 120 121 /** 122 * trace_event_get_state_dynamic: 123 * 124 * Get the dynamic tracing state of an event. 125 */ 126 static bool trace_event_get_state_dynamic(TraceEvent *ev); 127 128 /** 129 * trace_event_set_state: 130 * 131 * Set the tracing state of an event (only if possible). 132 */ 133 #define trace_event_set_state(id, state) \ 134 do { \ 135 if ((id ##_ENABLED)) { \ 136 TraceEvent *_e = trace_event_id(id); \ 137 trace_event_set_state_dynamic(_e, state); \ 138 } \ 139 } while (0) 140 141 /** 142 * trace_event_set_state_dynamic: 143 * 144 * Set the dynamic tracing state of an event. 145 * 146 * Pre-condition: trace_event_get_state_static(ev) == true 147 */ 148 static void trace_event_set_state_dynamic(TraceEvent *ev, bool state); 149 150 151 152 /** 153 * trace_init_backends: 154 * @file: Name of trace output file; may be NULL. 155 * Corresponds to commandline option "-trace file=...". 156 * 157 * Initialize the tracing backend. 158 * 159 * Returns: Whether the backends could be successfully initialized. 160 */ 161 bool trace_init_backends(void); 162 163 /** 164 * trace_init_events: 165 * @events: Name of file with events to be enabled at startup; may be NULL. 166 * Corresponds to commandline option "-trace events=...". 167 * 168 * Read the list of enabled tracing events. 169 * 170 * Returns: Whether the backends could be successfully initialized. 171 */ 172 void trace_init_events(const char *file); 173 174 /** 175 * trace_init_file: 176 * @file: Name of trace output file; may be NULL. 177 * Corresponds to commandline option "-trace file=...". 178 * 179 * Record the name of the output file for the tracing backend. 180 * Exits if no selected backend does not support specifying the 181 * output file, and a non-NULL file was passed. 182 */ 183 void trace_init_file(const char *file); 184 185 /** 186 * trace_list_events: 187 * 188 * List all available events. 189 */ 190 void trace_list_events(void); 191 192 /** 193 * trace_enable_events: 194 * @line_buf: A string with a glob pattern of events to be enabled or, 195 * if the string starts with '-', disabled. 196 * 197 * Enable or disable matching events. 198 */ 199 void trace_enable_events(const char *line_buf); 200 201 202 #include "trace/control-internal.h" 203 204 #endif /* TRACE__CONTROL_H */ 205