Add CL command buffer class
* Two implementations of the command buffer are added:
- CLMutableCommandBuffer uses mutable dispatch command buffer
extension.
- CLCompatCommandBuffer is the compatibility class for platform
without the CL extension.
Resolves: COMPMID-6454
Signed-off-by: Viet-Hoa Do <viet-hoa.do@arm.com>
Change-Id: I15b370a50168ca940bd8fb2b5fae26230da3f472
Reviewed-on: https://review.mlplatform.org/c/ml/ComputeLibrary/+/10298
Reviewed-by: Gunes Bayir <gunes.bayir@arm.com>
Comments-Addressed: Arm Jenkins <bsgcomp@arm.com>
Benchmark: Arm Jenkins <bsgcomp@arm.com>
Tested-by: Arm Jenkins <bsgcomp@arm.com>
diff --git a/src/core/CL/CLCommandBuffer.h b/src/core/CL/CLCommandBuffer.h
new file mode 100644
index 0000000..8a94e38
--- /dev/null
+++ b/src/core/CL/CLCommandBuffer.h
@@ -0,0 +1,162 @@
+/*
+ * Copyright (c) 2023 Arm Limited.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#ifndef ACL_SRC_CORE_CL_CLCOMMANDBUFFER_H
+#define ACL_SRC_CORE_CL_CLCOMMANDBUFFER_H
+
+#include "arm_compute/core/CL/OpenCL.h"
+
+#include <cstdint>
+#include <memory>
+#include <type_traits>
+
+namespace arm_compute
+{
+
+/** Command buffer contains a list of commands that is constructed once and later enqueued multiple times.
+ *
+ * To prepare a command buffer:
+ * - Construct a new command buffer targeting a command queue using @ref CLCommandBuffer::create.
+ * - Add kernel enqueue command to the buffer using @ref CLCommandBuffer::add_kernel.
+ * The kernel must be ready to be enqueued with all the arguments set.
+ * - Specify which kernel argument is mutable after the command buffer has been finalized.
+ * - When all the kernel enqueue commands have been added, call @ref CLCommandBuffer::finalize.
+ * After this point the command buffer is ready to be executed.
+ *
+ * To execute the command buffer:
+ * - Make any changes in the value which the mutable arguments are pointing to.
+ * - Call @ref CLCommandBuffer::update to apply the argument value changes.
+ * - Call @ref CLCommandBuffer::enqueue to enqueue the command buffer to execute.
+ */
+class CLCommandBuffer
+{
+public:
+ /** Create a new command buffer targeting the specified command queue.
+ *
+ * @param[in] queue The command queue to execute the command buffer.
+ *
+ * @return A unique pointer to the newly created command buffer.
+ */
+ static std::unique_ptr<CLCommandBuffer> create(cl_command_queue queue);
+
+ /** Constructor. */
+ CLCommandBuffer();
+
+ /** Destructor. */
+ virtual ~CLCommandBuffer();
+
+ /** Disallow copy constructor. */
+ CLCommandBuffer(const CLCommandBuffer &) = delete;
+
+ /** Disallow copy assignment. */
+ CLCommandBuffer &operator=(const CLCommandBuffer &) = delete;
+
+ /** Disallow move constructor. */
+ CLCommandBuffer(CLCommandBuffer &&other) = delete;
+
+ /** Disallow move assignment. */
+ CLCommandBuffer &operator=(CLCommandBuffer &&other) = delete;
+
+ /** Add a kernel enqueue command to the command queue.
+ *
+ * This function must be called before the command buffer has been finalized.
+ *
+ * @param[in] kernel The CL kernel.
+ * @param[in] offset The global work offset.
+ * @param[in] global The global work size.
+ * @param[in] local The local work size.
+ */
+ virtual void add_kernel(cl_kernel kernel, const cl::NDRange &offset, const cl::NDRange &global, const cl::NDRange &local) = 0;
+
+ /** Add the mutable argument to the current kernel enqueue command.
+ *
+ * This function must be called after @ref CLCommandBuffer::add_kernel but before the command buffer
+ * has been finalized.
+ *
+ * The pointer must be valid and it must point to the correct value at the time
+ * @ref CLCommandBuffer::update is called so that the value of the argument
+ * can be applied successfully to the kernel enqueue command.
+ *
+ * @param[in] arg_idx The index of the argument in the current kernel program.
+ * @param[in] value The pointer to the value of the argument.
+ */
+ template <typename T, typename = std::enable_if_t<std::is_arithmetic<T>::value || std::is_pointer<T>::value>>
+ void add_mutable_argument(cl_uint arg_idx, const T *value)
+ {
+ add_mutable_argument_generic(arg_idx, value, sizeof(T));
+ }
+
+ /** Finalize the command buffer. */
+ virtual void finalize() = 0;
+
+ /** Update the command buffer with new kernel argument values.
+ *
+ * This function must be called after the command buffer has been finalized.
+ *
+ * All the value pointed by the mutable argument will be applied to the command buffer.
+ */
+ virtual void update() = 0;
+
+ /** Enqueue the command buffer.
+ *
+ * This function must be called after the command buffer has been finalized.
+ */
+ virtual void enqueue() = 0;
+
+ /** Check if the command buffer has been finalized.
+ *
+ * @return true if the command buffer has been finalized.
+ */
+ virtual bool is_finalized() const = 0;
+
+protected:
+ /** Add the mutable argument to the current kernel enqueue command.
+ *
+ * @see CLCommandBuffer::add_mutable_argument for more information.
+ */
+ virtual void add_mutable_argument_generic(cl_uint arg_idx, const void *value, size_t size) = 0;
+
+ /** The state of the command buffer. */
+ enum class State : int32_t
+ {
+ /** The command buffer has been created and is being specified. */
+ Created,
+
+ /** The command buffer has been finalized and is ready to be executed. */
+ Finalized,
+ };
+
+ /** Get the state of the command buffer. */
+ State state() const;
+
+ /** Set the state of the command buffer. */
+ CLCommandBuffer &state(State state);
+
+private:
+ State _state{ State::Created };
+};
+
+} // namespace arm_compute
+
+#endif // ACL_SRC_CORE_CL_CLCOMMANDBUFFER_H