trace/control.h

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