1 /* 2 * Interface for configuring and controlling the state of tracing events. 3 * 4 * Copyright (C) 2011-2014 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_name: 90 * 91 * Get the name of an event. 92 */ 93 static const char * trace_event_get_name(TraceEvent *ev); 94 95 /** 96 * trace_event_get_state: 97 * @id: Event identifier. 98 * 99 * Get the tracing state of an event (both static and dynamic). 100 * 101 * If the event has the disabled property, the check will have no performance 102 * impact. 103 * 104 * As a down side, you must always use an immediate #TraceEventID value. 105 */ 106 #define trace_event_get_state(id) \ 107 ((id ##_ENABLED) && trace_event_get_state_dynamic_by_id(id)) 108 109 /** 110 * trace_event_get_state_static: 111 * @id: Event identifier. 112 * 113 * Get the static tracing state of an event. 114 * 115 * Use the define 'TRACE_${EVENT_NAME}_ENABLED' for compile-time checks (it will 116 * be set to 1 or 0 according to the presence of the disabled property). 117 */ 118 static bool trace_event_get_state_static(TraceEvent *ev); 119 120 /** 121 * trace_event_get_state_dynamic: 122 * 123 * Get the dynamic tracing state of an event. 124 */ 125 static bool trace_event_get_state_dynamic(TraceEvent *ev); 126 127 /** 128 * trace_event_set_state: 129 * 130 * Set the tracing state of an event (only if possible). 131 */ 132 #define trace_event_set_state(id, state) \ 133 do { \ 134 if ((id ##_ENABLED)) { \ 135 TraceEvent *_e = trace_event_id(id); \ 136 trace_event_set_state_dynamic(_e, state); \ 137 } \ 138 } while (0) 139 140 /** 141 * trace_event_set_state_dynamic: 142 * 143 * Set the dynamic tracing state of an event. 144 * 145 * Pre-condition: trace_event_get_state_static(ev) == true 146 */ 147 static void trace_event_set_state_dynamic(TraceEvent *ev, bool state); 148 149 150 151 /** 152 * trace_init_backends: 153 * @file: Name of trace output file; may be NULL. 154 * Corresponds to commandline option "-trace file=...". 155 * 156 * Initialize the tracing backend. 157 * 158 * Returns: Whether the backends could be successfully initialized. 159 */ 160 bool trace_init_backends(void); 161 162 /** 163 * trace_init_events: 164 * @events: Name of file with events to be enabled at startup; may be NULL. 165 * Corresponds to commandline option "-trace events=...". 166 * 167 * Read the list of enabled tracing events. 168 * 169 * Returns: Whether the backends could be successfully initialized. 170 */ 171 void trace_init_events(const char *file); 172 173 /** 174 * trace_init_file: 175 * @file: Name of trace output file; may be NULL. 176 * Corresponds to commandline option "-trace file=...". 177 * 178 * Record the name of the output file for the tracing backend. 179 * Exits if no selected backend does not support specifying the 180 * output file, and a non-NULL file was passed. 181 */ 182 void trace_init_file(const char *file); 183 184 /** 185 * trace_list_events: 186 * 187 * List all available events. 188 */ 189 void trace_list_events(void); 190 191 /** 192 * trace_enable_events: 193 * @line_buf: A string with a glob pattern of events to be enabled or, 194 * if the string starts with '-', disabled. 195 * 196 * Enable or disable matching events. 197 */ 198 void trace_enable_events(const char *line_buf); 199 200 201 #include "trace/control-internal.h" 202 203 #endif /* TRACE__CONTROL_H */ 204