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