1/**
2 * Copyright 2021 Huawei Technologies Co., Ltd
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/**
18 * @addtogroup MindSpore
19 * @{
20 *
21 * @brief 提供MindSpore Lite的模型推理相关接口。
22 *
23 * @Syscap SystemCapability.Ai.MindSpore
24 * @since 9
25 */
26
27/**
28 * @file tensor.h
29 * @kit MindSporeLiteKit
30 * @brief 提供了张量相关的接口，可用于创建和修改张量信息。
31 *
32 * @library libmindspore_lite_ndk.so
33 * @since 9
34 */
35#ifndef MINDSPORE_INCLUDE_C_API_TENSOE_C_H
36#define MINDSPORE_INCLUDE_C_API_TENSOE_C_H
37
38#include <stddef.h>
39#include "mindspore/status.h"
40#include "mindspore/types.h"
41#include "mindspore/data_type.h"
42#include "mindspore/format.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48typedef void *OH_AI_TensorHandle;
49
50/**
51 * @brief tensor allocator handle.
52 *
53 * @since 12
54 */
55typedef void *OH_AI_AllocatorHandle;
56
57/**
58 * @brief Create a tensor object.
59 * @param name The name of the tensor.
60 * @param type The data type of the tensor.
61 * @param shape The shape of the tensor.
62 * @param shape_num The num of the shape.
63 * @param data The data pointer that points to allocated memory.
64 * @param data_len The length of the memory, in bytes.
65 * @return Tensor object handle.
66 * @since 9
67 */
68OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,
69                                                size_t shape_num, const void *data, size_t data_len);
70
71/**
72 * @brief Destroy the tensor object.
73 * @param tensor Tensor object handle address.
74 * @since 9
75 */
76OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor);
77
78/**
79 * @brief Obtain a deep copy of the tensor.
80 * @param tensor Tensor object handle.
81 * @return Tensor object handle.
82 * @since 9
83 */
84OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor);
85
86/**
87 * @brief Set the name for the tensor.
88 * @param tensor Tensor object handle.
89 * @param name The name of the tensor.
90 * @since 9
91 */
92OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name);
93
94/**
95 * @brief Obtain the name of the tensor.
96 * @param tensor Tensor object handle.
97 * @return The name of the tensor.
98 * @since 9
99 */
100OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor);
101
102/**
103 * @brief Set the data type for the tensor.
104 * @param tensor Tensor object handle.
105 * @param type The data type of the tensor.
106 * @since 9
107 */
108OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type);
109
110/**
111 * @brief Obtain the data type of the tensor.
112 * @param tensor Tensor object handle.
113 * @return The date type of the tensor.
114 * @since 9
115 */
116OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor);
117
118/**
119 * @brief Set the shape for the tensor.
120 * @param tensor Tensor object handle.
121 * @param shape The shape array.
122 * @param shape_num Dimension of shape.
123 * @since 9
124 */
125OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num);
126
127/**
128 * @brief Obtain the shape of the tensor.
129 * @param tensor Tensor object handle.
130 * @param shape_num Dimension of shape.
131 * @return The shape array of the tensor.
132 * @since 9
133 */
134OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num);
135
136/**
137 * @brief Set the format for the tensor.
138 * @param tensor Tensor object handle.
139 * @param format The format of the tensor.
140 * @since 9
141 */
142OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format);
143
144/**
145 * @brief Obtain the format of the tensor.
146 * @param tensor Tensor object handle.
147 * @return The format of the tensor.
148 * @since 9
149 */
150OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor);
151
152/**
153 * @brief Obtain the data for the tensor.
154 * @param tensor Tensor object handle.
155 * @param data A pointer to the data of the tensor.
156 * @since 9
157 */
158OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data);
159
160/**
161 * @brief Obtain the data pointer of the tensor.
162 * @param tensor Tensor object handle.
163 * @return The data pointer of the tensor.
164 * @since 9
165 */
166OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor);
167
168/**
169 * @brief Obtain the mutable data pointer of the tensor. If the internal data is empty, it will allocate memory.
170 * @param tensor Tensor object handle.
171 * @return The data pointer of the tensor.
172 * @since 9
173 */
174OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor);
175
176/**
177 * @brief Obtain the element number of the tensor.
178 * @param tensor Tensor object handle.
179 * @return The element number of the tensor.
180 * @since 9
181 */
182OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor);
183
184/**
185 * @brief Obtain the data size fo the tensor.
186 * @param tensor Tensor object handle.
187 * @return The data size of the tensor.
188 * @since 9
189 */
190OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor);
191
192/**
193 * @brief Set the data for the tensor with user-allocated data buffer.
194 *
195 * The main purpose of this interface is providing a way of using memory already allocated by user as the Model's
196 * input, but not which allocated inside the Model object. It can reduce one copy. \n
197 * Note: The tensor won't free the data provided by invoker. Invoker has the responsibility to free it. And this
198 * free action should not be preformed before destruction of the tensor. \n
199 *
200 * @param tensor Tensor object handle.
201 * @param data A pointer to the user data buffer.
202 * @param data the byte size of the user data buffer.
203 * @return OH_AI_STATUS_SUCCESS if success, or detail error code if failed.
204 * @since 10
205 */
206OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size);
207
208/**
209 * @brief Get allocator for the tensor.
210 *
211 * The main purpose of this interface is providing a way of getting memory allocator of the tensor.
212 *
213 * @param tensor Tensor object handle.
214 * @return handle of the tensor's allocator.
215 * @since 12
216 */
217OH_AI_API OH_AI_AllocatorHandle OH_AI_TensorGetAllocator(OH_AI_TensorHandle tensor);
218
219/**
220 * @brief Set allocator to the tensor.
221 *
222 * The main purpose of this interface is providing a way of setting memory allocator, so tensor's memory will be
223 * allocated by this allocator.
224 *
225 * @param tensor Tensor object handle.
226 * @param allocator A allocator handle.
227 * @return OH_AI_STATUS_SUCCESS if success, or detail error code if failed.
228 * @since 12
229 */
230OH_AI_API OH_AI_Status OH_AI_TensorSetAllocator(OH_AI_TensorHandle tensor, OH_AI_AllocatorHandle allocator);
231
232#ifdef __cplusplus
233}
234#endif
235#endif  // MINDSPORE_INCLUDE_C_API_TENSOE_C_H
236