xref: /openbmc/qemu/trace/control.h (revision bfb27e60) 
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(trace_event_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_print_events:
153  *
154  * Print the state of all events.
155  */
156 void trace_print_events(FILE *stream, fprintf_function stream_printf);
157 
158 /**
159  * trace_init_backends:
160  * @events: Name of file with events to be enabled at startup; may be NULL.
161  *          Corresponds to commandline option "-trace events=...".
162  * @file:   Name of trace output file; may be NULL.
163  *          Corresponds to commandline option "-trace file=...".
164  *
165  * Initialize the tracing backend.
166  *
167  * Returns: Whether the backends could be successfully initialized.
168  */
169 bool trace_init_backends(const char *events, const char *file);
170 
171 
172 #include "trace/control-internal.h"
173 
174 #endif  /* TRACE__CONTROL_H */
175