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

@@ -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"