diff --git a/scripts/core/EXT_Exp_CounterBasedEventPools.rst b/scripts/core/EXT_Exp_CounterBasedEventPools.rst new file mode 100644 index 000000000..5b5f7ab05 --- /dev/null +++ b/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)); diff --git a/scripts/core/common.yml b/scripts/core/common.yml index 7c8583285..c5231f0ee 100644 --- a/scripts/core/common.yml +++ b/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" diff --git a/scripts/core/counterbasedeventpool.yml b/scripts/core/counterbasedeventpool.yml new file mode 100644 index 000000000..b4f08e08a --- /dev/null +++ b/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" \ No newline at end of file