1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
/*
* 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
|
