diff options
author | Ben Gamari <ben@smart-cactus.org> | 2020-04-23 22:57:24 -0400 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2020-05-03 04:41:33 -0400 |
commit | c560dd07f506810eaabae2f582491138aa224819 (patch) | |
tree | 012ef93bd92386f8ea5cd2207285fa5ff07006af /includes | |
parent | 7bfe9ac514e18c0b0e24ff55230fe98ec9db894c (diff) | |
download | haskell-c560dd07f506810eaabae2f582491138aa224819.tar.gz |
users guide: Move eventlog documentation users guide
Diffstat (limited to 'includes')
-rw-r--r-- | includes/rts/EventLogFormat.h | 58 |
1 files changed, 9 insertions, 49 deletions
diff --git a/includes/rts/EventLogFormat.h b/includes/rts/EventLogFormat.h index d5ed01a864..89a07bf5e1 100644 --- a/includes/rts/EventLogFormat.h +++ b/includes/rts/EventLogFormat.h @@ -9,65 +9,25 @@ * of the format, and new tools will be able to understand old log * files. * - * Each event has a specific format. If you add new events, give them - * new numbers: we never re-use old event numbers. - * - * - The format is endian-independent: all values are represented in - * bigendian order. - * - * - The format is extensible: - * - * - The header describes each event type and its length. Tools - * that don't recognise a particular event type can skip those events. - * - * - There is room for extra information in the event type - * specification, which can be ignored by older tools. - * - * - Events can have extra information added, but existing fields - * cannot be changed. Tools should ignore extra fields at the - * end of the event record. - * - * - Old event type ids are never re-used; just take a new identifier. - * - * - * The format - * ---------- - * - * log : EVENT_HEADER_BEGIN - * EventType* - * EVENT_HEADER_END - * EVENT_DATA_BEGIN - * Event* - * EVENT_DATA_END - * - * EventType : - * EVENT_ET_BEGIN - * Word16 -- unique identifier for this event - * Int16 -- >=0 size of the event in bytes (minus the header) - * -- -1 variable size - * Word32 -- length of the next field in bytes - * Word8* -- string describing the event - * Word32 -- length of the next field in bytes - * Word8* -- extra info (for future extensions) - * EVENT_ET_END - * - * Event : - * Word16 -- event_type - * Word64 -- time (nanosecs) - * [Word16] -- length of the rest (for variable-sized events only) - * ... extra event-specific info ... - * + * The canonical documentation for the event log format and record layouts is + * the "Eventlog encodings" section of the GHC User's Guide. * * To add a new event * ------------------ * * - In this file: - * - give it a new number, add a new #define EVENT_XXX below + * - give it a new number, add a new #define EVENT_XXX + * below. Do not reuse event ids from deprecated event types. + * * - In EventLog.c * - add it to the EventDesc array * - emit the event type in initEventLogging() * - emit the new event in postEvent_() * - generate the event itself by calling postEvent() somewhere + * + * - Describe the meaning and encoding of the event in the users guide + * (docs/user_guide/eventlog-formats.rst) + * * - In the Haskell code to parse the event log file: * - add types and code to read the new event * |