From 841c33a083decc559195b94837e65ac73b6bfd16 Mon Sep 17 00:00:00 2001
From: Igor Chorazewicz <igor.chorazewicz@intel.com>
Date: Wed, 30 Jul 2025 19:12:09 +0000
Subject: [PATCH 1/3] [SYCL][UR][L0 v2] Add a note about make_queue support

and return an error if urQueueCreateWithNativeHandle is
called with `ze_command_queue_handle_t`.

V2 adapter does not support non-immediate or out-of-order
command lists. Document this in the extension doc.

Currently, there is no way to check whether a command-list
is in order or not programatically.
---
 .../sycl_ext_oneapi_backend_level_zero.md     |  2 ++
 .../adapters/level_zero/v2/queue_create.cpp   | 20 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
index a190cb5a47ae0..3a0059ee5c6bd 100644
--- a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
+++ b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
@@ -388,6 +388,8 @@ If the deprecated variant of <code>backend_input_t<backend::ext_oneapi_level_zer
 
 Starting in version 4 of this specification, ```make_queue()``` can be called by passing either a Level Zero ```ze_command_queue_handle_t``` or a Level Zero ```ze_command_list_handle_t```. Queues created from a Level Zero immediate command list (```ze_command_list_handle_t```) generally perform better than queues created from a standard Level Zero ```ze_command_queue_handle_t```. See the Level Zero documentation of these native handles for more details. Also starting in version 4 the ```make_queue()``` function accepts a ```Properties``` member variable. This can contain any of the SYCL properties that are accepted by the SYCL queue constructor, except
 the ```compute_index``` property which is built into the command queue or command list.
+
+**Warning:** <span style="color:red"> When L0 v2 adapter is used (when running on platforms with GPUs based on the Xe2 architecture or later, such as Battlemage, Lunar Lake, and Arrow Lake or when SYCL_UR_USE_LEVEL_ZERO_V2=1 is set) ```make_queue()``` accepts only ```ze_command_list_handle_t```: a handle to an **immediate**, **in-order** command list. If non-immediate or out-of-order command list support is needed, the legacy adapter should be used (by setting SYCL_UR_USE_LEVEL_ZERO_V2=0)</span>
 </td>
 </tr><tr>
 <td>
diff --git a/unified-runtime/source/adapters/level_zero/v2/queue_create.cpp b/unified-runtime/source/adapters/level_zero/v2/queue_create.cpp
index a8270b192dfb7..be211cb198438 100644
--- a/unified-runtime/source/adapters/level_zero/v2/queue_create.cpp
+++ b/unified-runtime/source/adapters/level_zero/v2/queue_create.cpp
@@ -94,6 +94,7 @@ ur_result_t urQueueCreateWithNativeHandle(
 
   bool ownNativeHandle = pProperties ? pProperties->isNativeHandleOwned : false;
   ur_queue_flags_t flags = 0;
+  bool isNativeHandleImmediate = true;
 
   if (pProperties) {
     void *pNext = pProperties->pNext;
@@ -104,11 +105,30 @@ ur_result_t urQueueCreateWithNativeHandle(
         const ur_queue_properties_t *pUrProperties =
             reinterpret_cast<const ur_queue_properties_t *>(extendedProperties);
         flags = pUrProperties->flags;
+      } else if (extendedProperties->stype ==
+                 UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC) {
+        const ur_queue_native_desc_t *pUrNativeDesc =
+            reinterpret_cast<const ur_queue_native_desc_t *>(
+                extendedProperties);
+        if (pUrNativeDesc->pNativeData) {
+          // The pNativeData has value if if the native handle is an immediate
+          // command list.
+          isNativeHandleImmediate =
+              *(reinterpret_cast<int32_t *>((pUrNativeDesc->pNativeData))) == 1;
+        }
       }
       pNext = extendedProperties->pNext;
     }
   }
 
+  if (!isNativeHandleImmediate) {
+    UR_LOG(ERR, "urQueueCreateWithNativeHandle: "
+                "Native handle is not an immediate command "
+                "list; only immediate command lists are "
+                "supported.");
+    return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+  }
+
   ze_bool_t isImmediate = false;
   ZE2UR_CALL(
       zeCommandListIsImmediate,

From 303b37ec1f6b6740176af117fd4fda183096e745 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Igor=20Chor=C4=85=C5=BCewicz?= <igor.chorazewicz@intel.com>
Date: Thu, 31 Jul 2025 08:44:52 -0700
Subject: [PATCH 2/3] Update
 sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md

Co-authored-by: John Pennycook <john.pennycook@intel.com>
---
 .../extensions/supported/sycl_ext_oneapi_backend_level_zero.md  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
index 3a0059ee5c6bd..a2f02448c8a3a 100644
--- a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
+++ b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
@@ -389,7 +389,7 @@ If the deprecated variant of <code>backend_input_t<backend::ext_oneapi_level_zer
 Starting in version 4 of this specification, ```make_queue()``` can be called by passing either a Level Zero ```ze_command_queue_handle_t``` or a Level Zero ```ze_command_list_handle_t```. Queues created from a Level Zero immediate command list (```ze_command_list_handle_t```) generally perform better than queues created from a standard Level Zero ```ze_command_queue_handle_t```. See the Level Zero documentation of these native handles for more details. Also starting in version 4 the ```make_queue()``` function accepts a ```Properties``` member variable. This can contain any of the SYCL properties that are accepted by the SYCL queue constructor, except
 the ```compute_index``` property which is built into the command queue or command list.
 
-**Warning:** <span style="color:red"> When L0 v2 adapter is used (when running on platforms with GPUs based on the Xe2 architecture or later, such as Battlemage, Lunar Lake, and Arrow Lake or when SYCL_UR_USE_LEVEL_ZERO_V2=1 is set) ```make_queue()``` accepts only ```ze_command_list_handle_t```: a handle to an **immediate**, **in-order** command list. If non-immediate or out-of-order command list support is needed, the legacy adapter should be used (by setting SYCL_UR_USE_LEVEL_ZERO_V2=0)</span>
+**Warning:** <span style="color:red"> When using the L0 v2 adapter, ```make_queue()``` only accepts ```ze_command_list_handle_t```. The L0 v2 adapter is always used when running on platforms with GPUs based on the Xe2 architecture or later, such as Battlemage, Lunar Lake, and Arrow Lake. Applications may also opt-in to the L0 v2 adapter using the `SYCL_UR_USE_LEVEL_ZERO_V2` environment variable.</span>
 </td>
 </tr><tr>
 <td>

From 524978983692135366ed24fcd3fc5db4b80a81d7 Mon Sep 17 00:00:00 2001
From: Igor Chorazewicz <igor.chorazewicz@intel.com>
Date: Thu, 31 Jul 2025 16:49:11 +0000
Subject: [PATCH 3/3] Add in-order requirement

---
 .../extensions/supported/sycl_ext_oneapi_backend_level_zero.md  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
index a2f02448c8a3a..a4a09377b93b2 100644
--- a/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
+++ b/sycl/doc/extensions/supported/sycl_ext_oneapi_backend_level_zero.md
@@ -389,7 +389,7 @@ If the deprecated variant of <code>backend_input_t<backend::ext_oneapi_level_zer
 Starting in version 4 of this specification, ```make_queue()``` can be called by passing either a Level Zero ```ze_command_queue_handle_t``` or a Level Zero ```ze_command_list_handle_t```. Queues created from a Level Zero immediate command list (```ze_command_list_handle_t```) generally perform better than queues created from a standard Level Zero ```ze_command_queue_handle_t```. See the Level Zero documentation of these native handles for more details. Also starting in version 4 the ```make_queue()``` function accepts a ```Properties``` member variable. This can contain any of the SYCL properties that are accepted by the SYCL queue constructor, except
 the ```compute_index``` property which is built into the command queue or command list.
 
-**Warning:** <span style="color:red"> When using the L0 v2 adapter, ```make_queue()``` only accepts ```ze_command_list_handle_t```. The L0 v2 adapter is always used when running on platforms with GPUs based on the Xe2 architecture or later, such as Battlemage, Lunar Lake, and Arrow Lake. Applications may also opt-in to the L0 v2 adapter using the `SYCL_UR_USE_LEVEL_ZERO_V2` environment variable.</span>
+**Warning:** <span style="color:red"> When using the L0 v2 adapter, ```make_queue()``` only accepts ```ze_command_list_handle_t```. The command list has to be in-order. The L0 v2 adapter is always used when running on platforms with GPUs based on the Xe2 architecture or later, such as Battlemage, Lunar Lake, and Arrow Lake. Applications may also opt-in to the L0 v2 adapter using the `SYCL_UR_USE_LEVEL_ZERO_V2` environment variable. </span>
 </td>
 </tr><tr>
 <td>