[SYCL][UR][L0 v2] Add a note about make_queue support (#19644)

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.

---------

Co-authored-by: John Pennycook <[email protected]>

Author: igchor

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 using the L0 v2 adapter, ```make_queue()``` only accepts ```ze_command_list_handle_t```. The command list has to be in-order. Passing an out-of-order command list is undefined behavior. 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>

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,