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