LXR qemu/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 "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 */
  26enum 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 */
  42static 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 */
  52TraceEvent *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 */
  63TraceEvent *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 */
  70static bool trace_event_is_pattern(const char *str);
  71
  72/**
  73 * trace_event_count:
  74 *
  75 * Return the number of events.
  76 */
  77static TraceEventID trace_event_count(void);
  78
  79
  80
  81/**
  82 * trace_event_get_id:
  83 *
  84 * Get the identifier of an event.
  85 */
  86static TraceEventID trace_event_get_id(TraceEvent *ev);
  87
  88/**
  89 * trace_event_get_name:
  90 *
  91 * Get the name of an event.
  92 */
  93static 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 */
 118static 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 */
 125static 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 */
 147static 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 */
 160bool 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 */
 171void 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 */
 182void trace_init_file(const char *file);
 183
 184/**
 185 * trace_list_events:
 186 *
 187 * List all available events.
 188 */
 189void 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 */
 198void trace_enable_events(const char *line_buf);
 199
 200
 201#include "trace/control-internal.h"
 202
 203#endif  /* TRACE__CONTROL_H */
 204