363c1ca1cfe13cc2f0410ba824f6f629b93c8be1
[ghc.git] / 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 /* (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 /* RTS_EVENTLOGFORMAT_H */