Merge pull request #576 from rdeodhar/ur_qprop

Add queue properties to support immediate and batched submissions.

Author: kbenzie

include/ur.py

@@ -1557,6 +1557,10 @@ class ur_queue_flags_v(IntEnum):
     DISCARD_EVENTS = UR_BIT(4)                      ## Events will be discarded
     PRIORITY_LOW = UR_BIT(5)                        ## Low priority queue
     PRIORITY_HIGH = UR_BIT(6)                       ## High priority queue
+    SUBMISSION_BATCHED = UR_BIT(7)                  ## Hint: enqueue and submit in a batch later. No change in queue
+                                                    ## semantics. Implementation chooses submission mode.
+    SUBMISSION_IMMEDIATE = UR_BIT(8)                ## Hint: enqueue and submit immediately. No change in queue semantics.
+                                                    ## Implementation chooses submission mode.
 
 class ur_queue_flags_t(c_int):
     def __str__(self):

include/ur_api.h

@@ -4039,13 +4039,17 @@ typedef enum ur_queue_flag_t {
     UR_QUEUE_FLAG_DISCARD_EVENTS = UR_BIT(4),                ///< Events will be discarded
     UR_QUEUE_FLAG_PRIORITY_LOW = UR_BIT(5),                  ///< Low priority queue
     UR_QUEUE_FLAG_PRIORITY_HIGH = UR_BIT(6),                 ///< High priority queue
+    UR_QUEUE_FLAG_SUBMISSION_BATCHED = UR_BIT(7),            ///< Hint: enqueue and submit in a batch later. No change in queue
+                                                             ///< semantics. Implementation chooses submission mode.
+    UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE = UR_BIT(8),          ///< Hint: enqueue and submit immediately. No change in queue semantics.
+                                                             ///< Implementation chooses submission mode.
     /// @cond
     UR_QUEUE_FLAG_FORCE_UINT32 = 0x7fffffff
     /// @endcond
 
 } ur_queue_flag_t;
 /// @brief Bit Mask for validating ur_queue_flags_t
-#define UR_QUEUE_FLAGS_MASK 0xffffff80
+#define UR_QUEUE_FLAGS_MASK 0xfffffe00
 
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Query information about a command queue

scripts/core/queue.yml

@@ -62,6 +62,12 @@ etors:
     - name: PRIORITY_HIGH
       value: "$X_BIT(6)"
       desc: "High priority queue"
+    - name: SUBMISSION_BATCHED
+      value: "$X_BIT(7)"
+      desc: "Hint: enqueue and submit in a batch later. No change in queue semantics. Implementation chooses submission mode."
+    - name: SUBMISSION_IMMEDIATE
+      value: "$X_BIT(8)"
+      desc: "Hint: enqueue and submit immediately. No change in queue semantics. Implementation chooses submission mode."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Query information about a command queue"

source/common/ur_params.hpp

@@ -7442,6 +7442,14 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_queue_flag_t value) {
     case UR_QUEUE_FLAG_PRIORITY_HIGH:
         os << "UR_QUEUE_FLAG_PRIORITY_HIGH";
         break;
+
+    case UR_QUEUE_FLAG_SUBMISSION_BATCHED:
+        os << "UR_QUEUE_FLAG_SUBMISSION_BATCHED";
+        break;
+
+    case UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE:
+        os << "UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -7530,6 +7538,28 @@ inline void serializeFlag<ur_queue_flag_t>(std::ostream &os, uint32_t flag) {
         }
         os << UR_QUEUE_FLAG_PRIORITY_HIGH;
     }
+
+    if ((val & UR_QUEUE_FLAG_SUBMISSION_BATCHED) ==
+        (uint32_t)UR_QUEUE_FLAG_SUBMISSION_BATCHED) {
+        val ^= (uint32_t)UR_QUEUE_FLAG_SUBMISSION_BATCHED;
+        if (!first) {
+            os << " | ";
+        } else {
+            first = false;
+        }
+        os << UR_QUEUE_FLAG_SUBMISSION_BATCHED;
+    }
+
+    if ((val & UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE) ==
+        (uint32_t)UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE) {
+        val ^= (uint32_t)UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE;
+        if (!first) {
+            os << " | ";
+        } else {
+            first = false;
+        }
+        os << UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE;
+    }
     if (val != 0) {
         std::bitset<32> bits(val);
         if (!first) {

test/conformance/queue/urQueueCreate.cpp

@@ -77,14 +77,23 @@ TEST_P(urQueueCreateTest, InvalidValueProperties) {
 }
 
 TEST_P(urQueueCreateTest, InvalidQueueProperties) {
-    ur_queue_handle_t queue = nullptr;
-
-    // It should be an error to specify both low/high priorities
     ur_queue_properties_t props = {
         /*.stype =*/UR_STRUCTURE_TYPE_QUEUE_PROPERTIES,
         /*.pNext =*/nullptr,
         /*.flags =*/UR_QUEUE_FLAG_PRIORITY_HIGH | UR_QUEUE_FLAG_PRIORITY_LOW,
     };
-    ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_QUEUE_PROPERTIES,
-                     urQueueCreate(context, device, &props, &queue));
+    // It should be an error to specify both low/high priorities
+    {
+        ur_queue_handle_t queue = nullptr;
+        ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_QUEUE_PROPERTIES,
+                         urQueueCreate(context, device, &props, &queue));
+    }
+    // It should be an error to specify both batched and immediate submission
+    {
+        ur_queue_handle_t queue = nullptr;
+        props.flags = UR_QUEUE_FLAG_SUBMISSION_BATCHED |
+                      UR_QUEUE_FLAG_SUBMISSION_IMMEDIATE;
+        ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_QUEUE_PROPERTIES,
+                         urQueueCreate(context, device, &props, &queue));
+    }
 }