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 context.h
29 *
30 * @brief 提供了Context相关的接口，可以配置运行时信息。
31 *
32 * @library libmindspore_lite_ndk.so
33 * @since 9
34 */
35#ifndef MINDSPORE_INCLUDE_C_API_CONTEXT_C_H
36#define MINDSPORE_INCLUDE_C_API_CONTEXT_C_H
37
38#include <stddef.h>
39#include <stdint.h>
40#include <stdbool.h>
41#include "mindspore/types.h"
42#include "mindspore/status.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48typedef void *OH_AI_ContextHandle;
49typedef void *OH_AI_DeviceInfoHandle;
50
51/**
52 * @brief Create a context object.
53 * @return Context object handle.
54 * @since 9
55 */
56OH_AI_API OH_AI_ContextHandle OH_AI_ContextCreate();
57
58/**
59 * @brief Destroy the context object.
60 * @param context Context object handle address.
61 * @since 9
62 */
63OH_AI_API void OH_AI_ContextDestroy(OH_AI_ContextHandle *context);
64
65/**
66 * @brief Set the number of threads at runtime.
67 * @param context Context object handle.
68 * @param thread_num the number of threads at runtime.
69 * @since 9
70 */
71OH_AI_API void OH_AI_ContextSetThreadNum(OH_AI_ContextHandle context, int32_t thread_num);
72
73/**
74 * @brief Obtain the current thread number setting.
75 * @param context Context object handle.
76 * @return The current thread number setting.
77 * @since 9
78 */
79OH_AI_API int32_t OH_AI_ContextGetThreadNum(const OH_AI_ContextHandle context);
80
81/**
82 * @brief Set the thread affinity to CPU cores.
83 * @param context Context object handle.
84 * @param mode: 0: no affinities, 1: big cores first, 2: little cores first
85 * @since 9
86 */
87OH_AI_API void OH_AI_ContextSetThreadAffinityMode(OH_AI_ContextHandle context, int mode);
88
89/**
90 * @brief Obtain the thread affinity of CPU cores.
91 * @param context Context object handle.
92 * @return Thread affinity to CPU cores. 0: no affinities, 1: big cores first, 2: little cores first
93 * @since 9
94 */
95OH_AI_API int OH_AI_ContextGetThreadAffinityMode(const OH_AI_ContextHandle context);
96
97/**
98 * @brief Set the thread lists to CPU cores.
99 *
100 * If core_list and mode are set by OH_AI_ContextSetThreadAffinityMode at the same time,
101 * the core_list is effective, but the mode is not effective. \n
102 *
103 * @param context Context object handle.
104 * @param core_list: a array of thread core lists.
105 * @param core_num The number of core.
106 * @since 9
107 */
108OH_AI_API void OH_AI_ContextSetThreadAffinityCoreList(OH_AI_ContextHandle context, const int32_t *core_list,
109                                                      size_t core_num);
110
111/**
112 * @brief Obtain the thread lists of CPU cores.
113 * @param context Context object handle.
114 * @param core_num The number of core.
115 * @return a array of thread core lists.
116 * @since 9
117 */
118OH_AI_API const int32_t *OH_AI_ContextGetThreadAffinityCoreList(const OH_AI_ContextHandle context, size_t *core_num);
119
120/**
121 * @brief Set the status whether to perform model inference or training in parallel.
122 * @param context Context object handle.
123 * @param is_parallel: true, parallel; false, not in parallel.
124 * @since 9
125 */
126OH_AI_API void OH_AI_ContextSetEnableParallel(OH_AI_ContextHandle context, bool is_parallel);
127
128/**
129 * @brief Obtain the status whether to perform model inference or training in parallel.
130 * @param context Context object handle.
131 * @return Bool value that indicates whether in parallel.
132 * @since 9
133 */
134OH_AI_API bool OH_AI_ContextGetEnableParallel(const OH_AI_ContextHandle context);
135
136/**
137 * @brief Add device info to context object.
138 * @param context Context object handle.
139 * @param device_info Device info object handle.
140 * @since 9
141 */
142OH_AI_API void OH_AI_ContextAddDeviceInfo(OH_AI_ContextHandle context, OH_AI_DeviceInfoHandle device_info);
143
144/**
145 * @brief Create a device info object.
146 * @param device_info Device info object handle.
147 * @return Device info object handle.
148 * @since 9
149 */
150OH_AI_API OH_AI_DeviceInfoHandle OH_AI_DeviceInfoCreate(OH_AI_DeviceType device_type);
151
152/**
153 * @brief Destroy the device info object.
154 * @param device_info Device info object handle address.
155 * @since 9
156 */
157OH_AI_API void OH_AI_DeviceInfoDestroy(OH_AI_DeviceInfoHandle *device_info);
158
159/**
160 * @brief Set provider's name.
161 * @param device_info Device info object handle.
162 * @param provider define the provider's name.
163 * @since 9
164 */
165OH_AI_API void OH_AI_DeviceInfoSetProvider(OH_AI_DeviceInfoHandle device_info, const char *provider);
166
167/**
168 * @brief Obtain provider's name
169 * @param device_info Device info object handle.
170 * @return provider's name.
171 * @since 9
172 */
173OH_AI_API const char *OH_AI_DeviceInfoGetProvider(const OH_AI_DeviceInfoHandle device_info);
174
175/**
176 * @brief Set provider's device type.
177 * @param device_info Device info object handle.
178 * @param device define the provider's device type. EG: CPU.
179 * @since 9
180 */
181OH_AI_API void OH_AI_DeviceInfoSetProviderDevice(OH_AI_DeviceInfoHandle device_info, const char *device);
182
183/**
184 * @brief Obtain provider's device type.
185 * @param device_info Device info object handle.
186 * @return provider's device type.
187 * @since 9
188 */
189OH_AI_API const char *OH_AI_DeviceInfoGetProviderDevice(const OH_AI_DeviceInfoHandle device_info);
190
191/**
192 * @brief Obtain the device type of the device info.
193 * @param device_info Device info object handle.
194 * @return Device Type of the device info.
195 * @since 9
196 */
197OH_AI_API OH_AI_DeviceType OH_AI_DeviceInfoGetDeviceType(const OH_AI_DeviceInfoHandle device_info);
198
199/**
200 * @brief Set enables to perform the float16 inference, Only valid for CPU/GPU.
201 * @param device_info Device info object handle.
202 * @param is_fp16 Enable float16 inference or not.
203 * @since 9
204 */
205OH_AI_API void OH_AI_DeviceInfoSetEnableFP16(OH_AI_DeviceInfoHandle device_info, bool is_fp16);
206
207/**
208 * @brief Obtain enables to perform the float16 inference, Only valid for CPU/GPU.
209 * @param device_info Device info object handle.
210 * @return Whether enable float16 inference.
211 * @since 9
212 */
213OH_AI_API bool OH_AI_DeviceInfoGetEnableFP16(const OH_AI_DeviceInfoHandle device_info);
214
215/**
216 * @brief Set the NPU frequency, Only valid for NPU.
217 * @param device_info Device info object handle.
218 * @param frequency Can be set to 1 (low power consumption), 2 (balanced), 3 (high performance), 4 (extreme
219 *        performance), default as 3.
220 * @since 9
221 */
222OH_AI_API void OH_AI_DeviceInfoSetFrequency(OH_AI_DeviceInfoHandle device_info, int frequency);
223
224/**
225 * @brief Obtain the NPU frequency, Only valid for NPU.
226 * @param device_info Device info object handle.
227 * @return NPU frequency
228 * @since 9
229 */
230OH_AI_API int OH_AI_DeviceInfoGetFrequency(const OH_AI_DeviceInfoHandle device_info);
231
232/**
233 * @brief Obtain the all device descriptions in NNRT.
234 * @param num Number of NNRT device description.
235 * @return NNRT device description array.
236 * @since 10
237 */
238OH_AI_API NNRTDeviceDesc *OH_AI_GetAllNNRTDeviceDescs(size_t *num);
239
240/**
241 * @brief Obtain the specified element in NNRt device description array.
242 * @param descs NNRT device description array.
243 * @param index Element index.
244 * @return NNRT device description.
245 * @since 10
246 */
247OH_AI_API NNRTDeviceDesc *OH_AI_GetElementOfNNRTDeviceDescs(NNRTDeviceDesc *descs, size_t index);
248
249/**
250 * @brief Destroy the NNRT device descriptions returned by OH_AI_NNRTGetAllDeviceDescs().
251 * @param desc NNRT device description array.
252 * @since 10
253 */
254OH_AI_API void OH_AI_DestroyAllNNRTDeviceDescs(NNRTDeviceDesc **desc);
255
256/**
257 * @brief Obtain the device id in NNRT device description.
258 * @param desc pointer to the NNRT device description instance.
259 * @return NNRT device id.
260 * @since 10
261 */
262OH_AI_API size_t OH_AI_GetDeviceIdFromNNRTDeviceDesc(const NNRTDeviceDesc *desc);
263
264/**
265 * @brief Obtain the device name in NNRT device description.
266 * @param desc pointer to the NNRT device description instance.
267 * @return NNRT device name.
268 * @since 10
269 */
270OH_AI_API const char *OH_AI_GetNameFromNNRTDeviceDesc(const NNRTDeviceDesc *desc);
271
272/**
273 * @brief Obtain the device type in NNRT device description.
274 * @param desc pointer to the NNRT device description instance.
275 * @return NNRT device type.
276 * @since 10
277 */
278OH_AI_API OH_AI_NNRTDeviceType OH_AI_GetTypeFromNNRTDeviceDesc(const NNRTDeviceDesc *desc);
279
280/**
281 * @brief Create the NNRT device info by exactly matching the specific device name.
282 * @param name NNRt device name.
283 * @return Device info object handle.
284 * @since 10
285 */
286OH_AI_API OH_AI_DeviceInfoHandle OH_AI_CreateNNRTDeviceInfoByName(const char *name);
287
288/**
289 * @brief Create the NNRT device info by finding the first device with the specific device type.
290 * @param name NNRt device type.
291 * @return Device info object handle.
292 * @since 10
293 */
294OH_AI_API OH_AI_DeviceInfoHandle OH_AI_CreateNNRTDeviceInfoByType(OH_AI_NNRTDeviceType type);
295
296/**
297 * @brief Set the NNRT device id, Only valid for NNRT.
298 * @param device_info Device info object handle.
299 * @param device_id NNRT device id.
300 * @since 10
301 */
302OH_AI_API void OH_AI_DeviceInfoSetDeviceId(OH_AI_DeviceInfoHandle device_info, size_t device_id);
303
304/**
305 * @brief Obtain the NNRT device id, Only valid for NNRT.
306 * @param device_info Device info object handle.
307 * @return NNRT device id.
308 * @since 10
309 */
310OH_AI_API size_t OH_AI_DeviceInfoGetDeviceId(const OH_AI_DeviceInfoHandle device_info);
311
312/**
313 * @brief Set the NNRT performance mode, Only valid for NNRT.
314 * @param device_info Device info object handle.
315 * @param device_id NNRT performance mode.
316 * @since 10
317 */
318OH_AI_API void OH_AI_DeviceInfoSetPerformanceMode(OH_AI_DeviceInfoHandle device_info, OH_AI_PerformanceMode mode);
319
320/**
321 * @brief Obtain the NNRT performance mode, Only valid for NNRT.
322 * @param device_info Device info object handle.
323 * @return NNRT performance mode.
324 * @since 10
325 */
326OH_AI_API OH_AI_PerformanceMode OH_AI_DeviceInfoGetPerformanceMode(const OH_AI_DeviceInfoHandle device_info);
327
328/**
329 * @brief Set the NNRT priority, Only valid for NNRT.
330 * @param device_info Device info object handle.
331 * @param device_id NNRT priority.
332 * @since 10
333 */
334OH_AI_API void OH_AI_DeviceInfoSetPriority(OH_AI_DeviceInfoHandle device_info, OH_AI_Priority priority);
335
336/**
337 * @brief Obtain the NNRT priority, Only valid for NNRT.
338 * @param device_info Device info object handle.
339 * @return NNRT priority.
340 * @since 10
341 */
342OH_AI_API OH_AI_Priority OH_AI_DeviceInfoGetPriority(const OH_AI_DeviceInfoHandle device_info);
343
344/**
345 * @brief Add extension of key/value format to device info, Only valid for NNRT.
346 * @param device_info Device info object handle.
347 * @param name The content of key as a C string.
348 * @param value The pointer to the value, which is a byte array.
349 * @param value_size The size of the value, which is a byte array.
350 * @return OH_AI_STATUS_SUCCESS if success, or detail error code if failed.
351 * @since 10
352 */
353OH_AI_API OH_AI_Status OH_AI_DeviceInfoAddExtension(OH_AI_DeviceInfoHandle device_info, const char *name, const char *value, size_t value_size);
354#ifdef __cplusplus
355}
356#endif
357#endif  // MINDSPORE_INCLUDE_C_API_CONTEXT_C_H
358