1 /* ----------------------------------------------------------------------------- 2 * 3 * (c) The GHC Team, 2008-2012 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 /* 5, 6, 7 deprecated */ 108 #define EVENT_THREAD_WAKEUP 8 /* (thread, other_cap) */ 109 #define EVENT_GC_START 9 /* () */ 110 #define EVENT_GC_END 10 /* () */ 111 #define EVENT_REQUEST_SEQ_GC 11 /* () */ 112 #define EVENT_REQUEST_PAR_GC 12 /* () */ 113 /* 13, 14 deprecated */ 114 #define EVENT_CREATE_SPARK_THREAD 15 /* (spark_thread) */ 115 #define EVENT_LOG_MSG 16 /* (message ...) */ 116 /* 17 deprecated */ 117 #define EVENT_BLOCK_MARKER 18 /* (size, end_time, capability) */ 118 #define EVENT_USER_MSG 19 /* (message ...) */ 119 #define EVENT_GC_IDLE 20 /* () */ 120 #define EVENT_GC_WORK 21 /* () */ 121 #define EVENT_GC_DONE 22 /* () */ 122 /* 23, 24 used by eden */ 123 #define EVENT_CAPSET_CREATE 25 /* (capset, capset_type) */ 124 #define EVENT_CAPSET_DELETE 26 /* (capset) */ 125 #define EVENT_CAPSET_ASSIGN_CAP 27 /* (capset, cap) */ 126 #define EVENT_CAPSET_REMOVE_CAP 28 /* (capset, cap) */ 127 /* the RTS identifier is in the form of "GHC-version rts_way" */ 128 #define EVENT_RTS_IDENTIFIER 29 /* (capset, name_version_string) */ 129 /* the vectors in these events are null separated strings */ 130 #define EVENT_PROGRAM_ARGS 30 /* (capset, commandline_vector) */ 131 #define EVENT_PROGRAM_ENV 31 /* (capset, environment_vector) */ 132 #define EVENT_OSPROCESS_PID 32 /* (capset, pid) */ 133 #define EVENT_OSPROCESS_PPID 33 /* (capset, parent_pid) */ 134 #define EVENT_SPARK_COUNTERS 34 /* (crt,dud,ovf,cnv,gcd,fiz,rem) */ 135 #define EVENT_SPARK_CREATE 35 /* () */ 136 #define EVENT_SPARK_DUD 36 /* () */ 137 #define EVENT_SPARK_OVERFLOW 37 /* () */ 138 #define EVENT_SPARK_RUN 38 /* () */ 139 #define EVENT_SPARK_STEAL 39 /* (victim_cap) */ 140 #define EVENT_SPARK_FIZZLE 40 /* () */ 141 #define EVENT_SPARK_GC 41 /* () */ 142 #define EVENT_INTERN_STRING 42 /* (string, id) {not used by ghc} */ 143 #define EVENT_WALL_CLOCK_TIME 43 /* (capset, unix_epoch_seconds, nanoseconds) */ 144 #define EVENT_THREAD_LABEL 44 /* (thread, name_string) */ 145 #define EVENT_CAP_CREATE 45 /* (cap) */ 146 #define EVENT_CAP_DELETE 46 /* (cap) */ 147 #define EVENT_CAP_DISABLE 47 /* (cap) */ 148 #define EVENT_CAP_ENABLE 48 /* (cap) */ 149 #define EVENT_HEAP_ALLOCATED 49 /* (heap_capset, alloc_bytes) */ 150 #define EVENT_HEAP_SIZE 50 /* (heap_capset, size_bytes) */ 151 #define EVENT_HEAP_LIVE 51 /* (heap_capset, live_bytes) */ 152 #define EVENT_HEAP_INFO_GHC 52 /* (heap_capset, n_generations, 153 max_heap_size, alloc_area_size, 154 mblock_size, block_size) */ 155 #define EVENT_GC_STATS_GHC 53 /* (heap_capset, generation, 156 copied_bytes, slop_bytes, frag_bytes, 157 par_n_threads, 158 par_max_copied, par_tot_copied) */ 159 #define EVENT_GC_GLOBAL_SYNC 54 /* () */ 160 #define EVENT_TASK_CREATE 55 /* (taskID, cap, tid) */ 161 #define EVENT_TASK_MIGRATE 56 /* (taskID, cap, new_cap) */ 162 #define EVENT_TASK_DELETE 57 /* (taskID) */ 163 #define EVENT_USER_MARKER 58 /* (marker_name) */ 164 #define EVENT_HACK_BUG_T9003 59 /* Hack: see trac #9003 */ 165 166 /* Range 60 - 80 is used by eden for parallel tracing 167 * see http://www.mathematik.uni-marburg.de/~eden/ 168 */ 169 170 /* these are used by eden but are replaced by new alternatives for ghc */ 171 #define EVENT_VERSION 23 /* (version_string) */ 172 #define EVENT_PROGRAM_INVOCATION 24 /* (commandline_string) */ 173 174 /* start of parallel trace events */ 175 #define EVENT_EDEN_START_RECEIVE 60 /* () */ 176 #define EVENT_EDEN_END_RECEIVE 61 /* () */ 177 #define EVENT_CREATE_PROCESS 62 /* (process) */ 178 #define EVENT_KILL_PROCESS 63 /* (process) */ 179 #define EVENT_ASSIGN_THREAD_TO_PROCESS 64 /* (thread, process) */ 180 #define EVENT_CREATE_MACHINE 65 /* (machine, startupTime(in 10^-8 seconds after 19xx)) */ 181 #define EVENT_KILL_MACHINE 66 /* (machine) */ 182 #define EVENT_SEND_MESSAGE 67 /* (tag, sender_process, sender_thread, receiver_machine, receiver_process, receiver_inport) */ 183 #define EVENT_RECEIVE_MESSAGE 68 /* (tag, receiver_process, receiver_inport, sender_machine, sender_process, sender_outport, message_size) */ 184 #define EVENT_SEND_RECEIVE_LOCAL_MESSAGE 69 /* (tag, sender_process, sender_thread, receiver_process, receiver_inport) */ 185 186 187 /* Range 100 - 139 is reserved for Mercury, see below. */ 188 189 /* Range 140 - 159 is reserved for Perf events, see below. */ 190 191 /* Range 160 - 180 is reserved for cost-centre heap profiling events. */ 192 193 #define EVENT_HEAP_PROF_BEGIN 160 194 #define EVENT_HEAP_PROF_COST_CENTRE 161 195 #define EVENT_HEAP_PROF_SAMPLE_BEGIN 162 196 #define EVENT_HEAP_PROF_SAMPLE_COST_CENTRE 163 197 #define EVENT_HEAP_PROF_SAMPLE_STRING 164 198 #define EVENT_HEAP_PROF_SAMPLE_END 165 199 #define EVENT_HEAP_BIO_PROF_SAMPLE_BEGIN 166 200 #define EVENT_PROF_SAMPLE_COST_CENTRE 167 201 #define EVENT_PROF_BEGIN 168 202 203 #define EVENT_USER_BINARY_MSG 181 204 205 #define EVENT_CONC_MARK_BEGIN 200 206 #define EVENT_CONC_MARK_END 201 207 #define EVENT_CONC_SYNC_BEGIN 202 208 #define EVENT_CONC_SYNC_END 203 209 #define EVENT_CONC_SWEEP_BEGIN 204 210 #define EVENT_CONC_SWEEP_END 205 211 #define EVENT_CONC_UPD_REM_SET_FLUSH 206 212 #define EVENT_NONMOVING_HEAP_CENSUS 207 213 214 #define EVENT_TICKY_COUNTER_DEF 210 215 #define EVENT_TICKY_COUNTER_SAMPLE 211 216 217 /* 218 * The highest event code +1 that ghc itself emits. Note that some event 219 * ranges higher than this are reserved but not currently emitted by ghc. 220 * This must match the size of the EventDesc[] array in EventLog.c 221 */ 222 #define NUM_GHC_EVENT_TAGS 212 223 224 225 /* DEPRECATED EVENTS: */ 226 /* These two are deprecated because we don't need to record the thread, it's 227 implicit. We have to keep these #defines because for tiresome reasons we 228 still need to parse them, see GHC.RTS.Events.ghc6Parsers for details. */ 229 #define EVENT_RUN_SPARK 5 /* (thread) */ 230 #define EVENT_STEAL_SPARK 6 /* (thread, victim_cap) */ 231 /* shutdown replaced by EVENT_CAP_DELETE */ 232 #define EVENT_SHUTDOWN 7 /* () */ 233 #if 0 234 /* ghc changed how it handles sparks so these are no longer applicable */ 235 #define EVENT_CREATE_SPARK 13 /* (cap, thread) */ 236 #define EVENT_SPARK_TO_THREAD 14 /* (cap, thread, spark_thread) */ 237 #endif 238 #define EVENT_STARTUP 17 /* (num_capabilities) */ 239 240 241 /* 242 * These event types are Mercury specific, Mercury may use up to event number 243 * 139 244 */ 245 #define EVENT_FIRST_MER_EVENT 100 246 #define NUM_MER_EVENTS 14 247 248 #define EVENT_MER_START_PAR_CONJUNCTION 100 /* (dyn id, static id) */ 249 #define EVENT_MER_STOP_PAR_CONJUNCTION 101 /* (dyn id) */ 250 #define EVENT_MER_STOP_PAR_CONJUNCT 102 /* (dyn id) */ 251 #define EVENT_MER_CREATE_SPARK 103 /* (dyn id, spark id) */ 252 #define EVENT_MER_FUT_CREATE 104 /* (fut id, memo'd name id) */ 253 #define EVENT_MER_FUT_WAIT_NOSUSPEND 105 /* (fut id) */ 254 #define EVENT_MER_FUT_WAIT_SUSPENDED 106 /* (fut id) */ 255 #define EVENT_MER_FUT_SIGNAL 107 /* (fut id) */ 256 #define EVENT_MER_LOOKING_FOR_GLOBAL_CONTEXT \ 257 108 /* () */ 258 #define EVENT_MER_WORK_STEALING 109 /* () */ 259 #define EVENT_MER_LOOKING_FOR_LOCAL_SPARK \ 260 112 /* () */ 261 #define EVENT_MER_RELEASE_CONTEXT 110 /* (context id) */ 262 #define EVENT_MER_ENGINE_SLEEPING 111 /* () */ 263 #define EVENT_MER_CALLING_MAIN 113 /* () */ 264 265 266 /* 267 * These event types are parsed from hardware performance counters logs, 268 * such as the Linux Performance Counters data available through 269 * the perf subsystem. 270 */ 271 272 #define EVENT_PERF_NAME 140 /* (perf_num, name) */ 273 #define EVENT_PERF_COUNTER 141 /* (perf_num, tid, period) */ 274 #define EVENT_PERF_TRACEPOINT 142 /* (perf_num, tid) */ 275 276 277 /* 278 * Status values for EVENT_STOP_THREAD 279 * 280 * 1-5 are the StgRun return values (from includes/rts/Constants.h): 281 * 282 * #define HeapOverflow 1 283 * #define StackOverflow 2 284 * #define ThreadYielding 3 285 * #define ThreadBlocked 4 286 * #define ThreadFinished 5 287 * #define ForeignCall 6 288 * #define BlockedOnMVar 7 289 * #define BlockedOnMVarRead 20 290 * NOTE: in GHC-7.8.2, this was 8, and following states shifted one up 291 * #define BlockedOnBlackHole 8 292 * #define BlockedOnRead 9 293 * #define BlockedOnWrite 10 294 * #define BlockedOnDelay 11 295 * #define BlockedOnSTM 12 296 * #define BlockedOnDoProc 13 297 * NOTE: unused GUM states 8, 9 (here: 14,15) in rts/Constants.h 298 * #define BlockedOnCCall -- not used (see ForeignCall) 299 * #define BlockedOnCCall_NoUnblockExc -- not used (see ForeignCall) 300 * #define BlockedOnMsgThrowTo 16 301 * NOTE: 16 because unused GUM states ignored in ghc-events lib 302 * Otherwise it would be 18, following would be 19, 20 303 * TODO: verify the above is what GHC does (16/17 could be 18/19) 304 * #define ThreadMigrating 17 305 * #define BlockedOnMsgGlobalise 18 306 * NOTE: not present in GHC. Mercury-Event? 307 */ 308 #define THREAD_SUSPENDED_FOREIGN_CALL 6 309 310 /* 311 * Capset type values for EVENT_CAPSET_CREATE 312 */ 313 #define CAPSET_TYPE_CUSTOM 1 /* reserved for end-user applications */ 314 #define CAPSET_TYPE_OSPROCESS 2 /* caps belong to the same OS process */ 315 #define CAPSET_TYPE_CLOCKDOMAIN 3 /* caps share a local clock/time */ 316 317 #ifndef EVENTLOG_CONSTANTS_ONLY 318 319 typedef StgWord16 EventTypeNum; 320 typedef StgWord64 EventTimestamp; /* in nanoseconds */ 321 typedef StgWord32 EventThreadID; 322 typedef StgWord16 EventCapNo; 323 typedef StgWord16 EventPayloadSize; /* variable-size events */ 324 typedef StgWord16 EventThreadStatus; /* status for EVENT_STOP_THREAD */ 325 typedef StgWord32 EventCapsetID; 326 typedef StgWord16 EventCapsetType; /* types for EVENT_CAPSET_CREATE */ 327 typedef StgWord64 EventTaskId; /* for EVENT_TASK_* */ 328 typedef StgWord64 EventKernelThreadId; /* for EVENT_TASK_CREATE */ 329 330 typedef StgWord32 EventProcessID; 331 typedef StgWord16 EventMachineID; 332 typedef EventThreadID EventPortID; 333 334 #endif 335 336 #endif /* RTS_EVENTLOGFORMAT_H */ 337