includes/rts/EventLogFormat.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 2008-2009
   4  *
   5  * Event log format
   6  *
   7  * The log format is designed to be extensible: old tools should be
   8  * able to parse (but not necessarily understand all of) new versions
   9  * of the format, and new tools will be able to understand old log
  10  * files.
  11  *
  12  * Each event has a specific format.  If you add new events, give them
  13  * new numbers: we never re-use old event numbers.
  14  *
  15  * - The format is endian-independent: all values are represented in
  16  *    bigendian order.
  17  *
  18  * - The format is extensible:
  19  *
  20  *    - The header describes each event type and its length.  Tools
  21  *      that don't recognise a particular event type can skip those events.
  22  *
  23  *    - There is room for extra information in the event type
  24  *      specification, which can be ignored by older tools.
  25  *
  26  *    - Events can have extra information added, but existing fields
  27  *      cannot be changed.  Tools should ignore extra fields at the
  28  *      end of the event record.
  29  *
  30  *    - Old event type ids are never re-used; just take a new identifier.
  31  *
  32  *
  33  * The format
  34  * ----------
  35  *
  36  * log : EVENT_HEADER_BEGIN
  37  *       EventType*
  38  *       EVENT_HEADER_END
  39  *       EVENT_DATA_BEGIN
  40  *       Event*
  41  *       EVENT_DATA_END
  42  *
  43  * EventType :
  44  *       EVENT_ET_BEGIN
  45  *       Word16         -- unique identifier for this event
  46  *       Int16          -- >=0  size of the event in bytes (minus the header)
  47  *                      -- -1   variable size
  48  *       Word32         -- length of the next field in bytes
  49  *       Word8*         -- string describing the event
  50  *       Word32         -- length of the next field in bytes
  51  *       Word8*         -- extra info (for future extensions)
  52  *       EVENT_ET_END
  53  *
  54  * Event :
  55  *       Word16         -- event_type
  56  *       Word64         -- time (nanosecs)
  57  *       [Word16]       -- length of the rest (for variable-sized events only)
  58  *       ... extra event-specific info ...
  59  *
  60  *
  61  * To add a new event
  62  * ------------------
  63  *
  64  *  - In this file:
  65  *    - give it a new number, add a new #define EVENT_XXX below
  66  *  - In EventLog.c
  67  *    - add it to the EventDesc array
  68  *    - emit the event type in initEventLogging()
  69  *    - emit the new event in postEvent_()
  70  *    - generate the event itself by calling postEvent() somewhere
  71  *  - In the Haskell code to parse the event log file:
  72  *    - add types and code to read the new event
  73  *
  74  * -------------------------------------------------------------------------- */
  75
  76 #ifndef RTS_EVENTLOGFORMAT_H
  77 #define RTS_EVENTLOGFORMAT_H
  78
  79 /*
  80  * Markers for begin/end of the Header.
  81  */
  82 #define EVENT_HEADER_BEGIN    0x68647262 /* 'h' 'd' 'r' 'b' */
  83 #define EVENT_HEADER_END      0x68647265 /* 'h' 'd' 'r' 'e' */
  84
  85 #define EVENT_DATA_BEGIN      0x64617462 /* 'd' 'a' 't' 'b' */
  86 #define EVENT_DATA_END        0xffff
  87
  88 /*
  89  * Markers for begin/end of the list of Event Types in the Header.
  90  * Header, Event Type, Begin = hetb
  91  * Header, Event Type, End = hete
  92  */
  93 #define EVENT_HET_BEGIN       0x68657462 /* 'h' 'e' 't' 'b' */
  94 #define EVENT_HET_END         0x68657465 /* 'h' 'e' 't' 'e' */
  95
  96 #define EVENT_ET_BEGIN        0x65746200 /* 'e' 't' 'b' 0 */
  97 #define EVENT_ET_END          0x65746500 /* 'e' 't' 'e' 0 */
  98
  99 /*
 100  * Types of event
 101  */
 102 #define EVENT_CREATE_THREAD        0 /* (thread)               */
 103 #define EVENT_RUN_THREAD           1 /* (thread)               */
 104 #define EVENT_STOP_THREAD          2 /* (thread, status, blockinfo) */
 105 #define EVENT_THREAD_RUNNABLE      3 /* (thread)               */
 106 #define EVENT_MIGRATE_THREAD       4 /* (thread, new_cap)      */
 107 #define EVENT_RUN_SPARK            5 /* (thread)               */
 108 #define EVENT_STEAL_SPARK          6 /* (thread, victim_cap)   */
 109 #define EVENT_SHUTDOWN             7 /* ()                     */
 110 #define EVENT_THREAD_WAKEUP        8 /* (thread, other_cap)    */
 111 #define EVENT_GC_START             9 /* ()                     */
 112 #define EVENT_GC_END              10 /* ()                     */
 113 #define EVENT_REQUEST_SEQ_GC      11 /* ()                     */
 114 #define EVENT_REQUEST_PAR_GC      12 /* ()                     */
 115 /* 13, 14 deprecated */
 116 #define EVENT_CREATE_SPARK_THREAD 15 /* (spark_thread)         */
 117 #define EVENT_LOG_MSG             16 /* (message ...)          */
 118 #define EVENT_STARTUP             17 /* (num_capabilities)     */
 119 #define EVENT_BLOCK_MARKER        18 /* (size, end_time, capability) */
 120 #define EVENT_USER_MSG            19 /* (message ...)          */
 121 #define EVENT_GC_IDLE             20 /* () */
 122 #define EVENT_GC_WORK             21 /* () */
 123 #define EVENT_GC_DONE             22 /* () */
 124 /* 23, 24 used by eden */
 125 #define EVENT_CAPSET_CREATE       25 /* (capset, capset_type)  */
 126 #define EVENT_CAPSET_DELETE       26 /* (capset)               */
 127 #define EVENT_CAPSET_ASSIGN_CAP   27 /* (capset, cap)          */
 128 #define EVENT_CAPSET_REMOVE_CAP   28 /* (capset, cap)          */
 129 /* the RTS identifier is in the form of "GHC-version rts_way"  */
 130 #define EVENT_RTS_IDENTIFIER      29 /* (capset, name_version_string) */
 131 /* the vectors in these events are null separated strings             */
 132 #define EVENT_PROGRAM_ARGS        30 /* (capset, commandline_vector)  */
 133 #define EVENT_PROGRAM_ENV         31 /* (capset, environment_vector)  */
 134 #define EVENT_OSPROCESS_PID       32 /* (capset, pid)          */
 135 #define EVENT_OSPROCESS_PPID      33 /* (capset, parent_pid)   */
 136
 137
 138 /* Range 34 - 59 is available for new events */
 139
 140 /* Range 60 - 80 is used by eden for parallel tracing
 141  * see http://www.mathematik.uni-marburg.de/~eden/
 142  */
 143
 144 /*
 145  * The highest event code +1 that ghc itself emits. Note that some event
 146  * ranges higher than this are reserved but not currently emitted by ghc.
 147  * This must match the size of the EventDesc[] array in EventLog.c
 148  */
 149 #define NUM_EVENT_TAGS            34
 150
 151 #if 0  /* DEPRECATED EVENTS: */
 152 /* ghc changed how it handles sparks so these are no longer applicable */
 153 #define EVENT_CREATE_SPARK        13 /* (cap, thread) */
 154 #define EVENT_SPARK_TO_THREAD     14 /* (cap, thread, spark_thread) */
 155 /* these are used by eden but are replaced by new alternatives for ghc */
 156 #define EVENT_VERSION             23 /* (version_string) */
 157 #define EVENT_PROGRAM_INVOCATION  24 /* (commandline_string) */
 158 #endif
 159
 160 /*
 161  * Status values for EVENT_STOP_THREAD
 162  *
 163  * 1-5 are the StgRun return values (from includes/Constants.h):
 164  *
 165  * #define HeapOverflow   1
 166  * #define StackOverflow  2
 167  * #define ThreadYielding 3
 168  * #define ThreadBlocked  4
 169  * #define ThreadFinished 5
 170  * #define ForeignCall                  6
 171  * #define BlockedOnMVar                7
 172  * #define BlockedOnBlackHole           8
 173  * #define BlockedOnRead                9
 174  * #define BlockedOnWrite               10
 175  * #define BlockedOnDelay               11
 176  * #define BlockedOnSTM                 12
 177  * #define BlockedOnDoProc              13
 178  * #define BlockedOnCCall               -- not used (see ForeignCall)
 179  * #define BlockedOnCCall_NoUnblockExc  -- not used (see ForeignCall)
 180  * #define BlockedOnMsgThrowTo          16
 181  */
 182 #define THREAD_SUSPENDED_FOREIGN_CALL 6
 183
 184 /*
 185  * Capset type values for EVENT_CAPSET_CREATE
 186  */
 187 #define CAPSET_TYPE_CUSTOM      1  /* reserved for end-user applications */
 188 #define CAPSET_TYPE_OSPROCESS   2  /* caps belong to the same OS process */
 189 #define CAPSET_TYPE_CLOCKDOMAIN 3  /* caps share a local clock/time      */
 190
 191 #ifndef EVENTLOG_CONSTANTS_ONLY
 192
 193 typedef StgWord16 EventTypeNum;
 194 typedef StgWord64 EventTimestamp; /* in nanoseconds */
 195 typedef StgWord32 EventThreadID;
 196 typedef StgWord16 EventCapNo;
 197 typedef StgWord16 EventPayloadSize; /* variable-size events */
 198 typedef StgWord16 EventThreadStatus; /* status for EVENT_STOP_THREAD */
 199 typedef StgWord32 EventCapsetID;
 200 typedef StgWord16 EventCapsetType;   /* types for EVENT_CAPSET_CREATE */
 201
 202 #endif
 203
 204 #endif /* RTS_EVENTLOGFORMAT_H */