b63f8420084cc9e3588148de1010584b03a675e4
[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 #pragma once
77
78 /*
79 * Markers for begin/end of the Header.
80 */
81 #define EVENT_HEADER_BEGIN 0x68647262 /* 'h' 'd' 'r' 'b' */
82 #define EVENT_HEADER_END 0x68647265 /* 'h' 'd' 'r' 'e' */
83
84 #define EVENT_DATA_BEGIN 0x64617462 /* 'd' 'a' 't' 'b' */
85 #define EVENT_DATA_END 0xffff
86
87 /*
88 * Markers for begin/end of the list of Event Types in the Header.
89 * Header, Event Type, Begin = hetb
90 * Header, Event Type, End = hete
91 */
92 #define EVENT_HET_BEGIN 0x68657462 /* 'h' 'e' 't' 'b' */
93 #define EVENT_HET_END 0x68657465 /* 'h' 'e' 't' 'e' */
94
95 #define EVENT_ET_BEGIN 0x65746200 /* 'e' 't' 'b' 0 */
96 #define EVENT_ET_END 0x65746500 /* 'e' 't' 'e' 0 */
97
98 /*
99 * Types of event
100 */
101 #define EVENT_CREATE_THREAD 0 /* (thread) */
102 #define EVENT_RUN_THREAD 1 /* (thread) */
103 #define EVENT_STOP_THREAD 2 /* (thread, status, blockinfo) */
104 #define EVENT_THREAD_RUNNABLE 3 /* (thread) */
105 #define EVENT_MIGRATE_THREAD 4 /* (thread, new_cap) */
106 /* 5, 6, 7 deprecated */
107 #define EVENT_THREAD_WAKEUP 8 /* (thread, other_cap) */
108 #define EVENT_GC_START 9 /* () */
109 #define EVENT_GC_END 10 /* () */
110 #define EVENT_REQUEST_SEQ_GC 11 /* () */
111 #define EVENT_REQUEST_PAR_GC 12 /* () */
112 /* 13, 14 deprecated */
113 #define EVENT_CREATE_SPARK_THREAD 15 /* (spark_thread) */
114 #define EVENT_LOG_MSG 16 /* (message ...) */
115 /* 17 deprecated */
116 #define EVENT_BLOCK_MARKER 18 /* (size, end_time, capability) */
117 #define EVENT_USER_MSG 19 /* (message ...) */
118 #define EVENT_GC_IDLE 20 /* () */
119 #define EVENT_GC_WORK 21 /* () */
120 #define EVENT_GC_DONE 22 /* () */
121 /* 23, 24 used by eden */
122 #define EVENT_CAPSET_CREATE 25 /* (capset, capset_type) */
123 #define EVENT_CAPSET_DELETE 26 /* (capset) */
124 #define EVENT_CAPSET_ASSIGN_CAP 27 /* (capset, cap) */
125 #define EVENT_CAPSET_REMOVE_CAP 28 /* (capset, cap) */
126 /* the RTS identifier is in the form of "GHC-version rts_way" */
127 #define EVENT_RTS_IDENTIFIER 29 /* (capset, name_version_string) */
128 /* the vectors in these events are null separated strings */
129 #define EVENT_PROGRAM_ARGS 30 /* (capset, commandline_vector) */
130 #define EVENT_PROGRAM_ENV 31 /* (capset, environment_vector) */
131 #define EVENT_OSPROCESS_PID 32 /* (capset, pid) */
132 #define EVENT_OSPROCESS_PPID 33 /* (capset, parent_pid) */
133 #define EVENT_SPARK_COUNTERS 34 /* (crt,dud,ovf,cnv,gcd,fiz,rem) */
134 #define EVENT_SPARK_CREATE 35 /* () */
135 #define EVENT_SPARK_DUD 36 /* () */
136 #define EVENT_SPARK_OVERFLOW 37 /* () */
137 #define EVENT_SPARK_RUN 38 /* () */
138 #define EVENT_SPARK_STEAL 39 /* (victim_cap) */
139 #define EVENT_SPARK_FIZZLE 40 /* () */
140 #define EVENT_SPARK_GC 41 /* () */
141 #define EVENT_INTERN_STRING 42 /* (string, id) {not used by ghc} */
142 #define EVENT_WALL_CLOCK_TIME 43 /* (capset, unix_epoch_seconds, nanoseconds) */
143 #define EVENT_THREAD_LABEL 44 /* (thread, name_string) */
144 #define EVENT_CAP_CREATE 45 /* (cap) */
145 #define EVENT_CAP_DELETE 46 /* (cap) */
146 #define EVENT_CAP_DISABLE 47 /* (cap) */
147 #define EVENT_CAP_ENABLE 48 /* (cap) */
148 #define EVENT_HEAP_ALLOCATED 49 /* (heap_capset, alloc_bytes) */
149 #define EVENT_HEAP_SIZE 50 /* (heap_capset, size_bytes) */
150 #define EVENT_HEAP_LIVE 51 /* (heap_capset, live_bytes) */
151 #define EVENT_HEAP_INFO_GHC 52 /* (heap_capset, n_generations,
152 max_heap_size, alloc_area_size,
153 mblock_size, block_size) */
154 #define EVENT_GC_STATS_GHC 53 /* (heap_capset, generation,
155 copied_bytes, slop_bytes, frag_bytes,
156 par_n_threads,
157 par_max_copied, par_tot_copied) */
158 #define EVENT_GC_GLOBAL_SYNC 54 /* () */
159 #define EVENT_TASK_CREATE 55 /* (taskID, cap, tid) */
160 #define EVENT_TASK_MIGRATE 56 /* (taskID, cap, new_cap) */
161 #define EVENT_TASK_DELETE 57 /* (taskID) */
162 #define EVENT_USER_MARKER 58 /* (marker_name) */
163 #define EVENT_HACK_BUG_T9003 59 /* Hack: see trac #9003 */
164
165 /* Range 60 - 80 is used by eden for parallel tracing
166 * see http://www.mathematik.uni-marburg.de/~eden/
167 */
168
169 /* Range 100 - 139 is reserved for Mercury. */
170
171 /* Range 140 - 159 is reserved for Perf events. */
172
173 /* Range 160 - 180 is reserved for cost-centre heap profiling events. */
174
175 #define EVENT_HEAP_PROF_BEGIN 160
176 #define EVENT_HEAP_PROF_COST_CENTRE 161
177 #define EVENT_HEAP_PROF_SAMPLE_BEGIN 162
178 #define EVENT_HEAP_PROF_SAMPLE_COST_CENTRE 163
179 #define EVENT_HEAP_PROF_SAMPLE_STRING 164
180 /*
181 * The highest event code +1 that ghc itself emits. Note that some event
182 * ranges higher than this are reserved but not currently emitted by ghc.
183 * This must match the size of the EventDesc[] array in EventLog.c
184 */
185 #define NUM_GHC_EVENT_TAGS 165
186
187 #if 0 /* DEPRECATED EVENTS: */
188 /* we don't actually need to record the thread, it's implicit */
189 #define EVENT_RUN_SPARK 5 /* (thread) */
190 #define EVENT_STEAL_SPARK 6 /* (thread, victim_cap) */
191 /* shutdown replaced by EVENT_CAP_DELETE */
192 #define EVENT_SHUTDOWN 7 /* () */
193 /* ghc changed how it handles sparks so these are no longer applicable */
194 #define EVENT_CREATE_SPARK 13 /* (cap, thread) */
195 #define EVENT_SPARK_TO_THREAD 14 /* (cap, thread, spark_thread) */
196 #define EVENT_STARTUP 17 /* (num_capabilities) */
197 /* these are used by eden but are replaced by new alternatives for ghc */
198 #define EVENT_VERSION 23 /* (version_string) */
199 #define EVENT_PROGRAM_INVOCATION 24 /* (commandline_string) */
200 #endif
201
202 /*
203 * Status values for EVENT_STOP_THREAD
204 *
205 * 1-5 are the StgRun return values (from includes/Constants.h):
206 *
207 * #define HeapOverflow 1
208 * #define StackOverflow 2
209 * #define ThreadYielding 3
210 * #define ThreadBlocked 4
211 * #define ThreadFinished 5
212 * #define ForeignCall 6
213 * #define BlockedOnMVar 7
214 * #define BlockedOnBlackHole 8
215 * #define BlockedOnRead 9
216 * #define BlockedOnWrite 10
217 * #define BlockedOnDelay 11
218 * #define BlockedOnSTM 12
219 * #define BlockedOnDoProc 13
220 * #define BlockedOnCCall -- not used (see ForeignCall)
221 * #define BlockedOnCCall_NoUnblockExc -- not used (see ForeignCall)
222 * #define BlockedOnMsgThrowTo 16
223 */
224 #define THREAD_SUSPENDED_FOREIGN_CALL 6
225
226 /*
227 * Capset type values for EVENT_CAPSET_CREATE
228 */
229 #define CAPSET_TYPE_CUSTOM 1 /* reserved for end-user applications */
230 #define CAPSET_TYPE_OSPROCESS 2 /* caps belong to the same OS process */
231 #define CAPSET_TYPE_CLOCKDOMAIN 3 /* caps share a local clock/time */
232
233 #if !defined(EVENTLOG_CONSTANTS_ONLY)
234
235 typedef StgWord16 EventTypeNum;
236 typedef StgWord64 EventTimestamp; /* in nanoseconds */
237 typedef StgWord32 EventThreadID;
238 typedef StgWord16 EventCapNo;
239 typedef StgWord16 EventPayloadSize; /* variable-size events */
240 typedef StgWord16 EventThreadStatus; /* status for EVENT_STOP_THREAD */
241 typedef StgWord32 EventCapsetID;
242 typedef StgWord16 EventCapsetType; /* types for EVENT_CAPSET_CREATE */
243 typedef StgWord64 EventTaskId; /* for EVENT_TASK_* */
244 typedef StgWord64 EventKernelThreadId; /* for EVENT_TASK_CREATE */
245
246 #endif