From b06e5dd8a2b258d5d6f3676c9f424cc09d4d73f3 Mon Sep 17 00:00:00 2001 From: Adam Sandberg Ericsson Date: Sat, 12 Feb 2022 10:48:49 +0000 Subject: docs: clarify the eventlog format documentation a little bit --- docs/users_guide/eventlog-formats.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/users_guide/eventlog-formats.rst b/docs/users_guide/eventlog-formats.rst index b8ad8f32d9..1affa13151 100644 --- a/docs/users_guide/eventlog-formats.rst +++ b/docs/users_guide/eventlog-formats.rst @@ -36,13 +36,14 @@ files. cannot be changed. Tools should ignore extra fields at the end of the event record. -The event-log stream begins with a header describing the event types present in -the file. The header is followed by the event records themselves, each of which -consist of a 64-bit timestamp +The event-log stream begins with a header describing the event types (``EventType``) present in +the file. The header is followed by the event records (``Event``) themselves, each of which +start with the event type id and a 64-bit timestamp: .. code-block:: none - log : EVENT_HEADER_BEGIN + EventLog : + EVENT_HEADER_BEGIN EventType* EVENT_HEADER_END EVENT_DATA_BEGIN @@ -51,25 +52,25 @@ consist of a 64-bit timestamp EventType : EVENT_ET_BEGIN - Word16 -- unique identifier for this event - Int16 -- >=0 size of the event in bytes (minus the header) + Word16 -- event type id, unique identifier for this event + Int16 -- >=0 size of the event record in bytes (minus the event type id and timestamp fields) -- -1 variable size - Word32 -- length of the next field in bytes - Word8* -- string describing the event - Word32 -- length of the next field in bytes + Word32 -- size of the event description in bytes + Word8* -- event description, UTF8 encoded string describing the event + Word32 -- size of the extra info 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 ... + Word16 -- event type id, as included in the event log header + Word64 -- timestamp (nanoseconds) + [Word16] -- length of the rest (optional, for variable-sized events only) + ... event specific info ... There are two classes of event types: - *Fixed size*: All event records of a fixed-sized type are of the same - length, given in the header event-log header. + length, the size given in the header event-log header. - *Variable size*: Each event record includes a length field. -- cgit v1.2.1