users guide: Move eventlog documentation users guide

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
  *