Add experimental extension for counter-based events (#221)

Resolves #145 

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

Author: Jaime Arteaga

scripts/core/EXT_Exp_CounterBasedEventPools.rst

@@ -0,0 +1,69 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_experimental_event_pool_counter_based:
+
+=====================================
+ Counter-Based Event Pools Extension
+=====================================
+
+API
+----
+ 
+* Enumerations
+
+    * ${x}_event_pool_counter_based_exp_flags_t
+    * ${x}_event_pool_counter_based_exp_version_t
+
+* Structures
+
+    * ${x}_event_pool_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 must not be signaled from host, i.e., a call to ${x}EventHostSignal is not allowed.
+- Counter-based events may be reused multiple times without a need for reset.
+- 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,
+  i.e., a signaled counter-based event always represents the completion of the last call to which it was passed as signal event.
+- Synchronizing on a counter-based event waits only for the last saved counter value from the last command list that incremented it.
+- A counter-based event may be passed as signaling event for a new append call without needing to wait for the signaling of
+  the last call where it was used.
+
+Counter-based events can be created by passing ${x}_event_pool_counter_based_exp_desc_t to ${x}EventPoolCreate
+as pNext member of ${x}_event_pool_desc_t.
+
+.. parsed-literal::
+
+    uint32_t numEvents = 2;
+    ${x}_event_pool_handle_t eventPool = {};
+    ${x}_event_pool_desc_t eventPoolDesc = {${X}_STRUCTURE_TYPE_EVENT_POOL_DESC};
+    eventPoolDesc.count = numEvents;
+
+    ${x}_event_pool_counter_based_exp_desc_t counterBasedDesc = {${X}_STRUCTURE_TYPE_COUNTER_BASED_EVENT_POOL_EXP_DESC};
+    counterBasedDesc.flags = ${X}_EVENT_POOL_COUNTER_BASED_EXP_FLAG_IMMEDIATE;
+    eventPoolDesc.pNext = &counterBasedDesc;
+
+    ${x}_result_t = zeEventPoolCreate(context, &eventPoolDesc, 1, &device, &eventPool));

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_POOL_EXP_DESC
+      desc: $x_event_pool_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/counterbasedeventpool.yml

@@ -0,0 +1,52 @@
+#
+# 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 Event Pools"
+version: "1.8"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Counter-based Event Pools Extension Name"
+version: "1.8"
+name: $X_EVENT_POOL_COUNTER_BASED_EXP_NAME
+value: '"$X_experimental_event_pool_counter_based"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Counter-based Event Pools Extension Version(s)"
+version: "1.8"
+name: $x_event_pool_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 event pools."
+class: $xEventPool
+name: $x_event_pool_counter_based_exp_flags_t
+version: "1.8"
+etors:
+    - name: IMMEDIATE
+      desc: "Counter-based event pool is used for immediate command lists (default)"
+    - name: NON_IMMEDIATE
+      desc: "Counter-based event pool is for non-immediate command lists"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Event pool descriptor for counter-based events. This structure may be passed to $xEventPoolCreate as pNext member of $x_event_pool_desc_t."
+class: $xEventPool
+version: "1.8"
+name: $x_event_pool_counter_based_exp_desc_t
+base: $x_base_desc_t
+members:
+    - type: $x_event_pool_counter_based_exp_flags_t
+      name: flags
+      desc: |
+            [in] mode flags.
+            must be 0 (default) or a valid value of $x_event_pool_counter_based_exp_flag_t
+            default behavior is counter-based event pool is only used for immediate command lists.
+      init: "0"