910afbdaf80bf4744a99874f1932b1333614d829
[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 #include "BeginPrivate.h"
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 void resetTracing (void);
31
32 #endif /* TRACING */
33
34 typedef StgWord32 CapsetID;
35 typedef StgWord16 CapsetType;
36 enum CapsetType { CapsetTypeCustom = CAPSET_TYPE_CUSTOM,
37 CapsetTypeOsProcess = CAPSET_TYPE_OSPROCESS,
38 CapsetTypeClockdomain = CAPSET_TYPE_CLOCKDOMAIN };
39 #define CAPSET_OSPROCESS_DEFAULT 0
40
41 // -----------------------------------------------------------------------------
42 // Message classes
43 // -----------------------------------------------------------------------------
44
45 // debugging flags, set with +RTS -D<something>
46 extern int DEBUG_sched;
47 extern int DEBUG_interp;
48 extern int DEBUG_weak;
49 extern int DEBUG_gccafs;
50 extern int DEBUG_gc;
51 extern int DEBUG_block_alloc;
52 extern int DEBUG_sanity;
53 extern int DEBUG_stable;
54 extern int DEBUG_stm;
55 extern int DEBUG_prof;
56 extern int DEBUG_gran;
57 extern int DEBUG_par;
58 extern int DEBUG_linker;
59 extern int DEBUG_squeeze;
60 extern int DEBUG_hpc;
61 extern int DEBUG_sparks;
62
63 // events
64 extern int TRACE_sched;
65
66 // -----------------------------------------------------------------------------
67 // Posting events
68 //
69 // We use macros rather than inline functions deliberately. We want
70 // the not-taken case to be as efficient as possible, a simple
71 // test-and-jump, and with inline functions gcc seemed to move some of
72 // the instructions from the branch up before the test.
73 //
74 // -----------------------------------------------------------------------------
75
76 #ifdef DEBUG
77 void traceBegin (const char *str, ...);
78 void traceEnd (void);
79 #endif
80
81 #ifdef TRACING
82
83 /*
84 * Record a scheduler event
85 */
86 #define traceSchedEvent(cap, tag, tso, other) \
87 if (RTS_UNLIKELY(TRACE_sched)) { \
88 traceSchedEvent_(cap, tag, tso, other, 0); \
89 }
90
91 #define traceSchedEvent2(cap, tag, tso, info1, info2) \
92 if (RTS_UNLIKELY(TRACE_sched)) { \
93 traceSchedEvent_(cap, tag, tso, info1, info2); \
94 }
95
96 void traceSchedEvent_ (Capability *cap, EventTypeNum tag,
97 StgTSO *tso, StgWord info1, StgWord info2);
98
99
100 /*
101 * Record a nullary event
102 */
103 #define traceEvent(cap, tag) \
104 if (RTS_UNLIKELY(TRACE_sched)) { \
105 traceEvent_(cap, tag); \
106 }
107
108 void traceEvent_ (Capability *cap, EventTypeNum tag);
109
110 // variadic macros are C99, and supported by gcc. However, the
111 // ##__VA_ARGS syntax is a gcc extension, which allows the variable
112 // argument list to be empty (see gcc docs for details).
113
114 /*
115 * Emit a trace message on a particular Capability
116 */
117 #define traceCap(class, cap, msg, ...) \
118 if (RTS_UNLIKELY(class)) { \
119 traceCap_(cap, msg, ##__VA_ARGS__); \
120 }
121
122 void traceCap_(Capability *cap, char *msg, ...);
123
124 /*
125 * Emit a trace message
126 */
127 #define trace(class, msg, ...) \
128 if (RTS_UNLIKELY(class)) { \
129 trace_(msg, ##__VA_ARGS__); \
130 }
131
132 void trace_(char *msg, ...);
133
134 /*
135 * A message or event emitted by the program
136 */
137 void traceUserMsg(Capability *cap, char *msg);
138
139 /*
140 * Emit a debug message (only when DEBUG is defined)
141 */
142 #ifdef DEBUG
143 #define debugTrace(class, msg, ...) \
144 if (RTS_UNLIKELY(class)) { \
145 trace_(msg, ##__VA_ARGS__); \
146 }
147 #else
148 #define debugTrace(class, str, ...) /* nothing */
149 #endif
150
151 #ifdef DEBUG
152 #define debugTraceCap(class, cap, msg, ...) \
153 if (RTS_UNLIKELY(class)) { \
154 traceCap_(cap, msg, ##__VA_ARGS__); \
155 }
156 #else
157 #define debugTraceCap(class, cap, str, ...) /* nothing */
158 #endif
159
160 /*
161 * Emit a message/event describing the state of a thread
162 */
163 #define traceThreadStatus(class, tso) \
164 if (RTS_UNLIKELY(class)) { \
165 traceThreadStatus_(tso); \
166 }
167
168 void traceThreadStatus_ (StgTSO *tso);
169
170 void traceEventStartup_ (int n_caps);
171
172 /*
173 * Events for describing capability sets in the eventlog
174 *
175 * Note: unlike other events, these are not conditional on TRACE_sched or
176 * similar because they are not "real" events themselves but provide
177 * information and context for other "real" events. Other events depend on
178 * the capset info events so for simplicity, rather than working out if
179 * they're necessary we always emit them. They should be very low volume.
180 */
181 void traceCapsetModify_ (EventTypeNum tag,
182 CapsetID capset,
183 StgWord32 other);
184
185 void traceOSProcessInfo_ (void);
186
187 void traceSparkCounters_ (Capability *cap,
188 SparkCounters counters,
189 StgWord remaining);
190
191 #else /* !TRACING */
192
193 #define traceSchedEvent(cap, tag, tso, other) /* nothing */
194 #define traceSchedEvent2(cap, tag, tso, other, info) /* nothing */
195 #define traceEvent(cap, tag) /* nothing */
196 #define traceCap(class, cap, msg, ...) /* nothing */
197 #define trace(class, msg, ...) /* nothing */
198 #define debugTrace(class, str, ...) /* nothing */
199 #define debugTraceCap(class, cap, str, ...) /* nothing */
200 #define traceThreadStatus(class, tso) /* nothing */
201 INLINE_HEADER void traceEventStartup_ (int n_caps STG_UNUSED) {};
202 #define traceCapsetModify_(tag, capset, other) /* nothing */
203 #define traceOSProcessInfo_() /* nothing */
204 #define traceSparkCounters_(cap, counters, remaining) /* nothing */
205
206 #endif /* TRACING */
207
208 // If DTRACE is enabled, but neither DEBUG nor TRACING, we need a C land
209 // wrapper for the user-msg probe (as we can't expand that in PrimOps.cmm)
210 //
211 #if !defined(DEBUG) && !defined(TRACING) && defined(DTRACE)
212
213 void dtraceUserMsgWrapper(Capability *cap, char *msg);
214
215 #endif /* !defined(DEBUG) && !defined(TRACING) && defined(DTRACE) */
216
217 // -----------------------------------------------------------------------------
218 // Aliases for static dtrace probes if dtrace is available
219 // -----------------------------------------------------------------------------
220
221 #if defined(DTRACE)
222
223 #define dtraceCreateThread(cap, tid) \
224 HASKELLEVENT_CREATE_THREAD(cap, tid)
225 #define dtraceRunThread(cap, tid) \
226 HASKELLEVENT_RUN_THREAD(cap, tid)
227 #define dtraceStopThread(cap, tid, status, info) \
228 HASKELLEVENT_STOP_THREAD(cap, tid, status, info)
229 #define dtraceThreadRunnable(cap, tid) \
230 HASKELLEVENT_THREAD_RUNNABLE(cap, tid)
231 #define dtraceMigrateThread(cap, tid, new_cap) \
232 HASKELLEVENT_MIGRATE_THREAD(cap, tid, new_cap)
233 #define dtraceRunSpark(cap, tid) \
234 HASKELLEVENT_RUN_SPARK(cap, tid)
235 #define dtraceStealSpark(cap, tid, victim_cap) \
236 HASKELLEVENT_STEAL_SPARK(cap, tid, victim_cap)
237 #define dtraceShutdown(cap) \
238 HASKELLEVENT_SHUTDOWN(cap)
239 #define dtraceThreadWakeup(cap, tid, other_cap) \
240 HASKELLEVENT_THREAD_WAKEUP(cap, tid, other_cap)
241 #define dtraceGcStart(cap) \
242 HASKELLEVENT_GC_START(cap)
243 #define dtraceGcEnd(cap) \
244 HASKELLEVENT_GC_END(cap)
245 #define dtraceRequestSeqGc(cap) \
246 HASKELLEVENT_REQUEST_SEQ_GC(cap)
247 #define dtraceRequestParGc(cap) \
248 HASKELLEVENT_REQUEST_PAR_GC(cap)
249 #define dtraceCreateSparkThread(cap, spark_tid) \
250 HASKELLEVENT_CREATE_SPARK_THREAD(cap, spark_tid)
251 INLINE_HEADER void dtraceStartup (int num_caps) {
252 HASKELLEVENT_STARTUP(num_caps);
253 }
254 #define dtraceUserMsg(cap, msg) \
255 HASKELLEVENT_USER_MSG(cap, msg)
256 #define dtraceGcIdle(cap) \
257 HASKELLEVENT_GC_IDLE(cap)
258 #define dtraceGcWork(cap) \
259 HASKELLEVENT_GC_WORK(cap)
260 #define dtraceGcDone(cap) \
261 HASKELLEVENT_GC_DONE(cap)
262 #define dtraceCapsetCreate(capset, capset_type) \
263 HASKELLEVENT_CAPSET_CREATE(capset, capset_type)
264 #define dtraceCapsetDelete(capset) \
265 HASKELLEVENT_CAPSET_DELETE(capset)
266 #define dtraceCapsetAssignCap(capset, capno) \
267 HASKELLEVENT_CAPSET_ASSIGN_CAP(capset, capno)
268 #define dtraceCapsetRemoveCap(capset, capno) \
269 HASKELLEVENT_CAPSET_REMOVE_CAP(capset, capno)
270 #define dtraceSparkCounters(cap, a, b, c, d, e, f, g) \
271 HASKELLEVENT_SPARK_COUNTERS(cap, a, b, c, d, e, f, g)
272
273 #else /* !defined(DTRACE) */
274
275 #define dtraceCreateThread(cap, tid) /* nothing */
276 #define dtraceRunThread(cap, tid) /* nothing */
277 #define dtraceStopThread(cap, tid, status, info) /* nothing */
278 #define dtraceThreadRunnable(cap, tid) /* nothing */
279 #define dtraceMigrateThread(cap, tid, new_cap) /* nothing */
280 #define dtraceRunSpark(cap, tid) /* nothing */
281 #define dtraceStealSpark(cap, tid, victim_cap) /* nothing */
282 #define dtraceShutdown(cap) /* nothing */
283 #define dtraceThreadWakeup(cap, tid, other_cap) /* nothing */
284 #define dtraceGcStart(cap) /* nothing */
285 #define dtraceGcEnd(cap) /* nothing */
286 #define dtraceRequestSeqGc(cap) /* nothing */
287 #define dtraceRequestParGc(cap) /* nothing */
288 #define dtraceCreateSparkThread(cap, spark_tid) /* nothing */
289 INLINE_HEADER void dtraceStartup (int num_caps STG_UNUSED) {};
290 #define dtraceUserMsg(cap, msg) /* nothing */
291 #define dtraceGcIdle(cap) /* nothing */
292 #define dtraceGcWork(cap) /* nothing */
293 #define dtraceGcDone(cap) /* nothing */
294 #define dtraceCapsetCreate(capset, capset_type) /* nothing */
295 #define dtraceCapsetDelete(capset) /* nothing */
296 #define dtraceCapsetAssignCap(capset, capno) /* nothing */
297 #define dtraceCapsetRemoveCap(capset, capno) /* nothing */
298 #define dtraceSparkCounters(cap, a, b, c, d, e, f, g) /* nothing */
299
300 #endif
301
302 // -----------------------------------------------------------------------------
303 // Trace probes dispatching to various tracing frameworks
304 //
305 // In order to avoid accumulating multiple calls to tracing calls at trace
306 // points, we define inline probe functions that contain the various
307 // invocations.
308 //
309 // Dtrace - dtrace probes are unconditionally added as probe activation is
310 // handled by the dtrace component of the kernel, and inactive probes are
311 // very cheap — usually, one no-op. Consequently, dtrace can be used with
312 // all flavours of the RTS. In addition, we still support logging events to
313 // a file, even in the presence of dtrace. This is, eg, useful when tracing
314 // on a server, but browsing trace information with ThreadScope on a local
315 // client.
316 //
317 // -----------------------------------------------------------------------------
318
319 INLINE_HEADER void traceEventCreateThread(Capability *cap STG_UNUSED,
320 StgTSO *tso STG_UNUSED)
321 {
322 traceSchedEvent(cap, EVENT_CREATE_THREAD, tso, tso->stackobj->stack_size);
323 dtraceCreateThread((EventCapNo)cap->no, (EventThreadID)tso->id);
324 }
325
326 INLINE_HEADER void traceEventRunThread(Capability *cap STG_UNUSED,
327 StgTSO *tso STG_UNUSED)
328 {
329 traceSchedEvent(cap, EVENT_RUN_THREAD, tso, tso->what_next);
330 dtraceRunThread((EventCapNo)cap->no, (EventThreadID)tso->id);
331 }
332
333 INLINE_HEADER void traceEventStopThread(Capability *cap STG_UNUSED,
334 StgTSO *tso STG_UNUSED,
335 StgThreadReturnCode status STG_UNUSED,
336 StgWord32 info STG_UNUSED)
337 {
338 traceSchedEvent2(cap, EVENT_STOP_THREAD, tso, status, info);
339 dtraceStopThread((EventCapNo)cap->no, (EventThreadID)tso->id,
340 (EventThreadStatus)status, (EventThreadID)info);
341 }
342
343 // needs to be EXTERN_INLINE as it is used in another EXTERN_INLINE function
344 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
345 StgTSO *tso STG_UNUSED);
346
347 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
348 StgTSO *tso STG_UNUSED)
349 {
350 traceSchedEvent(cap, EVENT_THREAD_RUNNABLE, tso, 0);
351 dtraceThreadRunnable((EventCapNo)cap->no, (EventThreadID)tso->id);
352 }
353
354 INLINE_HEADER void traceEventMigrateThread(Capability *cap STG_UNUSED,
355 StgTSO *tso STG_UNUSED,
356 nat new_cap STG_UNUSED)
357 {
358 traceSchedEvent(cap, EVENT_MIGRATE_THREAD, tso, new_cap);
359 dtraceMigrateThread((EventCapNo)cap->no, (EventThreadID)tso->id,
360 (EventCapNo)new_cap);
361 }
362
363 INLINE_HEADER void traceEventShutdown(Capability *cap STG_UNUSED)
364 {
365 traceSchedEvent(cap, EVENT_SHUTDOWN, 0, 0);
366 dtraceShutdown((EventCapNo)cap->no);
367 }
368
369 INLINE_HEADER void traceEventThreadWakeup(Capability *cap STG_UNUSED,
370 StgTSO *tso STG_UNUSED,
371 nat other_cap STG_UNUSED)
372 {
373 traceSchedEvent(cap, EVENT_THREAD_WAKEUP, tso, other_cap);
374 dtraceThreadWakeup((EventCapNo)cap->no, (EventThreadID)tso->id,
375 (EventCapNo)other_cap);
376 }
377
378 INLINE_HEADER void traceEventGcStart(Capability *cap STG_UNUSED)
379 {
380 traceSchedEvent(cap, EVENT_GC_START, 0, 0);
381 dtraceGcStart((EventCapNo)cap->no);
382 }
383
384 INLINE_HEADER void traceEventGcEnd(Capability *cap STG_UNUSED)
385 {
386 traceSchedEvent(cap, EVENT_GC_END, 0, 0);
387 dtraceGcEnd((EventCapNo)cap->no);
388 }
389
390 INLINE_HEADER void traceEventRequestSeqGc(Capability *cap STG_UNUSED)
391 {
392 traceSchedEvent(cap, EVENT_REQUEST_SEQ_GC, 0, 0);
393 dtraceRequestSeqGc((EventCapNo)cap->no);
394 }
395
396 INLINE_HEADER void traceEventRequestParGc(Capability *cap STG_UNUSED)
397 {
398 traceSchedEvent(cap, EVENT_REQUEST_PAR_GC, 0, 0);
399 dtraceRequestParGc((EventCapNo)cap->no);
400 }
401
402 INLINE_HEADER void traceEventRunSpark(Capability *cap STG_UNUSED,
403 StgTSO *tso STG_UNUSED)
404 {
405 traceSchedEvent(cap, EVENT_RUN_SPARK, tso, 0);
406 dtraceRunSpark((EventCapNo)cap->no, (EventThreadID)tso->id);
407 }
408
409 INLINE_HEADER void traceEventStealSpark(Capability *cap STG_UNUSED,
410 StgTSO *tso STG_UNUSED,
411 nat victim_cap STG_UNUSED)
412 {
413 traceSchedEvent(cap, EVENT_STEAL_SPARK, tso, victim_cap);
414 dtraceStealSpark((EventCapNo)cap->no, (EventThreadID)tso->id,
415 (EventCapNo)victim_cap);
416 }
417
418 INLINE_HEADER void traceEventCreateSparkThread(Capability *cap STG_UNUSED,
419 StgThreadID spark_tid STG_UNUSED)
420 {
421 traceSchedEvent(cap, EVENT_CREATE_SPARK_THREAD, 0, spark_tid);
422 dtraceCreateSparkThread((EventCapNo)cap->no, (EventThreadID)spark_tid);
423 }
424
425 INLINE_HEADER void traceEventStartup(void)
426 {
427 int n_caps;
428 #ifdef THREADED_RTS
429 // XXX n_capabilities hasn't been initialised yet
430 n_caps = RtsFlags.ParFlags.nNodes;
431 #else
432 n_caps = 1;
433 #endif
434
435 traceEventStartup_(n_caps);
436 dtraceStartup(n_caps);
437 }
438
439 INLINE_HEADER void traceEventGcIdle(Capability *cap STG_UNUSED)
440 {
441 traceEvent(cap, EVENT_GC_IDLE);
442 dtraceGcIdle((EventCapNo)cap->no);
443 }
444
445 INLINE_HEADER void traceEventGcWork(Capability *cap STG_UNUSED)
446 {
447 traceEvent(cap, EVENT_GC_WORK);
448 dtraceGcWork((EventCapNo)cap->no);
449 }
450
451 INLINE_HEADER void traceEventGcDone(Capability *cap STG_UNUSED)
452 {
453 traceEvent(cap, EVENT_GC_DONE);
454 dtraceGcDone((EventCapNo)cap->no);
455 }
456
457 INLINE_HEADER void traceCapsetCreate(CapsetID capset STG_UNUSED,
458 CapsetType capset_type STG_UNUSED)
459 {
460 traceCapsetModify_(EVENT_CAPSET_CREATE, capset, capset_type);
461 dtraceCapsetCreate(capset, capset_type);
462 }
463
464 INLINE_HEADER void traceCapsetDelete(CapsetID capset STG_UNUSED)
465 {
466 traceCapsetModify_(EVENT_CAPSET_DELETE, capset, 0);
467 dtraceCapsetDelete(capset);
468 }
469
470 INLINE_HEADER void traceCapsetAssignCap(CapsetID capset STG_UNUSED,
471 nat capno STG_UNUSED)
472 {
473 traceCapsetModify_(EVENT_CAPSET_ASSIGN_CAP, capset, capno);
474 dtraceCapsetAssignCap(capset, capno);
475 }
476
477 INLINE_HEADER void traceCapsetRemoveCap(CapsetID capset STG_UNUSED,
478 nat capno STG_UNUSED)
479 {
480 traceCapsetModify_(EVENT_CAPSET_REMOVE_CAP, capset, capno);
481 dtraceCapsetRemoveCap(capset, capno);
482 }
483
484 INLINE_HEADER void traceOSProcessInfo(void)
485 {
486 traceOSProcessInfo_();
487 /* Note: no DTrace equivalent because all this OS process info
488 * is available to DTrace directly */
489 }
490
491 INLINE_HEADER void traceSparkCounters(Capability *cap STG_UNUSED)
492 {
493 #ifdef THREADED_RTS
494 if (RTS_UNLIKELY(TRACE_sched)) {
495 traceSparkCounters_(cap, cap->spark_stats, sparkPoolSize(cap->sparks));
496 }
497 #endif
498 dtraceSparkCounters((EventCapNo)cap->no,
499 cap->spark_stats.created,
500 cap->spark_stats.dud,
501 cap->spark_stats.overflowed,
502 cap->spark_stats.converted,
503 cap->spark_stats.gcd,
504 cap->spark_stats.fizzled,
505 sparkPoolSize(cap->sparks));
506 }
507
508
509 #include "EndPrivate.h"
510
511 #endif /* TRACE_H */