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 #ifdef DEBUG
 139 #define debugTraceCap(class, cap, msg, ...)      \
 140     if (RTS_UNLIKELY(class)) {                  \
 141         traceCap_(cap, msg, ##__VA_ARGS__);     \
 142     }
 143 #else
 144 #define debugTraceCap(class, cap, str, ...) /* nothing */
 145 #endif
 146
 147 /*
 148  * Emit a message/event describing the state of a thread
 149  */
 150 #define traceThreadStatus(class, tso)           \
 151     if (RTS_UNLIKELY(class)) {                  \
 152         traceThreadStatus_(tso);                \
 153     }
 154
 155 void traceThreadStatus_ (StgTSO *tso);
 156
 157 #else /* !TRACING */
 158
 159 #define traceSchedEvent(cap, tag, tso, other) /* nothing */
 160 #define traceEvent(cap, tag) /* nothing */
 161 #define traceCap(class, cap, msg, ...) /* nothing */
 162 #define trace(class, msg, ...) /* nothing */
 163 #define debugTrace(class, str, ...) /* nothing */
 164 #define debugTraceCap(class, cap, str, ...) /* nothing */
 165 #define traceThreadStatus(class, tso) /* nothing */
 166
 167 #endif /* TRACING */
 168
 169 // If DTRACE is enabled, but neither DEBUG nor TRACING, we need a C land
 170 // wrapper for the user-msg probe (as we can't expand that in PrimOps.cmm)
 171 //
 172 #if !defined(DEBUG) && !defined(TRACING) && defined(DTRACE)
 173
 174 void dtraceUserMsgWrapper(Capability *cap, char *msg);
 175
 176 #endif /* !defined(DEBUG) && !defined(TRACING) && defined(DTRACE) */
 177
 178 // -----------------------------------------------------------------------------
 179 // Aliases for static dtrace probes if dtrace is available
 180 // -----------------------------------------------------------------------------
 181
 182 #if defined(DTRACE)
 183
 184 #define dtraceCreateThread(cap, tid)                    \
 185     HASKELLEVENT_CREATE_THREAD(cap, tid)
 186 #define dtraceRunThread(cap, tid)                       \
 187     HASKELLEVENT_RUN_THREAD(cap, tid)
 188 #define dtraceStopThread(cap, tid, status)              \
 189     HASKELLEVENT_STOP_THREAD(cap, tid, status)
 190 #define dtraceThreadRunnable(cap, tid)                  \
 191     HASKELLEVENT_THREAD_RUNNABLE(cap, tid)
 192 #define dtraceMigrateThread(cap, tid, new_cap)          \
 193     HASKELLEVENT_MIGRATE_THREAD(cap, tid, new_cap)
 194 #define dtraceRunSpark(cap, tid)                        \
 195     HASKELLEVENT_RUN_SPARK(cap, tid)
 196 #define dtraceStealSpark(cap, tid, victim_cap)          \
 197     HASKELLEVENT_STEAL_SPARK(cap, tid, victim_cap)
 198 #define dtraceShutdown(cap)                             \
 199     HASKELLEVENT_SHUTDOWN(cap)
 200 #define dtraceThreadWakeup(cap, tid, other_cap)         \
 201     HASKELLEVENT_THREAD_WAKEUP(cap, tid, other_cap)
 202 #define dtraceGcStart(cap)                              \
 203     HASKELLEVENT_GC_START(cap)
 204 #define dtraceGcEnd(cap)                                \
 205     HASKELLEVENT_GC_END(cap)
 206 #define dtraceRequestSeqGc(cap)                         \
 207     HASKELLEVENT_REQUEST_SEQ_GC(cap)
 208 #define dtraceRequestParGc(cap)                         \
 209     HASKELLEVENT_REQUEST_PAR_GC(cap)
 210 #define dtraceCreateSparkThread(cap, spark_tid)         \
 211     HASKELLEVENT_CREATE_SPARK_THREAD(cap, spark_tid)
 212 #define dtraceStartup(num_caps)                         \
 213     HASKELLEVENT_STARTUP(num_caps)
 214 #define dtraceUserMsg(cap, msg)                         \
 215     HASKELLEVENT_USER_MSG(cap, msg)
 216 #define dtraceGcIdle(cap)                               \
 217     HASKELLEVENT_GC_IDLE(cap)
 218 #define dtraceGcWork(cap)                               \
 219     HASKELLEVENT_GC_WORK(cap)
 220 #define dtraceGcDone(cap)                               \
 221     HASKELLEVENT_GC_DONE(cap)
 222
 223 #else /* !defined(DTRACE) */
 224
 225 #define dtraceCreateThread(cap, tid)                    /* nothing */
 226 #define dtraceRunThread(cap, tid)                       /* nothing */
 227 #define dtraceStopThread(cap, tid, status)              /* nothing */
 228 #define dtraceThreadRunnable(cap, tid)                  /* nothing */
 229 #define dtraceMigrateThread(cap, tid, new_cap)          /* nothing */
 230 #define dtraceRunSpark(cap, tid)                        /* nothing */
 231 #define dtraceStealSpark(cap, tid, victim_cap)          /* nothing */
 232 #define dtraceShutdown(cap)                             /* nothing */
 233 #define dtraceThreadWakeup(cap, tid, other_cap)         /* nothing */
 234 #define dtraceGcStart(cap)                              /* nothing */
 235 #define dtraceGcEnd(cap)                                /* nothing */
 236 #define dtraceRequestSeqGc(cap)                         /* nothing */
 237 #define dtraceRequestParGc(cap)                         /* nothing */
 238 #define dtraceCreateSparkThread(cap, spark_tid)         /* nothing */
 239 #define dtraceStartup(num_caps)                         /* nothing */
 240 #define dtraceUserMsg(cap, msg)                         /* nothing */
 241 #define dtraceGcIdle(cap)                               /* nothing */
 242 #define dtraceGcWork(cap)                               /* nothing */
 243 #define dtraceGcDone(cap)                               /* nothing */
 244
 245 #endif
 246
 247 // -----------------------------------------------------------------------------
 248 // Trace probes dispatching to various tracing frameworks
 249 //
 250 // In order to avoid accumulating multiple calls to tracing calls at trace
 251 // points, we define inline probe functions that contain the various
 252 // invocations.
 253 //
 254 // Dtrace - dtrace probes are unconditionally added as probe activation is
 255 //   handled by the dtrace component of the kernel, and inactive probes are
 256 //   very cheap — usually, one no-op.  Consequently, dtrace can be used with
 257 //   all flavours of the RTS.  In addition, we still support logging events to
 258 //   a file, even in the presence of dtrace.  This is, eg, useful when tracing
 259 //   on a server, but browsing trace information with ThreadScope on a local
 260 //   client.
 261 //
 262 // -----------------------------------------------------------------------------
 263
 264 INLINE_HEADER void traceEventCreateThread(Capability *cap STG_UNUSED,
 265                                           StgTSO     *tso STG_UNUSED)
 266 {
 267     traceSchedEvent(cap, EVENT_CREATE_THREAD, tso, tso->stack_size);
 268     dtraceCreateThread((EventCapNo)cap->no, (EventThreadID)tso->id);
 269 }
 270
 271 INLINE_HEADER void traceEventRunThread(Capability *cap STG_UNUSED,
 272                                        StgTSO     *tso STG_UNUSED)
 273 {
 274     traceSchedEvent(cap, EVENT_RUN_THREAD, tso, tso->what_next);
 275     dtraceRunThread((EventCapNo)cap->no, (EventThreadID)tso->id);
 276 }
 277
 278 INLINE_HEADER void traceEventStopThread(Capability          *cap    STG_UNUSED,
 279                                         StgTSO              *tso    STG_UNUSED,
 280                                         StgThreadReturnCode  status STG_UNUSED)
 281 {
 282     traceSchedEvent(cap, EVENT_STOP_THREAD, tso, status);
 283     dtraceStopThread((EventCapNo)cap->no, (EventThreadID)tso->id,
 284                      (EventThreadStatus)status);
 285 }
 286
 287 // needs to be EXTERN_INLINE as it is used in another EXTERN_INLINE function
 288 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
 289                                             StgTSO     *tso STG_UNUSED);
 290
 291 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
 292                                             StgTSO     *tso STG_UNUSED)
 293 {
 294     traceSchedEvent(cap, EVENT_THREAD_RUNNABLE, tso, 0);
 295     dtraceThreadRunnable((EventCapNo)cap->no, (EventThreadID)tso->id);
 296 }
 297
 298 INLINE_HEADER void traceEventMigrateThread(Capability *cap     STG_UNUSED,
 299                                            StgTSO     *tso     STG_UNUSED,
 300                                            nat         new_cap STG_UNUSED)
 301 {
 302     traceSchedEvent(cap, EVENT_MIGRATE_THREAD, tso, new_cap);
 303     dtraceMigrateThread((EventCapNo)cap->no, (EventThreadID)tso->id,
 304                         (EventCapNo)new_cap);
 305 }
 306
 307 INLINE_HEADER void traceEventRunSpark(Capability *cap STG_UNUSED,
 308                                       StgTSO     *tso STG_UNUSED)
 309 {
 310     traceSchedEvent(cap, EVENT_RUN_SPARK, tso, 0);
 311     dtraceRunSpark((EventCapNo)cap->no, (EventThreadID)tso->id);
 312 }
 313
 314 INLINE_HEADER void traceEventStealSpark(Capability *cap        STG_UNUSED,
 315                                         StgTSO     *tso        STG_UNUSED,
 316                                         nat         victim_cap STG_UNUSED)
 317 {
 318     traceSchedEvent(cap, EVENT_STEAL_SPARK, tso, victim_cap);
 319     dtraceStealSpark((EventCapNo)cap->no, (EventThreadID)tso->id,
 320                      (EventCapNo)victim_cap);
 321 }
 322
 323 INLINE_HEADER void traceEventShutdown(Capability *cap STG_UNUSED)
 324 {
 325     traceSchedEvent(cap, EVENT_SHUTDOWN, 0, 0);
 326     dtraceShutdown((EventCapNo)cap->no);
 327 }
 328
 329 INLINE_HEADER void traceEventThreadWakeup(Capability *cap       STG_UNUSED,
 330                                           StgTSO     *tso       STG_UNUSED,
 331                                           nat         other_cap STG_UNUSED)
 332 {
 333     traceSchedEvent(cap, EVENT_THREAD_WAKEUP, tso, other_cap);
 334     dtraceThreadWakeup((EventCapNo)cap->no, (EventThreadID)tso->id,
 335                        (EventCapNo)other_cap);
 336 }
 337
 338 INLINE_HEADER void traceEventGcStart(Capability *cap STG_UNUSED)
 339 {
 340     traceSchedEvent(cap, EVENT_GC_START, 0, 0);
 341     dtraceGcStart((EventCapNo)cap->no);
 342 }
 343
 344 INLINE_HEADER void traceEventGcEnd(Capability *cap STG_UNUSED)
 345 {
 346     traceSchedEvent(cap, EVENT_GC_END, 0, 0);
 347     dtraceGcEnd((EventCapNo)cap->no);
 348 }
 349
 350 INLINE_HEADER void traceEventRequestSeqGc(Capability *cap STG_UNUSED)
 351 {
 352     traceSchedEvent(cap, EVENT_REQUEST_SEQ_GC, 0, 0);
 353     dtraceRequestSeqGc((EventCapNo)cap->no);
 354 }
 355
 356 INLINE_HEADER void traceEventRequestParGc(Capability *cap STG_UNUSED)
 357 {
 358     traceSchedEvent(cap, EVENT_REQUEST_PAR_GC, 0, 0);
 359     dtraceRequestParGc((EventCapNo)cap->no);
 360 }
 361
 362 INLINE_HEADER void traceEventCreateSparkThread(Capability  *cap      STG_UNUSED,
 363                                                StgThreadID spark_tid STG_UNUSED)
 364 {
 365     traceSchedEvent(cap, EVENT_CREATE_SPARK_THREAD, 0, spark_tid);
 366     dtraceCreateSparkThread((EventCapNo)cap->no, (EventThreadID)spark_tid);
 367 }
 368
 369 // This applies only to dtrace as EVENT_STARTUP in the logging framework is
 370 // handled specially in 'EventLog.c'.
 371 //
 372 INLINE_HEADER void dtraceEventStartup(void)
 373 {
 374 #ifdef THREADED_RTS
 375     // XXX n_capabilities hasn't been initislised yet
 376     dtraceStartup(RtsFlags.ParFlags.nNodes);
 377 #else
 378     dtraceStartup(1);
 379 #endif
 380 }
 381
 382 INLINE_HEADER void traceEventGcIdle(Capability *cap STG_UNUSED)
 383 {
 384     traceEvent(cap, EVENT_GC_IDLE);
 385     dtraceGcIdle((EventCapNo)cap->no);
 386 }
 387
 388 INLINE_HEADER void traceEventGcWork(Capability *cap STG_UNUSED)
 389 {
 390     traceEvent(cap, EVENT_GC_WORK);
 391     dtraceGcWork((EventCapNo)cap->no);
 392 }
 393
 394 INLINE_HEADER void traceEventGcDone(Capability *cap STG_UNUSED)
 395 {
 396     traceEvent(cap, EVENT_GC_DONE);
 397     dtraceGcDone((EventCapNo)cap->no);
 398 }
 399
 400 END_RTS_PRIVATE
 401
 402 #endif /* TRACE_H */