From 42fc26c4f5b0543620111ccf8c84a121d87d2c3c Mon Sep 17 00:00:00 2001
From: Jaime Arteaga <jaime.a.arteaga.molina@intel.com>
Date: Tue, 28 Feb 2023 11:45:00 -0800
Subject: [PATCH] Add extension for global metrics timestamps (#78)

Add extension for global metrics timestamps.

Resolves: #11

Signed-off-by: Jaime Arteaga <jaime.a.arteaga.molina@intel.com>
---
 scripts/tools/EXT_Exp_GlobalTimestamps.rst | 28 +++++++++
 scripts/tools/GlobalTimestamps.yml         | 68 ++++++++++++++++++++++
 scripts/tools/common.yml                   |  3 +
 3 files changed, 99 insertions(+)
 create mode 100644 scripts/tools/EXT_Exp_GlobalTimestamps.rst
 create mode 100644 scripts/tools/GlobalTimestamps.yml

diff --git a/scripts/tools/EXT_Exp_GlobalTimestamps.rst b/scripts/tools/EXT_Exp_GlobalTimestamps.rst
new file mode 100644
index 000000000..919f835f0
--- /dev/null
+++ b/scripts/tools/EXT_Exp_GlobalTimestamps.rst
@@ -0,0 +1,28 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+    t=tags['$t']
+    T=t.upper()
+%>
+:orphan:
+
+.. _ZET_experimental_global_metric_timestamps:
+
+==========================================
+Global Metrics Timestamps Extension
+==========================================
+
+API
+----
+
+* Structures
+
+    * ${t}_metric_global_timestamps_resolution_exp_t
+
+* Functions
+
+    * ${t}MetricGroupGetGlobalTimestampsExp
\ No newline at end of file
diff --git a/scripts/tools/GlobalTimestamps.yml b/scripts/tools/GlobalTimestamps.yml
new file mode 100644
index 000000000..cb01c6448
--- /dev/null
+++ b/scripts/tools/GlobalTimestamps.yml
@@ -0,0 +1,68 @@
+#
+# Copyright (C) 2023 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Tool Experimental Extension for Global Metric Timestamps"
+version: "1.5"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Global Metric Timestamps Experimental Extension Name"
+version: "1.5"
+name: $T_GLOBAL_METRICS_TIMESTAMPS_EXP_NAME
+value: '"$XT_experimental_global_metric_timestamps"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Global Metric Timestamps Experimental Extension Version(s)"
+version: "1.5"
+name: $x_metric_global_timestamps_exp_version_t
+etors:
+    - name: "1_0"
+      value: "$X_MAKE_VERSION( 1, 0 )"
+      desc: "version 1.0"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Metric timestamps resolution"
+version: "1.5"
+class: $tMetric
+name: $t_metric_global_timestamps_resolution_exp_t
+base: $x_base_desc_t
+members:
+    - type: uint64_t
+      name: timerResolution
+      desc: "[out] Returns the resolution of device timer in nanoseconds used for timestamps."
+    - type: uint64_t
+      name: timestampValidBits
+      desc: "[out] Returns the number of valid bits in the timestamp value."
+details:
+    - "This structure may be returned from $tMetricGroupGetProperties via `pNext` member of $t_metric_group_properties_t"
+    - "Used for mapping metric timestamps to other timers."
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Returns metric timestamps synchronized with global device timestamps, optionally synchronized with host"
+class: $tMetricGroup
+name: GetGlobalTimestampsExp
+decl: static
+details:
+    - "The application may call this function from simultaneous threads."
+    - "By default, the global and metrics timestamps are synchronized to the device."
+params:
+    - type: "$t_metric_group_handle_t"
+      name: hMetricGroup
+      desc: "[in] handle of the metric group"
+    - type: "$x_bool_t"
+      name: synchronizedWithHost
+      desc: "[in] Returns the timestamps synchronized to the host or the device."
+      init: "false"
+    - type: "uint64_t*"
+      name: globalTimestamp
+      desc: |
+            [out] Device timestamp.
+    - type: "uint64_t*"
+      name: metricTimestamp
+      desc: |
+            [out] Metric timestamp.
\ No newline at end of file
diff --git a/scripts/tools/common.yml b/scripts/tools/common.yml
index 69d629090..d0f889520 100644
--- a/scripts/tools/common.yml
+++ b/scripts/tools/common.yml
@@ -102,6 +102,9 @@ etors:
       desc: $t_debug_memory_space_desc_t
     - name: DEBUG_REGSET_PROPERTIES
       desc: $t_debug_regset_properties_t
+    - name: GLOBAL_METRICS_TIMESTAMPS_EXP_PROPERTIES
+      desc: $t_metric_global_timestamps_resolution_exp_t
+      version: "1.5"
     - name: TRACER_EXP_DESC
       desc: $t_tracer_exp_desc_t
       value: "0x00010001"