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