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 /*
  77  * Markers for begin/end of the Header.
  78  */
  79 #define EVENT_HEADER_BEGIN    0x68647262 /* 'h' 'd' 'r' 'b' */
  80 #define EVENT_HEADER_END      0x68647265 /* 'h' 'd' 'r' 'e' */
  81
  82 #define EVENT_DATA_BEGIN      0x64617462 /* 'd' 'a' 't' 'b' */
  83 #define EVENT_DATA_END        0xffff
  84
  85 /*
  86  * Markers for begin/end of the list of Event Types in the Header.
  87  * Header, Event Type, Begin = hetb
  88  * Header, Event Type, End = hete
  89  */
  90 #define EVENT_HET_BEGIN       0x68657462 /* 'h' 'e' 't' 'b' */
  91 #define EVENT_HET_END         0x68657465 /* 'h' 'e' 't' 'e' */
  92
  93 #define EVENT_ET_BEGIN        0x65746200 /* 'e' 't' 'b' 0 */
  94 #define EVENT_ET_END          0x65746500 /* 'e' 't' 'e' 0 */
  95
  96 /*
  97  * Types of event
  98  */
  99 #define EVENT_CREATE_THREAD   0 /* (cap, thread)              */
 100 #define EVENT_RUN_THREAD      1 /* (cap, thread)              */
 101 #define EVENT_STOP_THREAD     2 /* (cap, thread, status)      */
 102 #define EVENT_THREAD_RUNNABLE 3 /* (cap, thread)              */
 103 #define EVENT_MIGRATE_THREAD  4 /* (cap, thread, new_cap)     */
 104 #define EVENT_RUN_SPARK       5 /* (cap, thread)              */
 105 #define EVENT_STEAL_SPARK     6 /* (cap, thread, victim_cap)  */
 106 #define EVENT_SHUTDOWN        7 /* (cap)                      */
 107 #define EVENT_THREAD_WAKEUP   8 /* (cap, thread, other_cap)   */
 108 #define EVENT_GC_START        9 /* (cap) */
 109 #define EVENT_GC_END         10 /* (cap) */
 110 #define EVENT_REQUEST_SEQ_GC 11 /* (cap) */
 111 #define EVENT_REQUEST_PAR_GC 12 /* (cap) */
 112
 113 #define NUM_EVENT_TAGS       13
 114
 115 /*
 116  * Status values for EVENT_STOP_THREAD
 117  *
 118  * 1-5 are the StgRun return values (from includes/Constants.h):
 119  *
 120  * #define HeapOverflow   1
 121  * #define StackOverflow  2
 122  * #define ThreadYielding 3
 123  * #define ThreadBlocked  4
 124  * #define ThreadFinished 5
 125  */
 126 #define THREAD_SUSPENDED_FOREIGN_CALL 6
 127
 128 #ifndef EVENTLOG_CONSTANTS_ONLY
 129
 130 typedef StgWord16 EventTypeNum;
 131 typedef StgWord64 Timestamp; // in nanoseconds
 132 typedef StgWord64 ThreadID;
 133 typedef StgWord16 CapabilityNum;
 134
 135 #endif