..
 #
 # Critical Application Monitoring (CAM)
 #
 # SPDX-FileCopyrightText: <text>Copyright 2023-2024 Arm Limited
 # and/or its affiliates <open-source-office@arm.com></text>
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #

.. _CSEL_File:

############################
Stream Event Log File Format
############################

The CAM Stream Event Log (CSEL) file contains the events and other metadata
generated by a critical application whilst running in calibration mode. The
generated data is in binary format with the intent to improve throughput and
reduce the overhead in the critical applications.

The file is composed of multiple sections as described below. The sections must
be in the order as they appear in this specification.

Files should use the extension ``.csel``.

All multi-byte types are little-endian.

.. _CSEL_Timestamp:

About the timestamp fields:
  * The file format does not assume or enforce an epoch.
  * The format depends on the clock used by the application.

.. _CSEL_UUID:

About the Universally Unique Identifier (UUID) fields:
  * UUIDs are 16-byte long fields representing the 128-bit UUID in binary format
  * | The file format does not enforce any UUID variant. UUIDs are used as an
    | opaque data value and does not process the sub-fields of the UUID.

**************
Header Section
**************

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Signature
    - 4
    - ``0x4d, 0x46, 0x4d, 0x4e``
  * - Format version
    - 2
    - ``0x01, 0x00`` for the ``1.0`` version
  * - *Reserved*
    - 2
    -

****************
Metadata Section
****************

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - :ref:`UUID <CSEL_UUID>`
    - 16
    - Stream UUID
  * - Stream name
    - 64
    - 64-byte string (including null-character)
  * - :ref:`Timestamp <CSEL_Timestamp>`
    - 8
    - Unsigned integer, stream init timestamp

*********************
State Control Section
*********************

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Target timeout between init and start messages
    - 4
    - Unsigned integer, 0 indicates no timeout
  * - Target timeout between start and the first event
    - 4
    - Unsigned integer, cannot be zero

*******************
Log Entries Section
*******************

The remaining of the data is composed by zero or more entries as described
below.

From a file format perspective, entries are allowed to be in any order ensuring
that the files are deemed valid and allowing tools to process such files to
detect and report on any invalid event sequence.

Start
=====

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Entry identifier
    - 1
    - ``0x01`` - Stream start
  * - :ref:`Timestamp <CSEL_Timestamp>`
    - 8
    - Unsigned integer, stream start timestamp

Stop
====

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Entry identifier
    - 1
    - ``0x02`` - Stream stop
  * - :ref:`Timestamp <CSEL_Timestamp>`
    - 8
    - Unsigned integer, stream stop timestamp

End
===

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Entry identifier
    - 1
    - ``0x03`` - Stream end
  * - :ref:`Timestamp <CSEL_Timestamp>`
    - 8
    - Unsigned integer, stream end timestamp

Event
=====

.. list-table::
  :header-rows: 1

  * - Field
    - Size (in bytes)
    - Description
  * - Entry identifier
    - 1
    - ``0x04`` - Stream event
  * - :ref:`Timestamp <CSEL_Timestamp>`
    - 8
    - Unsigned integer, stream event timestamp
  * - Sequence identifier
    - 4
    - Unsigned integer
  * - Event identifier
    - 2
    - Unsigned integer
  * - *Reserved*
    - 2
    -