includes/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 EVENTLOGFORMAT_H
  77 #define 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 /* (cap, thread)               */
 103 #define EVENT_RUN_THREAD           1 /* (cap, thread)               */
 104 #define EVENT_STOP_THREAD          2 /* (cap, thread, status)       */
 105 #define EVENT_THREAD_RUNNABLE      3 /* (cap, thread)               */
 106 #define EVENT_MIGRATE_THREAD       4 /* (cap, thread, new_cap)      */
 107 #define EVENT_RUN_SPARK            5 /* (cap, thread)               */
 108 #define EVENT_STEAL_SPARK          6 /* (cap, thread, victim_cap)   */
 109 #define EVENT_SHUTDOWN             7 /* (cap)                       */
 110 #define EVENT_THREAD_WAKEUP        8 /* (cap, thread, other_cap)    */
 111 #define EVENT_GC_START             9 /* (cap)                       */
 112 #define EVENT_GC_END              10 /* (cap)                       */
 113 #define EVENT_REQUEST_SEQ_GC      11 /* (cap)                       */
 114 #define EVENT_REQUEST_PAR_GC      12 /* (cap)                       */
 115 #define EVENT_CREATE_SPARK        13 /* (cap, thread)               */
 116 #define EVENT_SPARK_TO_THREAD     14 /* DEPRECATED! (cap, thread, spark_thread) */
 117 #define EVENT_CREATE_SPARK_THREAD 15 /* (cap, thread, spark_thread) */
 118
 119 #define NUM_EVENT_TAGS        16
 120
 121 /*
 122  * Status values for EVENT_STOP_THREAD
 123  *
 124  * 1-5 are the StgRun return values (from includes/Constants.h):
 125  *
 126  * #define HeapOverflow   1
 127  * #define StackOverflow  2
 128  * #define ThreadYielding 3
 129  * #define ThreadBlocked  4
 130  * #define ThreadFinished 5
 131  */
 132 #define THREAD_SUSPENDED_FOREIGN_CALL 6
 133
 134 #ifndef EVENTLOG_CONSTANTS_ONLY
 135
 136 typedef StgWord16 EventTypeNum;
 137 typedef StgWord64 EventTimestamp; // in nanoseconds
 138 typedef StgWord64 EventThreadID;
 139 typedef StgWord16 EventCapNo;
 140
 141 #endif
 142
 143 #endif /* EVENTLOGFORMAT_H */