Add extension for global metrics timestamps (#78)

Add extension for global metrics timestamps.

Resolves: #11

Signed-off-by: Jaime Arteaga <[email protected]>

Author: Jaime Arteaga

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

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.

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"