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 *
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 Create a tensor object.
52 * @param name The name of the tensor.
53 * @param type The data type of the tensor.
54 * @param shape The shape of the tensor.
55 * @param shape_num The num of the shape.
56 * @param data The data pointer that points to allocated memory.
57 * @param data_len The length of the memory, in bytes.
58 * @return Tensor object handle.
59 * @since 9
60 */
61OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,
62                                                size_t shape_num, const void *data, size_t data_len);
63
64/**
65 * @brief Destroy the tensor object.
66 * @param tensor Tensor object handle address.
67 * @since 9
68 */
69OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor);
70
71/**
72 * @brief Obtain a deep copy of the tensor.
73 * @param tensor Tensor object handle.
74 * @return Tensor object handle.
75 * @since 9
76 */
77OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor);
78
79/**
80 * @brief Set the name for the tensor.
81 * @param tensor Tensor object handle.
82 * @param name The name of the tensor.
83 * @since 9
84 */
85OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name);
86
87/**
88 * @brief Obtain the name of the tensor.
89 * @param tensor Tensor object handle.
90 * @return The name of the tensor.
91 * @since 9
92 */
93OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor);
94
95/**
96 * @brief Set the data type for the tensor.
97 * @param tensor Tensor object handle.
98 * @param type The data type of the tensor.
99 * @since 9
100 */
101OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type);
102
103/**
104 * @brief Obtain the data type of the tensor.
105 * @param tensor Tensor object handle.
106 * @return The date type of the tensor.
107 * @since 9
108 */
109OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor);
110
111/**
112 * @brief Set the shape for the tensor.
113 * @param tensor Tensor object handle.
114 * @param shape The shape array.
115 * @param shape_num Dimension of shape.
116 * @since 9
117 */
118OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num);
119
120/**
121 * @brief Obtain the shape of the tensor.
122 * @param tensor Tensor object handle.
123 * @param shape_num Dimension of shape.
124 * @return The shape array of the tensor.
125 * @since 9
126 */
127OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num);
128
129/**
130 * @brief Set the format for the tensor.
131 * @param tensor Tensor object handle.
132 * @param format The format of the tensor.
133 * @since 9
134 */
135OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format);
136
137/**
138 * @brief Obtain the format of the tensor.
139 * @param tensor Tensor object handle.
140 * @return The format of the tensor.
141 * @since 9
142 */
143OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor);
144
145/**
146 * @brief Obtain the data for the tensor.
147 * @param tensor Tensor object handle.
148 * @param data A pointer to the data of the tensor.
149 * @since 9
150 */
151OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data);
152
153/**
154 * @brief Obtain the data pointer of the tensor.
155 * @param tensor Tensor object handle.
156 * @return The data pointer of the tensor.
157 * @since 9
158 */
159OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor);
160
161/**
162 * @brief Obtain the mutable data pointer of the tensor. If the internal data is empty, it will allocate memory.
163 * @param tensor Tensor object handle.
164 * @return The data pointer of the tensor.
165 * @since 9
166 */
167OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor);
168
169/**
170 * @brief Obtain the element number of the tensor.
171 * @param tensor Tensor object handle.
172 * @return The element number of the tensor.
173 * @since 9
174 */
175OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor);
176
177/**
178 * @brief Obtain the data size fo the tensor.
179 * @param tensor Tensor object handle.
180 * @return The data size of the tensor.
181 * @since 9
182 */
183OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor);
184
185/**
186 * @brief Set the data for the tensor with user-allocated data buffer.
187 *
188 * The main purpose of this interface is providing a way of using memory already allocated by user as the Model's
189 * input, but not which allocated inside the Model object. It can reduce one copy. \n
190 * Note: The tensor won't free the data provided by invoker. Invoker has the responsibility to free it. And this
191 * free action should not be preformed before destruction of the tensor. \n
192 *
193 * @param tensor Tensor object handle.
194 * @param data A pointer to the user data buffer.
195 * @param data the byte size of the user data buffer.
196 * @return OH_AI_STATUS_SUCCESS if success, or detail error code if failed.
197 * @since 10
198 */
199OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size);
200
201#ifdef __cplusplus
202}
203#endif
204#endif  // MINDSPORE_INCLUDE_C_API_TENSOE_C_H
205