Making iree_hal_device_queue_execute take zero or one command buffer.

The practical reason to take multiple is multi-threaded encoding or
mixing those with different lifetimes (per-execution prefix/suffix
command buffers around a reusable command buffer, etc) but we don't
do this in practice and supporting only one makes it easier to
implement against all APIs but Vulkan.

Author: benvanik

experimental/web/sample_webgpu/main.c

@@ -794,8 +794,8 @@ static iree_status_t process_call_outputs(
     };
     status = iree_hal_device_queue_execute(
         device, IREE_HAL_QUEUE_AFFINITY_ANY, iree_hal_semaphore_list_empty(),
-        signal_semaphores, 1, &transfer_command_buffer,
-        /*binding_tables=*/NULL);
+        signal_semaphores, transfer_command_buffer,
+        iree_hal_buffer_binding_table_empty());
   }
   // TODO(scotttodd): Make this async - pass a wait source to iree_loop_wait_one
   //     1. create iree_hal_fence_t, iree_hal_fence_insert(fance, semaphore)

experimental/webgpu/webgpu_device.c

@@ -396,9 +396,8 @@ static iree_status_t iree_hal_webgpu_device_queue_execute(
     iree_hal_device_t* base_device, iree_hal_queue_affinity_t queue_affinity,
     const iree_hal_semaphore_list_t wait_semaphore_list,
     const iree_hal_semaphore_list_t signal_semaphore_list,
-    iree_host_size_t command_buffer_count,
-    iree_hal_command_buffer_t* const* command_buffers,
-    iree_hal_buffer_binding_table_t const* binding_tables) {
+    iree_hal_command_buffer_t* command_buffer,
+    iree_hal_buffer_binding_table_t binding_table) {
   iree_hal_webgpu_device_t* device = iree_hal_webgpu_device_cast(base_device);
 
   // TODO(benvanik): this currently assumes we are synchronizing on semaphores
@@ -410,11 +409,8 @@ static iree_status_t iree_hal_webgpu_device_queue_execute(
                                                     iree_infinite_timeout()));
 
   // TODO(benvanik): propagate errors to semaphores.
-  for (iree_host_size_t i = 0; i < command_buffer_count; i++) {
-    iree_hal_command_buffer_t* command_buffer = command_buffers[i];
-    IREE_RETURN_IF_ERROR(
-        iree_hal_webgpu_command_buffer_issue(command_buffer, device->queue));
-  }
+  IREE_RETURN_IF_ERROR(
+      iree_hal_webgpu_command_buffer_issue(command_buffer, device->queue));
 
   IREE_RETURN_IF_ERROR(iree_hal_semaphore_list_signal(signal_semaphore_list));
 

integrations/pjrt/src/iree_pjrt/common/api_impl.cc

@@ -590,8 +590,8 @@ iree_status_t BufferInstance::CopyToHost(void* dst, iree_host_size_t dst_size,
       device_.device(), IREE_HAL_QUEUE_AFFINITY_ANY,
       /*wait_semaphore_list=*/iree_hal_fence_semaphore_list(ready_fence_.get()),
       /*signal_semaphore_list=*/
-      iree_hal_fence_semaphore_list(dst_buffer_ready_fence.get()),
-      /*command_buffer_count=*/1, &transfer_cb, NULL));
+      iree_hal_fence_semaphore_list(dst_buffer_ready_fence.get()), transfer_cb,
+      iree_hal_buffer_binding_table_empty()));
 
   *out_done_event = copy_done_event;
   return iree_ok_status();
@@ -847,8 +847,8 @@ iree_status_t DeviceInstance::HostBufferToDeviceSplat(
       /*wait_semaphore_list=*/
       {1, &transfer_timeline_, &signal_alloca_complete},
       /*signal_semaphore_list=*/
-      {1, &transfer_timeline_, &signal_copy_complete},
-      /*command_buffer_count=*/1, &transfer_cb, NULL));
+      {1, &transfer_timeline_, &signal_copy_complete}, transfer_cb,
+      iree_hal_buffer_binding_table_empty()));
 
   // Wrap in a buffer view and return:
   iree::vm::ref<iree_hal_buffer_view_t> result_buffer_view;
@@ -1191,8 +1191,8 @@ iree_status_t DeviceInstance::HostBufferToDevice(
       /*wait_semaphore_list=*/
       {1, &transfer_timeline_, &signal_alloca_complete},
       /*signal_semaphore_list=*/
-      {1, &transfer_timeline_, &signal_copy_complete},
-      /*command_buffer_count=*/1, &transfer_cb, NULL));
+      {1, &transfer_timeline_, &signal_copy_complete}, transfer_cb,
+      iree_hal_buffer_binding_table_empty()));
 
   // Wrap in a buffer view and return.
   iree::vm::ref<iree_hal_buffer_view_t> result_buffer_view;

integrations/pjrt/src/iree_pjrt/common/iree_helpers.h

@@ -139,17 +139,16 @@ iree_status_t hal_device_queue_execute(
     iree_hal_device_t* device, iree_hal_queue_affinity_t queue_affinity,
     const iree_hal_semaphore_list_t wait_semaphore_list,
     const iree_hal_semaphore_list_t signal_semaphore_list,
-    iree_host_size_t command_buffer_count,
-    iree_hal_command_buffer_t* const* command_buffers) {
+    iree_hal_command_buffer_t* command_buffer) {
   if (LOGGING_ENABLED) {
     LogInvoke(__func__, "device=%p, wait={%s}, signal={%s}", device,
               SemaphoreListToString(wait_semaphore_list).c_str(),
               SemaphoreListToString(signal_semaphore_list).c_str());
   }
   return HandleStatus(__func__, iree_hal_device_queue_execute(
                                     device, queue_affinity, wait_semaphore_list,
-                                    signal_semaphore_list, command_buffer_count,
-                                    command_buffers, /*binding_tables=*/NULL));
+                                    signal_semaphore_list, command_buffer,
+                                    iree_hal_buffer_binding_table_empty()));
 }
 
 iree_status_t hal_fence_create(iree_host_size_t capacity,

runtime/bindings/python/hal.cc

@@ -499,7 +499,7 @@ void HalDevice::QueueDealloca(HalBuffer& buffer, py::handle wait_semaphores,
       "deallocating memory on queue");
 }
 
-void HalDevice::QueueExecute(py::handle command_buffers,
+void HalDevice::QueueExecute(py::handle command_buffer,
                              py::handle wait_semaphores,
                              py::handle signal_semaphores) {
   iree_hal_semaphore_list_t wait_list;
@@ -548,17 +548,14 @@ void HalDevice::QueueExecute(py::handle command_buffers,
   }
 
   // Unpack command buffers.
-  size_t cb_count = py::len(command_buffers);
-  iree_hal_command_buffer_t** cb_list =
-      static_cast<iree_hal_command_buffer_t**>(
-          alloca(sizeof(iree_hal_command_buffer_t*) * cb_count));
-  for (size_t i = 0; i < cb_count; ++i) {
-    cb_list[i] = py::cast<HalCommandBuffer*>(command_buffers[i])->raw_ptr();
-  }
+  iree_hal_command_buffer_t* cb =
+      !command_buffer.is_none()
+          ? py::cast<HalCommandBuffer*>(command_buffer)->raw_ptr()
+          : NULL;
 
   CheckApiStatus(iree_hal_device_queue_execute(
                      raw_ptr(), IREE_HAL_QUEUE_AFFINITY_ANY, wait_list,
-                     signal_list, cb_count, cb_list, /*binding_tables=*/NULL),
+                     signal_list, cb, iree_hal_buffer_binding_table_empty()),
                  "executing command buffers");
 }
 

runtime/bindings/python/iree/runtime/_binding.pyi

@@ -185,7 +185,7 @@ class HalDevice:
     ) -> None: ...
     def queue_execute(
         self,
-        command_buffers: Sequence[HalCommandBuffer],
+        command_buffer: HalCommandBuffer,
         wait_semaphores: HalSemaphoreList,
         signal_semaphores: HalSemaphoreList,
     ) -> None: ...

runtime/bindings/python/tests/hal_test.py

@@ -463,7 +463,7 @@ def testCommandBufferExecute(self):
 
         sem = self.device.create_semaphore(0)
         self.device.queue_execute(
-            [cb], wait_semaphores=[(sem, 0)], signal_semaphores=[(sem, 1)]
+            cb, wait_semaphores=[(sem, 0)], signal_semaphores=[(sem, 1)]
         )
         iree.runtime.HalFence.create_at(sem, 1).wait()
 
@@ -479,7 +479,7 @@ def testCommandBufferExecuteAcceptsFence(self):
 
         sem = self.device.create_semaphore(0)
         self.device.queue_execute(
-            [cb],
+            cb,
             wait_semaphores=iree.runtime.HalFence.create_at(sem, 0),
             signal_semaphores=iree.runtime.HalFence.create_at(sem, 1),
         )

runtime/src/iree/hal/buffer_transfer.c

@@ -78,7 +78,7 @@ static iree_status_t iree_hal_device_transfer_and_wait(
     };
     status = iree_hal_device_queue_execute(
         device, IREE_HAL_QUEUE_AFFINITY_ANY, wait_semaphores, signal_semaphores,
-        1, &command_buffer, /*binding_tables=*/NULL);
+        command_buffer, iree_hal_buffer_binding_table_empty());
   }
   if (iree_status_is_ok(status)) {
     status = iree_hal_semaphore_wait(fence_semaphore, signal_value, timeout);

runtime/src/iree/hal/command_buffer.c

@@ -592,7 +592,7 @@ IREE_API_EXPORT iree_status_t iree_hal_command_buffer_dispatch_indirect(
 
 IREE_API_EXPORT iree_status_t iree_hal_command_buffer_validate_submission(
     iree_hal_command_buffer_t* command_buffer,
-    const iree_hal_buffer_binding_table_t* binding_table) {
+    iree_hal_buffer_binding_table_t binding_table) {
   IREE_ASSERT_ARGUMENT(command_buffer);
 
   // Validate the command buffer has been recorded properly.
@@ -607,25 +607,24 @@ IREE_API_EXPORT iree_status_t iree_hal_command_buffer_validate_submission(
   // the command buffer was allocated with.
   if (command_buffer->binding_count == 0) {
     return iree_ok_status();
-  } else if (!binding_table) {
+  } else if (binding_table.count == 0) {
     return iree_make_status(IREE_STATUS_INVALID_ARGUMENT,
                             "indirect command buffer requires at least %u "
                             "bindings but no binding table was provided",
                             command_buffer->binding_count);
-  } else if (binding_table->count < command_buffer->binding_count) {
+  } else if (binding_table.count < command_buffer->binding_count) {
     return iree_make_status(IREE_STATUS_OUT_OF_RANGE,
                             "indirect command buffer requires at least %u "
                             "bindings but only %" PRIhsz " were provided ",
-                            command_buffer->binding_count,
-                            binding_table->count);
+                            command_buffer->binding_count, binding_table.count);
   }
 
   // Validate the binding table against the commands consuming them.
   // This is O(binding_count) so something we only do if validation is
   // requested on the command buffer.
   IF_VALIDATING(command_buffer, {
     IREE_RETURN_IF_ERROR(iree_hal_command_buffer_binding_table_validation(
-        command_buffer, VALIDATION_STATE(command_buffer), *binding_table));
+        command_buffer, VALIDATION_STATE(command_buffer), binding_table));
   });
 
   return iree_ok_status();

runtime/src/iree/hal/command_buffer.h

@@ -792,7 +792,7 @@ IREE_API_EXPORT iree_status_t iree_hal_command_buffer_dispatch_indirect(
 // are used by the command buffer are provided they will be ignored.
 IREE_API_EXPORT iree_status_t iree_hal_command_buffer_validate_submission(
     iree_hal_command_buffer_t* command_buffer,
-    const iree_hal_buffer_binding_table_t* binding_table);
+    iree_hal_buffer_binding_table_t binding_table);
 
 //===----------------------------------------------------------------------===//
 // Utilities for command buffer creation