Add experimental extension for counter-based events

scripts/core/EXT_Exp_CounterBasedEvents.rst

@@ -0,0 +1,50 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_experimental_event_counter_based:
+
+=========================
+ Counter-Based Events Extension
+=========================
+
+API
+----
+
+* Enumerations
+
+    * ${x}_event_counter_based_exp_flags_t
+    * ${x}_event_counter_based_exp_version_t
+
+* Structures
+
+    * ${x}_event_counter_based_exp_desc_t
+
+Counter-Based Events
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, events in Level Zero contains one of two states: signaled or not signaled.
+Signaling of an event, as well as resetting its state, can be done from either host or
+device.
+
+Another way of tracking the state of an event is by using a counter, which is incremented
+every time a task has completed in the device. Using a counter-based event may provide
+Level Zero driver implementations with the opportunity for both functional and performance
+optimizations.
+
+The following recommendations and restrictions apply to counter-based events:
+
+- Counter-based events can be used only with in-orders lists, whether those are regular or immediate.
+- Counter-based events must not be reset, i.e., a call to ${x}EventHostReset or ${x}CommandListAppendEventReset
+  is not allowed.
+- Counter-based events may be reused multiple times without a need for reset.
+- Counter-based events must not be signaled from host, i.e., a call to ${x}EventHostSignal is not allowed.
+- Counter-based events may be used on multiple command lists.
+- Querying a counter-based event queries only the last saved counter value from the last command list that incremented it.
+- Synchronizing on a counter-based event waits only the last saved counter value from the last command list that incremented it.

scripts/core/common.yml

@@ -508,6 +508,10 @@ etors:
       desc: $x_rtas_geometry_aabbs_exp_cb_params_t
       version: "1.7"
       value: "0x00020013"
+    - name: COUNTER_BASED_EVENT_EXP_DESC
+      desc: $x_event_counter_based_exp_desc_t
+      version: "1.8"
+      value: "0x00020014"
     - name: COMMAND_GRAPH_EXP_DESC
       desc: $x_command_graph_exp_desc_t
       version: "2.0"

scripts/core/counterbasedevent.yml

@@ -0,0 +1,51 @@
+#
+# Copyright (C) 2019-2022 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Extension APIs for Counter-based Events"
+version: "1.8"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Counter-based Events Extension Name"
+version: "1.4"
+name: $X_EVENT_COUNTER_BASED_EXP_NAME
+value: '"$X_experimental_event_counter_based"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Counter-based Events Extension Version(s)"
+version: "1.8"
+name: $x_event_counter_based_exp_version_t
+etors:
+    - name: "1_0"
+      value: "$X_MAKE_VERSION( 1, 0 )"
+      desc: "version 1.0"
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Supported event flags for defining counter-based events. Must "
+class: $xEvent
+name: $x_event_counter_based_exp_flags_t
+etors:
+    - name: IMMEDIATE
+      desc: "Counter-based event is used for immediate command lists (default)"
+    - name: NON_IMMEDIATE
+      desc: "Counter-based event is used for non-immediate command lists"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Event descriptor for counter-based events. This structure may be passed to $xEventCreate as pNext member of $x_event_desc_t."
+class: $xEvent
+version: "1.8"
+name: $x_event_counter_based_exp_desc_t
+base: $x_base_desc_t
+members:
+    - type: $x_event_counter_based_exp_flags_t
+      name: flags
+      desc: |
+            [in] mode flags.
+            must be 0 (default) or a valid value of $x_event_counter_based_exp_flag_t
+            default behavior is counter-based event is only used for immediate command lists.
+      init: "0"