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 "trace/generated-events.h" 15 16 17 /** 18 * TraceEventID: 19 * 20 * Unique tracing event identifier. 21 * 22 * These are named as 'TRACE_${EVENT_NAME}'. 23 * 24 * See also: "trace/generated-events.h" 25 */ 26 enum TraceEventID; 27 28 /** 29 * trace_event_id: 30 * @id: Event identifier. 31 * 32 * Get an event by its identifier. 33 * 34 * This routine has a constant cost, as opposed to trace_event_name and 35 * trace_event_pattern. 36 * 37 * Pre-conditions: The identifier is valid. 38 * 39 * Returns: pointer to #TraceEvent. 40 * 41 */ 42 static TraceEvent *trace_event_id(TraceEventID id); 43 44 /** 45 * trace_event_name: 46 * @id: Event name. 47 * 48 * Search an event by its name. 49 * 50 * Returns: pointer to #TraceEvent or NULL if not found. 51 */ 52 TraceEvent *trace_event_name(const char *name); 53 54 /** 55 * trace_event_pattern: 56 * @pat: Event name pattern. 57 * @ev: Event to start searching from (not included). 58 * 59 * Get all events with a given name pattern. 60 * 61 * Returns: pointer to #TraceEvent or NULL if not found. 62 */ 63 TraceEvent *trace_event_pattern(const char *pat, TraceEvent *ev); 64 65 /** 66 * trace_event_is_pattern: 67 * 68 * Whether the given string is an event name pattern. 69 */ 70 static bool trace_event_is_pattern(const char *str); 71 72 /** 73 * trace_event_count: 74 * 75 * Return the number of events. 76 */ 77 static TraceEventID trace_event_count(void); 78 79 80 81 /** 82 * trace_event_get_id: 83 * 84 * Get the identifier of an event. 85 */ 86 static TraceEventID trace_event_get_id(TraceEvent *ev); 87 88 /** 89 * trace_event_get_vcpu_id: 90 * 91 * Get the per-vCPU identifier of an event. 92 * 93 * Special value #TRACE_VCPU_EVENT_COUNT means the event is not vCPU-specific 94 * (does not have the "vcpu" property). 95 */ 96 static TraceEventVCPUID trace_event_get_vcpu_id(TraceEvent *ev); 97 98 /** 99 * trace_event_is_vcpu: 100 * 101 * Whether this is a per-vCPU event. 102 */ 103 static bool trace_event_is_vcpu(TraceEvent *ev); 104 105 /** 106 * trace_event_get_name: 107 * 108 * Get the name of an event. 109 */ 110 static const char * trace_event_get_name(TraceEvent *ev); 111 112 /** 113 * trace_event_get_state: 114 * @id: Event identifier. 115 * 116 * Get the tracing state of an event (both static and dynamic). 117 * 118 * If the event has the disabled property, the check will have no performance 119 * impact. 120 * 121 * As a down side, you must always use an immediate #TraceEventID value. 122 */ 123 #define trace_event_get_state(id) \ 124 ((id ##_ENABLED) && trace_event_get_state_dynamic_by_id(id)) 125 126 /** 127 * trace_event_get_vcpu_state: 128 * @vcpu: Target vCPU. 129 * @id: Event identifier (TraceEventID). 130 * @vcpu_id: Per-vCPU event identifier (TraceEventVCPUID). 131 * 132 * Get the tracing state of an event (both static and dynamic) for the given 133 * vCPU. 134 * 135 * If the event has the disabled property, the check will have no performance 136 * impact. 137 * 138 * As a down side, you must always use an immediate #TraceEventID value. 139 */ 140 #define trace_event_get_vcpu_state(vcpu, id, vcpu_id) \ 141 ((id ##_ENABLED) && trace_event_get_vcpu_state_dynamic_by_vcpu_id(vcpu, vcpu_id)) 142 143 /** 144 * trace_event_get_state_static: 145 * @id: Event identifier. 146 * 147 * Get the static tracing state of an event. 148 * 149 * Use the define 'TRACE_${EVENT_NAME}_ENABLED' for compile-time checks (it will 150 * be set to 1 or 0 according to the presence of the disabled property). 151 */ 152 static bool trace_event_get_state_static(TraceEvent *ev); 153 154 /** 155 * trace_event_get_state_dynamic: 156 * 157 * Get the dynamic tracing state of an event. 158 * 159 * If the event has the 'vcpu' property, gets the OR'ed state of all vCPUs. 160 */ 161 static bool trace_event_get_state_dynamic(TraceEvent *ev); 162 163 /** 164 * trace_event_get_vcpu_state_dynamic: 165 * 166 * Get the dynamic tracing state of an event for the given vCPU. 167 */ 168 static bool trace_event_get_vcpu_state_dynamic(CPUState *vcpu, TraceEvent *ev); 169 170 /** 171 * trace_event_set_state: 172 * 173 * Set the tracing state of an event (only if possible). 174 */ 175 #define trace_event_set_state(id, state) \ 176 do { \ 177 if ((id ##_ENABLED)) { \ 178 TraceEvent *_e = trace_event_id(id); \ 179 trace_event_set_state_dynamic(_e, state); \ 180 } \ 181 } while (0) 182 183 /** 184 * trace_event_set_vcpu_state: 185 * 186 * Set the tracing state of an event for the given vCPU (only if not disabled). 187 */ 188 #define trace_event_set_vcpu_state(vcpu, id, state) \ 189 do { \ 190 if ((id ##_ENABLED)) { \ 191 TraceEvent *_e = trace_event_id(id); \ 192 trace_event_set_vcpu_state_dynamic(vcpu, _e, state); \ 193 } \ 194 } while (0) 195 196 /** 197 * trace_event_set_state_dynamic: 198 * 199 * Set the dynamic tracing state of an event. 200 * 201 * If the event has the 'vcpu' property, sets the state on all vCPUs. 202 * 203 * Pre-condition: trace_event_get_state_static(ev) == true 204 */ 205 void trace_event_set_state_dynamic(TraceEvent *ev, bool state); 206 207 /** 208 * trace_event_set_vcpu_state_dynamic: 209 * 210 * Set the dynamic tracing state of an event for the given vCPU. 211 * 212 * Pre-condition: trace_event_get_vcpu_state_static(ev) == true 213 */ 214 void trace_event_set_vcpu_state_dynamic(CPUState *vcpu, 215 TraceEvent *ev, bool state); 216 217 218 219 /** 220 * trace_init_backends: 221 * @file: Name of trace output file; may be NULL. 222 * Corresponds to commandline option "-trace file=...". 223 * 224 * Initialize the tracing backend. 225 * 226 * Returns: Whether the backends could be successfully initialized. 227 */ 228 bool trace_init_backends(void); 229 230 /** 231 * trace_init_file: 232 * @file: Name of trace output file; may be NULL. 233 * Corresponds to commandline option "-trace file=...". 234 * 235 * Record the name of the output file for the tracing backend. 236 * Exits if no selected backend does not support specifying the 237 * output file, and a non-NULL file was passed. 238 */ 239 void trace_init_file(const char *file); 240 241 /** 242 * trace_list_events: 243 * 244 * List all available events. 245 */ 246 void trace_list_events(void); 247 248 /** 249 * trace_enable_events: 250 * @line_buf: A string with a glob pattern of events to be enabled or, 251 * if the string starts with '-', disabled. 252 * 253 * Enable or disable matching events. 254 */ 255 void trace_enable_events(const char *line_buf); 256 257 /** 258 * Definition of QEMU options describing trace subsystem configuration 259 */ 260 extern QemuOptsList qemu_trace_opts; 261 262 /** 263 * trace_opt_parse: 264 * @optarg: A string argument of --trace command line argument 265 * 266 * Initialize tracing subsystem. 267 * 268 * Returns the filename to save trace to. It must be freed with g_free(). 269 */ 270 char *trace_opt_parse(const char *optarg); 271 272 /** 273 * trace_init_vcpu_events: 274 * 275 * Re-synchronize initial event state with vCPUs (which can be created after 276 * trace_init_events()). 277 */ 278 void trace_init_vcpu_events(void); 279 280 281 #include "trace/control-internal.h" 282 283 #endif /* TRACE__CONTROL_H */ 284