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 /*
 171  * Events for describing capability sets in the eventlog
 172  *
 173  * Note: unlike other events, these are not conditional on TRACE_sched or
 174  * similar because they are not "real" events themselves but provide
 175  * information and context for other "real" events. Other events depend on
 176  * the capset info events so for simplicity, rather than working out if
 177  * they're necessary we always emit them. They should be very low volume.
 178  */
 179 void traceCapsetModify_ (EventTypeNum tag,
 180                          CapsetID capset,
 181                          StgWord32 other,
 182                          StgWord32 other2);
 183
 184 void traceCapsetDetails_ (int *argc, char **argv[]);
 185 #else /* !TRACING */
 186
 187 #define traceSchedEvent(cap, tag, tso, other) /* nothing */
 188 #define traceSchedEvent2(cap, tag, tso, other, info) /* nothing */
 189 #define traceEvent(cap, tag) /* nothing */
 190 #define traceCap(class, cap, msg, ...) /* nothing */
 191 #define trace(class, msg, ...) /* nothing */
 192 #define debugTrace(class, str, ...) /* nothing */
 193 #define debugTraceCap(class, cap, str, ...) /* nothing */
 194 #define traceThreadStatus(class, tso) /* nothing */
 195 #define traceCapsetModify_(tag, capset, other, other2) /* nothing */
 196 #define traceCapsetDetails_(argc, argv) /* nothing */
 197
 198 #endif /* TRACING */
 199
 200 // If DTRACE is enabled, but neither DEBUG nor TRACING, we need a C land
 201 // wrapper for the user-msg probe (as we can't expand that in PrimOps.cmm)
 202 //
 203 #if !defined(DEBUG) && !defined(TRACING) && defined(DTRACE)
 204
 205 void dtraceUserMsgWrapper(Capability *cap, char *msg);
 206
 207 #endif /* !defined(DEBUG) && !defined(TRACING) && defined(DTRACE) */
 208
 209 // -----------------------------------------------------------------------------
 210 // Aliases for static dtrace probes if dtrace is available
 211 // -----------------------------------------------------------------------------
 212
 213 #if defined(DTRACE)
 214
 215 #define dtraceCreateThread(cap, tid)                    \
 216     HASKELLEVENT_CREATE_THREAD(cap, tid)
 217 #define dtraceRunThread(cap, tid)                       \
 218     HASKELLEVENT_RUN_THREAD(cap, tid)
 219 #define dtraceStopThread(cap, tid, status, info)        \
 220     HASKELLEVENT_STOP_THREAD(cap, tid, status, info)
 221 #define dtraceThreadRunnable(cap, tid)                  \
 222     HASKELLEVENT_THREAD_RUNNABLE(cap, tid)
 223 #define dtraceMigrateThread(cap, tid, new_cap)          \
 224     HASKELLEVENT_MIGRATE_THREAD(cap, tid, new_cap)
 225 #define dtraceRunSpark(cap, tid)                        \
 226     HASKELLEVENT_RUN_SPARK(cap, tid)
 227 #define dtraceStealSpark(cap, tid, victim_cap)          \
 228     HASKELLEVENT_STEAL_SPARK(cap, tid, victim_cap)
 229 #define dtraceShutdown(cap)                             \
 230     HASKELLEVENT_SHUTDOWN(cap)
 231 #define dtraceThreadWakeup(cap, tid, other_cap)         \
 232     HASKELLEVENT_THREAD_WAKEUP(cap, tid, other_cap)
 233 #define dtraceGcStart(cap)                              \
 234     HASKELLEVENT_GC_START(cap)
 235 #define dtraceGcEnd(cap)                                \
 236     HASKELLEVENT_GC_END(cap)
 237 #define dtraceRequestSeqGc(cap)                         \
 238     HASKELLEVENT_REQUEST_SEQ_GC(cap)
 239 #define dtraceRequestParGc(cap)                         \
 240     HASKELLEVENT_REQUEST_PAR_GC(cap)
 241 #define dtraceCreateSparkThread(cap, spark_tid)         \
 242     HASKELLEVENT_CREATE_SPARK_THREAD(cap, spark_tid)
 243 #define dtraceStartup(num_caps)                         \
 244     HASKELLEVENT_STARTUP(num_caps)
 245 #define dtraceUserMsg(cap, msg)                         \
 246     HASKELLEVENT_USER_MSG(cap, msg)
 247 #define dtraceGcIdle(cap)                               \
 248     HASKELLEVENT_GC_IDLE(cap)
 249 #define dtraceGcWork(cap)                               \
 250     HASKELLEVENT_GC_WORK(cap)
 251 #define dtraceGcDone(cap)                               \
 252     HASKELLEVENT_GC_DONE(cap)
 253 #define dtraceCapsetCreate(capset, capset_type)         \
 254     HASKELLEVENT_CAPSET_CREATE(capset, capset_type)
 255 #define dtraceCapsetDelete(capset)                      \
 256     HASKELLEVENT_CAPSET_DELETE(capset)
 257 #define dtraceCapsetAssignCap(capset, capno)            \
 258     HASKELLEVENT_CAPSET_ASSIGN_CAP(capset, capno)
 259 #define dtraceCapsetRemoveCap(capset, capno)            \
 260     HASKELLEVENT_CAPSET_REMOVE_CAP(capset, capno)
 261
 262 #else /* !defined(DTRACE) */
 263
 264 #define dtraceCreateThread(cap, tid)                    /* nothing */
 265 #define dtraceRunThread(cap, tid)                       /* nothing */
 266 #define dtraceStopThread(cap, tid, status, info)        /* nothing */
 267 #define dtraceThreadRunnable(cap, tid)                  /* nothing */
 268 #define dtraceMigrateThread(cap, tid, new_cap)          /* nothing */
 269 #define dtraceRunSpark(cap, tid)                        /* nothing */
 270 #define dtraceStealSpark(cap, tid, victim_cap)          /* nothing */
 271 #define dtraceShutdown(cap)                             /* nothing */
 272 #define dtraceThreadWakeup(cap, tid, other_cap)         /* nothing */
 273 #define dtraceGcStart(cap)                              /* nothing */
 274 #define dtraceGcEnd(cap)                                /* nothing */
 275 #define dtraceRequestSeqGc(cap)                         /* nothing */
 276 #define dtraceRequestParGc(cap)                         /* nothing */
 277 #define dtraceCreateSparkThread(cap, spark_tid)         /* nothing */
 278 #define dtraceStartup(num_caps)                         /* nothing */
 279 #define dtraceUserMsg(cap, msg)                         /* nothing */
 280 #define dtraceGcIdle(cap)                               /* nothing */
 281 #define dtraceGcWork(cap)                               /* nothing */
 282 #define dtraceGcDone(cap)                               /* nothing */
 283 #define dtraceCapsetCreate(capset, capset_type)         /* nothing */
 284 #define dtraceCapsetDelete(capset)                      /* nothing */
 285 #define dtraceCapsetAssignCap(capset, capno)            /* nothing */
 286 #define dtraceCapsetRemoveCap(capset, capno)            /* nothing */
 287
 288 #endif
 289
 290 // -----------------------------------------------------------------------------
 291 // Trace probes dispatching to various tracing frameworks
 292 //
 293 // In order to avoid accumulating multiple calls to tracing calls at trace
 294 // points, we define inline probe functions that contain the various
 295 // invocations.
 296 //
 297 // Dtrace - dtrace probes are unconditionally added as probe activation is
 298 //   handled by the dtrace component of the kernel, and inactive probes are
 299 //   very cheap — usually, one no-op.  Consequently, dtrace can be used with
 300 //   all flavours of the RTS.  In addition, we still support logging events to
 301 //   a file, even in the presence of dtrace.  This is, eg, useful when tracing
 302 //   on a server, but browsing trace information with ThreadScope on a local
 303 //   client.
 304 //
 305 // -----------------------------------------------------------------------------
 306
 307 INLINE_HEADER void traceEventCreateThread(Capability *cap STG_UNUSED,
 308                                           StgTSO     *tso STG_UNUSED)
 309 {
 310     traceSchedEvent(cap, EVENT_CREATE_THREAD, tso, tso->stackobj->stack_size);
 311     dtraceCreateThread((EventCapNo)cap->no, (EventThreadID)tso->id);
 312 }
 313
 314 INLINE_HEADER void traceEventRunThread(Capability *cap STG_UNUSED,
 315                                        StgTSO     *tso STG_UNUSED)
 316 {
 317     traceSchedEvent(cap, EVENT_RUN_THREAD, tso, tso->what_next);
 318     dtraceRunThread((EventCapNo)cap->no, (EventThreadID)tso->id);
 319 }
 320
 321 INLINE_HEADER void traceEventStopThread(Capability          *cap    STG_UNUSED,
 322                                         StgTSO              *tso    STG_UNUSED,
 323                                         StgThreadReturnCode  status STG_UNUSED,
 324                                         StgWord32           info    STG_UNUSED)
 325 {
 326     traceSchedEvent2(cap, EVENT_STOP_THREAD, tso, status, info);
 327     dtraceStopThread((EventCapNo)cap->no, (EventThreadID)tso->id,
 328                      (EventThreadStatus)status, (EventThreadID)info);
 329 }
 330
 331 // needs to be EXTERN_INLINE as it is used in another EXTERN_INLINE function
 332 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
 333                                             StgTSO     *tso STG_UNUSED);
 334
 335 EXTERN_INLINE void traceEventThreadRunnable(Capability *cap STG_UNUSED,
 336                                             StgTSO     *tso STG_UNUSED)
 337 {
 338     traceSchedEvent(cap, EVENT_THREAD_RUNNABLE, tso, 0);
 339     dtraceThreadRunnable((EventCapNo)cap->no, (EventThreadID)tso->id);
 340 }
 341
 342 INLINE_HEADER void traceEventMigrateThread(Capability *cap     STG_UNUSED,
 343                                            StgTSO     *tso     STG_UNUSED,
 344                                            nat         new_cap STG_UNUSED)
 345 {
 346     traceSchedEvent(cap, EVENT_MIGRATE_THREAD, tso, new_cap);
 347     dtraceMigrateThread((EventCapNo)cap->no, (EventThreadID)tso->id,
 348                         (EventCapNo)new_cap);
 349 }
 350
 351 INLINE_HEADER void traceEventRunSpark(Capability *cap STG_UNUSED,
 352                                       StgTSO     *tso STG_UNUSED)
 353 {
 354     traceSchedEvent(cap, EVENT_RUN_SPARK, tso, 0);
 355     dtraceRunSpark((EventCapNo)cap->no, (EventThreadID)tso->id);
 356 }
 357
 358 INLINE_HEADER void traceEventStealSpark(Capability *cap        STG_UNUSED,
 359                                         StgTSO     *tso        STG_UNUSED,
 360                                         nat         victim_cap STG_UNUSED)
 361 {
 362     traceSchedEvent(cap, EVENT_STEAL_SPARK, tso, victim_cap);
 363     dtraceStealSpark((EventCapNo)cap->no, (EventThreadID)tso->id,
 364                      (EventCapNo)victim_cap);
 365 }
 366
 367 INLINE_HEADER void traceEventShutdown(Capability *cap STG_UNUSED)
 368 {
 369     traceSchedEvent(cap, EVENT_SHUTDOWN, 0, 0);
 370     dtraceShutdown((EventCapNo)cap->no);
 371 }
 372
 373 INLINE_HEADER void traceEventThreadWakeup(Capability *cap       STG_UNUSED,
 374                                           StgTSO     *tso       STG_UNUSED,
 375                                           nat         other_cap STG_UNUSED)
 376 {
 377     traceSchedEvent(cap, EVENT_THREAD_WAKEUP, tso, other_cap);
 378     dtraceThreadWakeup((EventCapNo)cap->no, (EventThreadID)tso->id,
 379                        (EventCapNo)other_cap);
 380 }
 381
 382 INLINE_HEADER void traceEventGcStart(Capability *cap STG_UNUSED)
 383 {
 384     traceSchedEvent(cap, EVENT_GC_START, 0, 0);
 385     dtraceGcStart((EventCapNo)cap->no);
 386 }
 387
 388 INLINE_HEADER void traceEventGcEnd(Capability *cap STG_UNUSED)
 389 {
 390     traceSchedEvent(cap, EVENT_GC_END, 0, 0);
 391     dtraceGcEnd((EventCapNo)cap->no);
 392 }
 393
 394 INLINE_HEADER void traceEventRequestSeqGc(Capability *cap STG_UNUSED)
 395 {
 396     traceSchedEvent(cap, EVENT_REQUEST_SEQ_GC, 0, 0);
 397     dtraceRequestSeqGc((EventCapNo)cap->no);
 398 }
 399
 400 INLINE_HEADER void traceEventRequestParGc(Capability *cap STG_UNUSED)
 401 {
 402     traceSchedEvent(cap, EVENT_REQUEST_PAR_GC, 0, 0);
 403     dtraceRequestParGc((EventCapNo)cap->no);
 404 }
 405
 406 INLINE_HEADER void traceEventCreateSparkThread(Capability  *cap      STG_UNUSED,
 407                                                StgThreadID spark_tid STG_UNUSED)
 408 {
 409     traceSchedEvent(cap, EVENT_CREATE_SPARK_THREAD, 0, spark_tid);
 410     dtraceCreateSparkThread((EventCapNo)cap->no, (EventThreadID)spark_tid);
 411 }
 412
 413 // This applies only to dtrace as EVENT_STARTUP in the logging framework is
 414 // handled specially in 'EventLog.c'.
 415 //
 416 INLINE_HEADER void dtraceEventStartup(void)
 417 {
 418 #ifdef THREADED_RTS
 419     // XXX n_capabilities hasn't been initislised yet
 420     dtraceStartup(RtsFlags.ParFlags.nNodes);
 421 #else
 422     dtraceStartup(1);
 423 #endif
 424 }
 425
 426 INLINE_HEADER void traceEventGcIdle(Capability *cap STG_UNUSED)
 427 {
 428     traceEvent(cap, EVENT_GC_IDLE);
 429     dtraceGcIdle((EventCapNo)cap->no);
 430 }
 431
 432 INLINE_HEADER void traceEventGcWork(Capability *cap STG_UNUSED)
 433 {
 434     traceEvent(cap, EVENT_GC_WORK);
 435     dtraceGcWork((EventCapNo)cap->no);
 436 }
 437
 438 INLINE_HEADER void traceEventGcDone(Capability *cap STG_UNUSED)
 439 {
 440     traceEvent(cap, EVENT_GC_DONE);
 441     dtraceGcDone((EventCapNo)cap->no);
 442 }
 443
 444 INLINE_HEADER void traceCapsetCreate(CapsetID   capset      STG_UNUSED,
 445                                      CapsetType capset_type STG_UNUSED)
 446 {
 447     traceCapsetModify_(EVENT_CAPSET_CREATE, capset, capset_type, 0);
 448     dtraceCapsetCreate(capset, capset_type);
 449 }
 450
 451 INLINE_HEADER void traceCapsetDelete(CapsetID capset STG_UNUSED)
 452 {
 453     traceCapsetModify_(EVENT_CAPSET_DELETE, capset, 0, 0);
 454     dtraceCapsetDelete(capset);
 455 }
 456
 457 INLINE_HEADER void traceCapsetAssignCap(CapsetID capset STG_UNUSED,
 458                                         nat      capno  STG_UNUSED)
 459 {
 460     traceCapsetModify_(EVENT_CAPSET_ASSIGN_CAP, capset, capno, 0);
 461     dtraceCapsetAssignCap(capset, capno);
 462 }
 463
 464 INLINE_HEADER void traceCapsetRemoveCap(CapsetID capset STG_UNUSED,
 465                                         nat      capno  STG_UNUSED)
 466 {
 467     traceCapsetModify_(EVENT_CAPSET_REMOVE_CAP, capset, capno, 0);
 468     dtraceCapsetRemoveCap(capset, capno);
 469 }
 470
 471 INLINE_HEADER void traceCapsetDetails(int *argc STG_UNUSED, char **argv[] STG_UNUSED)
 472 {
 473     traceCapsetCreate(CAPSET_OSPROCESS_DEFAULT, CapsetTypeOsProcess);
 474     traceCapsetDetails_(argc, argv);
 475 }
 476
 477 #include "EndPrivate.h"
 478
 479 #endif /* TRACE_H */