Compute Library
 21.08
AclEntrypoints.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2021 Arm Limited.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all
14  * copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24 #ifndef ARM_COMPUTE_ACL_ENTRYPOINTS_H_
25 #define ARM_COMPUTE_ACL_ENTRYPOINTS_H_
26 
27 #include "arm_compute/AclTypes.h"
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif /** __cplusplus */
32 
33 /** Create a context object
34  *
35  * Context is responsible for retaining internal information and work as an aggregate service mechanism
36  *
37  * @param[in, out] ctx A valid non-zero context object if no failure occurs
38  * @param[in] target Target to create the context for
39  * @param[in] options Context options to be used for all the kernels that are created under the context
40  *
41  * @return Status code
42  *
43  * Returns:
44  * - @ref AclSuccess if function was completed successfully
45  * - @ref AclOutOfMemory if there was a failure allocating memory resources
46  * - @ref AclUnsupportedTarget if the requested target is unsupported
47  * - @ref AclInvalidArgument if a given argument is invalid
48  */
50  AclTarget target,
51  const AclContextOptions *options);
52 
53 /** Destroy a given context object
54  *
55  * @param[in] ctx A valid context object to destroy
56  *
57  * @return Status code
58  *
59  * Returns:
60  * - @ref AclSuccess if functions was completed successfully
61  * - @ref AclInvalidArgument if the provided context is invalid
62  */
64 
65 /** Create an operator queue
66  *
67  * Queue is responsible for any scheduling related activities
68  *
69  * @param[in, out] queue A valid non-zero queue object is not failures occur
70  * @param[in] ctx Context to be used
71  * @param[in] options Queue options to be used for the operators using the queue
72  *
73  * @return Status code
74  *
75  * Returns:
76  * - @ref AclSuccess if function was completed successfully
77  * - @ref AclOutOfMemory if there was a failure allocating memory resources
78  * - @ref AclUnsupportedTarget if the requested target is unsupported
79  * - @ref AclInvalidArgument if a given argument is invalid
80  */
81 AclStatus AclCreateQueue(AclQueue *queue, AclContext ctx, const AclQueueOptions *options);
82 
83 /** Wait until all elements on the queue have been completed
84  *
85  * @param[in] queue Queue to wait on completion
86  *
87  * @return Status code
88  *
89  * Returns:
90  * - @ref AclSuccess if functions was completed successfully
91  * - @ref AclInvalidArgument if the provided queue is invalid
92  * - @ref AclRuntimeError on any other runtime related error
93  */
95 
96 /** Destroy a given queue object
97  *
98  * @param[in] queue A valid context object to destroy
99  *
100  * @return Status code
101  *
102  * Returns:
103  * - @ref AclSuccess if functions was completed successfully
104  * - @ref AclInvalidArgument if the provided context is invalid
105  */
107 
108 /** Create a Tensor object
109  *
110  * Tensor is a generalized matrix construct that can represent up to ND dimensionality (where N = 6 for Compute Library)
111  * The object holds a backing memory along-side to operate on
112  *
113  * @param[in, out] tensor A valid non-zero tensor object if no failures occur
114  * @param[in] ctx Context to be used
115  * @param[in] desc Tensor representation meta-data
116  * @param[in] allocate Instructs allocation of the tensor objects
117  *
118  * Returns:
119  * - @ref AclSuccess if function was completed successfully
120  * - @ref AclOutOfMemory if there was a failure allocating memory resources
121  * - @ref AclUnsupportedTarget if the requested target is unsupported
122  * - @ref AclInvalidArgument if a given argument is invalid
123  */
124 AclStatus AclCreateTensor(AclTensor *tensor, AclContext ctx, const AclTensorDescriptor *desc, bool allocate);
125 
126 /** Map a tensor's backing memory to the host
127  *
128  * @param[in] tensor Tensor to be mapped
129  * @param[in, out] handle A handle to the underlying backing memory
130  *
131  * @return Status code
132  *
133  * Returns:
134  * - @ref AclSuccess if function was completed successfully
135  * - @ref AclInvalidArgument if a given argument is invalid
136  */
137 AclStatus AclMapTensor(AclTensor tensor, void **handle);
138 
139 /** Unmap the tensor's backing memory
140  *
141  * @param[in] tensor tensor to unmap memory from
142  * @param[in] handle Backing memory to be unmapped
143  *
144  * @return Status code
145  *
146  * Returns:
147  * - @ref AclSuccess if function was completed successfully
148  * - @ref AclInvalidArgument if a given argument is invalid
149  */
150 AclStatus AclUnmapTensor(AclTensor tensor, void *handle);
151 
152 /** Import external memory to a given tensor object
153  *
154  * @param[in, out] tensor Tensor to import memory to
155  * @param[in] handle Backing memory to be imported
156  * @param[in] type Type of the imported memory
157  *
158  * Returns:
159  * - @ref AclSuccess if function was completed successfully
160  * - @ref AclInvalidArgument if a given argument is invalid
161  */
163 
164 /** Destroy a given tensor object
165  *
166  * @param[in,out] tensor A valid tensor object to be destroyed
167  *
168  * @return Status code
169  *
170  * Returns:
171  * - @ref AclSuccess if function was completed successfully
172  * - @ref AclInvalidArgument if the provided tensor is invalid
173  */
175 
176 /** Creates a tensor pack
177  *
178  * Tensor packs are used to create a collection of tensors that can be passed around for operator execution
179  *
180  * @param[in,out] pack A valid non-zero tensor pack object if no failures occur
181  * @param[in] ctx Context to be used
182  *
183  * @return Status code
184  *
185  * Returns:
186  * - @ref AclSuccess if function was completed successfully
187  * - @ref AclOutOfMemory if there was a failure allocating memory resources
188  * - @ref AclInvalidArgument if a given argument is invalid
189  */
191 
192 /** Add a tensor to a tensor pack
193  *
194  * @param[in,out] pack Pack to append a tensor to
195  * @param[in] tensor Tensor to pack
196  * @param[in] slot_id Slot of the operator that the tensors corresponds to
197  *
198  * @return Status code
199  *
200  * Returns:
201  * - @ref AclSuccess if function was completed successfully
202  * - @ref AclOutOfMemory if there was a failure allocating memory resources
203  * - @ref AclInvalidArgument if a given argument is invalid
204  */
205 AclStatus AclPackTensor(AclTensorPack pack, AclTensor tensor, int32_t slot_id);
206 
207 /** A list of tensors to a tensor pack
208  *
209  * @param[in,out] pack Pack to append the tensors to
210  * @param[in] tensors Tensors to append to the pack
211  * @param[in] slot_ids Slot IDs of each tensors to the operators
212  * @param[in] num_tensors Number of tensors that are passed
213  *
214  * @return Status code
215  *
216  * Returns:
217  * - @ref AclSuccess if function was completed successfully
218  * - @ref AclOutOfMemory if there was a failure allocating memory resources
219  * - @ref AclInvalidArgument if a given argument is invalid
220  */
221 AclStatus AclPackTensors(AclTensorPack pack, AclTensor *tensors, int32_t *slot_ids, size_t num_tensors);
222 
223 /** Destroy a given tensor pack object
224  *
225  * @param[in,out] pack A valid tensor pack object to destroy
226  *
227  * @return Status code
228  *
229  * Returns:
230  * - @ref AclSuccess if functions was completed successfully
231  * - @ref AclInvalidArgument if the provided context is invalid
232  */
234 
235 /** Eager execution of a given operator on a list of inputs and outputs
236  *
237  * @param[in] op Operator to execute
238  * @param[in] queue Queue to schedule the operator on
239  * @param[in,out] tensors A list of input and outputs tensors to execute the operator on
240  *
241  * @return Status Code
242  *
243  * Returns:
244  * - @ref AclSuccess if function was completed successfully
245  * - @ref AclOutOfMemory if there was a failure allocating memory resources
246  * - @ref AclUnsupportedTarget if the requested target is unsupported
247  * - @ref AclInvalidArgument if a given argument is invalid
248  * - @ref AclRuntimeError on any other runtime related error
249  */
251 
252 /** Destroy a given operator object
253  *
254  * @param[in,out] op A valid operator object to destroy
255  *
256  * @return Status code
257  *
258  * Returns:
259  * - @ref AclSuccess if functions was completed successfully
260  * - @ref AclInvalidArgument if the provided context is invalid
261  */
263 #ifdef __cplusplus
264 }
265 #endif /* __cplusplus */
266 #endif /* ARM_COMPUTE_ACL_ENTRYPOINTS_H_ */
AclStatus AclMapTensor(AclTensor tensor, void **handle)
Map a tensor's backing memory to the host.
Definition: AclTensor.cpp:97
AclStatus AclDestroyQueue(AclQueue queue)
Destroy a given queue object.
Definition: AclQueue.cpp:87
AclStatus AclUnmapTensor(AclTensor tensor, void *handle)
Unmap the tensor's backing memory.
Definition: AclTensor.cpp:116
AclStatus AclCreateTensorPack(AclTensorPack *pack, AclContext ctx)
Creates a tensor pack.
AclStatus AclRunOperator(AclOperator op, AclQueue queue, AclTensorPack tensors)
Eager execution of a given operator on a list of inputs and outputs.
Definition: AclOperator.cpp:31
AclTarget
Definition: AclTypes.h:63
AclStatus AclCreateQueue(AclQueue *queue, AclContext ctx, const AclQueueOptions *options)
Create an operator queue.
Definition: AclQueue.cpp:45
AclStatus AclQueueFinish(AclQueue queue)
Wait until all elements on the queue have been completed.
Definition: AclQueue.cpp:72
AclStatus AclDestroyOperator(AclOperator op)
Destroy a given operator object.
Definition: AclOperator.cpp:53
decltype(strategy::transforms) typedef type
AclStatus AclDestroyTensorPack(AclTensorPack pack)
Destroy a given tensor pack object.
AclStatus AclPackTensor(AclTensorPack pack, AclTensor tensor, int32_t slot_id)
Add a tensor to a tensor pack.
AclStatus AclDestroyTensor(AclTensor tensor)
Destroy a given tensor object.
Definition: AclTensor.cpp:144
AclStatus AclCreateTensor(AclTensor *tensor, AclContext ctx, const AclTensorDescriptor *desc, bool allocate)
Create a Tensor object.
Definition: AclTensor.cpp:68
AclImportMemoryType
Type of memory to be imported.
Definition: AclTypes.h:185
AclStatus AclDestroyContext(AclContext ctx)
Destroy a given context object.
Definition: AclContext.cpp:105
AclStatus AclPackTensors(AclTensorPack pack, AclTensor *tensors, int32_t *slot_ids, size_t num_tensors)
A list of tensors to a tensor pack.
AclStatus AclTensorImport(AclTensor tensor, void *handle, AclImportMemoryType type)
Import external memory to a given tensor object.
Definition: AclTensor.cpp:130
AclStatus
Definition: AclTypes.h:49
AclStatus AclCreateContext(AclContext *ctx, AclTarget target, const AclContextOptions *options)
__cplusplus
Definition: AclContext.cpp:78