Expose all EventLog events as DTrace probes
[ghc.git] / rts / Trace.h
1 /* -----------------------------------------------------------------------------
2 *
3 * (c) The GHC Team, 2008-2009
4 *
5 * Support for fast binary event logging and user-space dtrace probes.
6 *
7 * ---------------------------------------------------------------------------*/
8
9 #ifndef TRACE_H
10 #define TRACE_H
11
12 #include "rts/EventLogFormat.h"
13 #include "Capability.h"
14
15 #if defined(DTRACE)
16 #include "RtsProbes.h"
17 #endif /* defined(DTRACE) */
18
19 BEGIN_RTS_PRIVATE
20
21 // -----------------------------------------------------------------------------
22 // EventLog API
23 // -----------------------------------------------------------------------------
24
25 #if defined(TRACING)
26
27 void initTracing (void);
28 void endTracing (void);
29 void freeTracing (void);
30
31 #endif /* TRACING */
32
33 // -----------------------------------------------------------------------------
34 // Message classes
35 // -----------------------------------------------------------------------------
36
37 // debugging flags, set with +RTS -D<something>
38 extern int DEBUG_sched;
39 extern int DEBUG_interp;
40 extern int DEBUG_weak;
41 extern int DEBUG_gccafs;
42 extern int DEBUG_gc;
43 extern int DEBUG_block_alloc;
44 extern int DEBUG_sanity;
45 extern int DEBUG_stable;
46 extern int DEBUG_stm;
47 extern int DEBUG_prof;
48 extern int DEBUG_gran;
49 extern int DEBUG_par;
50 extern int DEBUG_linker;
51 extern int DEBUG_squeeze;
52 extern int DEBUG_hpc;
53 extern int DEBUG_sparks;
54
55 // events
56 extern int TRACE_sched;
57
58 // -----------------------------------------------------------------------------
59 // Posting events
60 //
61 // We use macros rather than inline functions deliberately. We want
62 // the not-taken case to be as efficient as possible, a simple
63 // test-and-jump, and with inline functions gcc seemed to move some of
64 // the instructions from the branch up before the test.
65 //
66 // -----------------------------------------------------------------------------
67
68 #ifdef DEBUG
69 void traceBegin (const char *str, ...);
70 void traceEnd (void);
71 #endif
72
73 #ifdef TRACING
74
75 /*
76 * Record a scheduler event
77 */
78 #define traceSchedEvent(cap, tag, tso, other) \
79 if (RTS_UNLIKELY(TRACE_sched)) { \
80 traceSchedEvent_(cap, tag, tso, other); \
81 }
82
83 void traceSchedEvent_ (Capability *cap, EventTypeNum tag,
84 StgTSO *tso, StgWord64 other);
85
86
87 /*
88 * Record a nullary event
89 */
90 #define traceEvent(cap, tag) \
91 if (RTS_UNLIKELY(TRACE_sched)) { \
92 traceEvent_(cap, tag); \
93 }
94
95 void traceEvent_ (Capability *cap, EventTypeNum tag);
96
97 // variadic macros are C99, and supported by gcc. However, the
98 // ##__VA_ARGS syntax is a gcc extension, which allows the variable
99 // argument list to be empty (see gcc docs for details).
100
101 /*
102 * Emit a trace message on a particular Capability
103 */
104 #define traceCap(class, cap, msg, ...) \
105 if (RTS_UNLIKELY(class)) { \
106 traceCap_(cap, msg, ##__VA_ARGS__); \
107 }
108
109 void traceCap_(Capability *cap, char *msg, ...);
110
111 /*
112 * Emit a trace message
113 */
114 #define trace(class, msg, ...) \
115 if (RTS_UNLIKELY(class)) { \
116 trace_(msg, ##__VA_ARGS__); \
117 }
118
119 void trace_(char *msg, ...);
120
121 /*
122 * A message or event emitted by the program
123 */
124 void traceUserMsg(Capability *cap, char *msg);
125
126 /*
127 * Emit a debug message (only when DEBUG is defined)
128 */
129 #ifdef DEBUG
130 #define debugTrace(class, msg, ...) \
131 if (RTS_UNLIKELY(class)) { \
132 trace_(msg, ##__VA_ARGS__); \
133 }
134 #else
135 #define debugTrace(class, str, ...) /* nothing */
136 #endif
137
138 /*
139 * Emit a message/event describing the state of a thread
140 */
141 #define traceThreadStatus(class, tso) \
142 if (RTS_UNLIKELY(class)) { \
143 traceThreadStatus_(tso); \
144 }
145
146 void traceThreadStatus_ (StgTSO *tso);
147
148 #else /* !TRACING */
149
150 #define traceSchedEvent(cap, tag, tso, other) /* nothing */
151 #define traceEvent(cap, tag) /* nothing */
152 #define traceCap(class, cap, msg, ...) /* nothing */
153 #define trace(class, msg, ...) /* nothing */
154 #define debugTrace(class, str, ...) /* nothing */
155 #define traceThreadStatus(class, tso) /* nothing */
156
157 #endif /* TRACING */
158
159 // If DTRACE is enabled, but neither DEBUG nor TRACING, we need a C land
160 // wrapper for the user-msg probe (as we can't expand that in PrimOps.cmm)
161 //
162 #if !defined(DEBUG) && !defined(TRACING) && defined(DTRACE)
163
164 void dtraceUserMsgWrapper(Capability *cap, char *msg);
165
166 #endif /* !defined(DEBUG) && !defined(TRACING) && defined(DTRACE) */
167
168 // -----------------------------------------------------------------------------
169 // Aliases for static dtrace probes if dtrace is available
170 // -----------------------------------------------------------------------------
171
172 #if defined(DTRACE)
173
174 #define dtraceCreateThread(cap, tid) \
175 HASKELLEVENT_CREATE_THREAD(cap, tid)
176 #define dtraceRunThread(cap, tid) \
177 HASKELLEVENT_RUN_THREAD(cap, tid)
178 #define dtraceStopThread(cap, tid, status) \
179 HASKELLEVENT_STOP_THREAD(cap, tid, status)
180 #define dtraceThreadRunnable(cap, tid) \
181 HASKELLEVENT_THREAD_RUNNABLE(cap, tid)
182 #define dtraceMigrateThread(cap, tid, new_cap) \
183 HASKELLEVENT_MIGRATE_THREAD(cap, tid, new_cap)
184 #define dtraceRunSpark(cap, tid) \
185 HASKELLEVENT_RUN_SPARK(cap, tid)
186 #define dtraceStealSpark(cap, tid, victim_cap) \
187 HASKELLEVENT_STEAL_SPARK(cap, tid, victim_cap)
188 #define dtraceShutdown(cap) \
189 HASKELLEVENT_SHUTDOWN(cap)
190 #define dtraceThreadWakeup(cap, tid, other_cap) \
191 HASKELLEVENT_THREAD_WAKEUP(cap, tid, other_cap)
192 #define dtraceGcStart(cap) \
193 HASKELLEVENT_GC_START(cap)
194 #define dtraceGcEnd(cap) \
195 HASKELLEVENT_GC_END(cap)
196 #define dtraceRequestSeqGc(cap) \
197 HASKELLEVENT_REQUEST_SEQ_GC(cap)
198 #define dtraceRequestParGc(cap) \
199 HASKELLEVENT_REQUEST_PAR_GC(cap)
200 #define dtraceCreateSparkThread(cap, spark_tid) \
201 HASKELLEVENT_CREATE_SPARK_THREAD(cap, spark_tid)
202 #define dtraceStartup(num_caps) \
203 HASKELLEVENT_STARTUP(num_caps)
204 #define dtraceUserMsg(cap, msg) \
205 HASKELLEVENT_USER_MSG(cap, msg)
206 #define dtraceGcIdle(cap) \
207 HASKELLEVENT_GC_IDLE(cap)
208 #define dtraceGcWork(cap) \
209 HASKELLEVENT_GC_WORK(cap)
210 #define dtraceGcDone(cap) \
211 HASKELLEVENT_GC_DONE(cap)
212
213 #else /* !defined(DTRACE) */
214
215 #define dtraceCreateThread(cap, tid) /* nothing */
216 #define dtraceRunThread(cap, tid) /* nothing */
217 #define dtraceStopThread(cap, tid, status) /* nothing */
218 #define dtraceThreadRunnable(cap, tid) /* nothing */
219 #define dtraceMigrateThread(cap, tid, new_cap) /* nothing */
220 #define dtraceRunSpark(cap, tid) /* nothing */
221 #define dtraceStealSpark(cap, tid, victim_cap) /* nothing */
222 #define dtraceShutdown(cap) /* nothing */
223 #define dtraceThreadWakeup(cap, tid, other_cap) /* nothing */
224 #define dtraceGcStart(cap) /* nothing */
225 #define dtraceGcEnd(cap) /* nothing */
226 #define dtraceRequestSeqGc(cap) /* nothing */
227 #define dtraceRequestParGc(cap) /* nothing */
228 #define dtraceCreateSparkThread(cap, spark_tid) /* nothing */
229 #define dtraceStartup(num_caps) /* nothing */
230 #define dtraceUserMsg(cap, msg) /* nothing */
231 #define dtraceGcIdle(cap) /* nothing */
232 #define dtraceGcWork(cap) /* nothing */
233 #define dtraceGcDone(cap) /* nothing */
234
235 #endif
236
237 // -----------------------------------------------------------------------------
238 // Trace probes dispatching to various tracing frameworks
239 //
240 // In order to avoid accumulating multiple calls to tracing calls at trace
241 // points, we define inline probe functions that contain the various
242 // invocations.
243 //
244 // Dtrace - dtrace probes are unconditionally added as probe activation is
245 // handled by the dtrace component of the kernel, and inactive probes are
246 // very cheap — usually, one no-op. Consequently, dtrace can be used with
247 // all flavours of the RTS. In addition, we still support logging events to
248 // a file, even in the presence of dtrace. This is, eg, useful when tracing
249 // on a server, but browsing trace information with ThreadScope on a local
250 // client.
251 //
252 // -----------------------------------------------------------------------------
253
254 INLINE_HEADER void traceEventCreateThread(Capability *cap STG_UNUSED,
255 StgTSO *tso STG_UNUSED)
256 {
257 traceSchedEvent(cap, EVENT_CREATE_THREAD, tso, tso->stack_size);
258 dtraceCreateThread((EventCapNo)cap->no, (EventThreadID)tso->id);
259 }
260
261 INLINE_HEADER void traceEventRunThread(Capability *cap STG_UNUSED,
262 StgTSO *tso STG_UNUSED)
263 {
264 traceSchedEvent(cap, EVENT_RUN_THREAD, tso, tso->what_next);
265 dtraceRunThread((EventCapNo)cap->no, (EventThreadID)tso->id);
266 }
267
268 INLINE_HEADER void traceEventStopThread(Capability *cap STG_UNUSED,
269 StgTSO *tso STG_UNUSED,
270 StgThreadReturnCode status STG_UNUSED)
271 {
272 traceSchedEvent(cap, EVENT_STOP_THREAD, tso, status);
273 dtraceStopThread((EventCapNo)cap->no, (EventThreadID)tso->id,
274 (EventThreadStatus)status);
275 }
276
277 // needs to be EXTERN_INLINE as it is used in another EXTERN_INLINE function
278 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
279 StgTSO *tso STG_UNUSED);
280
281 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
282 StgTSO *tso STG_UNUSED)
283 {
284 traceSchedEvent(cap, EVENT_THREAD_RUNNABLE, tso, 0);
285 dtraceThreadRunnable((EventCapNo)cap->no, (EventThreadID)tso->id);
286 }
287
288 INLINE_HEADER void traceEventMigrateThread(Capability *cap STG_UNUSED,
289 StgTSO *tso STG_UNUSED,
290 nat new_cap STG_UNUSED)
291 {
292 traceSchedEvent(cap, EVENT_MIGRATE_THREAD, tso, new_cap);
293 dtraceMigrateThread((EventCapNo)cap->no, (EventThreadID)tso->id,
294 (EventCapNo)new_cap);
295 }
296
297 INLINE_HEADER void traceEventRunSpark(Capability *cap STG_UNUSED,
298 StgTSO *tso STG_UNUSED)
299 {
300 traceSchedEvent(cap, EVENT_RUN_SPARK, tso, 0);
301 dtraceRunSpark((EventCapNo)cap->no, (EventThreadID)tso->id);
302 }
303
304 INLINE_HEADER void traceEventStealSpark(Capability *cap STG_UNUSED,
305 StgTSO *tso STG_UNUSED,
306 nat victim_cap STG_UNUSED)
307 {
308 traceSchedEvent(cap, EVENT_STEAL_SPARK, tso, victim_cap);
309 dtraceStealSpark((EventCapNo)cap->no, (EventThreadID)tso->id,
310 (EventCapNo)victim_cap);
311 }
312
313 INLINE_HEADER void traceEventShutdown(Capability *cap STG_UNUSED)
314 {
315 traceSchedEvent(cap, EVENT_SHUTDOWN, 0, 0);
316 dtraceShutdown((EventCapNo)cap->no);
317 }
318
319 INLINE_HEADER void traceEventThreadWakeup(Capability *cap STG_UNUSED,
320 StgTSO *tso STG_UNUSED,
321 nat other_cap STG_UNUSED)
322 {
323 traceSchedEvent(cap, EVENT_THREAD_WAKEUP, tso, other_cap);
324 dtraceThreadWakeup((EventCapNo)cap->no, (EventThreadID)tso->id,
325 (EventCapNo)other_cap);
326 }
327
328 INLINE_HEADER void traceEventGcStart(Capability *cap STG_UNUSED)
329 {
330 traceSchedEvent(cap, EVENT_GC_START, 0, 0);
331 dtraceGcStart((EventCapNo)cap->no);
332 }
333
334 INLINE_HEADER void traceEventGcEnd(Capability *cap STG_UNUSED)
335 {
336 traceSchedEvent(cap, EVENT_GC_END, 0, 0);
337 dtraceGcEnd((EventCapNo)cap->no);
338 }
339
340 INLINE_HEADER void traceEventRequestSeqGc(Capability *cap STG_UNUSED)
341 {
342 traceSchedEvent(cap, EVENT_REQUEST_SEQ_GC, 0, 0);
343 dtraceRequestSeqGc((EventCapNo)cap->no);
344 }
345
346 INLINE_HEADER void traceEventRequestParGc(Capability *cap STG_UNUSED)
347 {
348 traceSchedEvent(cap, EVENT_REQUEST_PAR_GC, 0, 0);
349 dtraceRequestParGc((EventCapNo)cap->no);
350 }
351
352 INLINE_HEADER void traceEventCreateSparkThread(Capability *cap STG_UNUSED,
353 StgThreadID spark_tid STG_UNUSED)
354 {
355 traceSchedEvent(cap, EVENT_CREATE_SPARK_THREAD, 0, spark_tid);
356 dtraceCreateSparkThread((EventCapNo)cap->no, (EventThreadID)spark_tid);
357 }
358
359 // This applies only to dtrace as EVENT_STARTUP in the logging framework is
360 // handled specially in 'EventLog.c'.
361 //
362 INLINE_HEADER void dtraceEventStartup(void)
363 {
364 #ifdef THREADED_RTS
365 // XXX n_capabilities hasn't been initislised yet
366 dtraceStartup(RtsFlags.ParFlags.nNodes);
367 #else
368 dtraceStartup(1);
369 #endif
370 }
371
372 INLINE_HEADER void traceEventGcIdle(Capability *cap STG_UNUSED)
373 {
374 traceEvent(cap, EVENT_GC_IDLE);
375 dtraceGcIdle((EventCapNo)cap->no);
376 }
377
378 INLINE_HEADER void traceEventGcWork(Capability *cap STG_UNUSED)
379 {
380 traceEvent(cap, EVENT_GC_WORK);
381 dtraceGcWork((EventCapNo)cap->no);
382 }
383
384 INLINE_HEADER void traceEventGcDone(Capability *cap STG_UNUSED)
385 {
386 traceEvent(cap, EVENT_GC_DONE);
387 dtraceGcDone((EventCapNo)cap->no);
388 }
389
390 END_RTS_PRIVATE
391
392 #endif /* TRACE_H */