diff --git a/ai/neural_network_runtime/BUILD.gn b/ai/neural_network_runtime/BUILD.gn index 856097adcf97de1304cc37f8b1fdf2fa03d4382e..1f9060cf58cfc118500e69b09206dc310c4927b5 100644 --- a/ai/neural_network_runtime/BUILD.gn +++ b/ai/neural_network_runtime/BUILD.gn @@ -1,4 +1,4 @@ -# Copyright (c) 2022 Huawei Device Co., Ltd. +# Copyright (c) 2022-2023 Huawei Device Co., Ltd. # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at @@ -13,6 +13,18 @@ import("//build/ohos.gni") +ohos_ndk_library("libneural_network_core_ndk") { + output_name = "neural_network_core" + output_extension = "so" + ndk_description_file = "libneural_network_core.ndk.json" + min_compact_version = "11" + system_capability = "SystemCapability.AI.NeuralNetworkRuntime" + system_capability_headers = [ + "neural_network_core.h", + "neural_network_runtime_type.h", + ] +} + ohos_ndk_library("libneural_network_runtime_ndk") { output_name = "neural_network_runtime" output_extension = "so" @@ -21,6 +33,7 @@ ohos_ndk_library("libneural_network_runtime_ndk") { system_capability = "SystemCapability.AI.NeuralNetworkRuntime" system_capability_headers = [ "neural_network_runtime.h", + "neural_network_runtime_compat.h", "neural_network_runtime_type.h", ] } @@ -28,7 +41,9 @@ ohos_ndk_library("libneural_network_runtime_ndk") { ohos_ndk_headers("libneural_network_runtime_header") { dest_dir = "$ndk_headers_out_dir/neural_network_runtime" sources = [ + "neural_network_core.h", "neural_network_runtime.h", + "neural_network_runtime_compat.h", "neural_network_runtime_type.h", ] } diff --git a/ai/neural_network_runtime/libneural_network_core.ndk.json b/ai/neural_network_runtime/libneural_network_core.ndk.json new file mode 100644 index 0000000000000000000000000000000000000000..85be3aee3098a5dd9b7e36285803780189f196e5 --- /dev/null +++ b/ai/neural_network_runtime/libneural_network_core.ndk.json @@ -0,0 +1,152 @@ +[ + { + "name": "OH_NNCompilation_Construct" + }, + { + "name": "OH_NNCompilation_ConstructWithOfflineModelFile" + }, + { + "name": "OH_NNCompilation_ConstructWithOfflineModelBuffer" + }, + { + "name": "OH_NNCompilation_ConstructForCache" + }, + { + "name": "OH_NNCompilation_ExportCacheToBuffer" + }, + { + "name": "OH_NNCompilation_ImportCacheFromBuffer" + }, + { + "name": "OH_NNCompilation_AddExtensionConfig" + }, + { + "name": "OH_NNCompilation_SetDevice" + }, + { + "name": "OH_NNCompilation_SetCache" + }, + { + "name": "OH_NNCompilation_SetPerformanceMode" + }, + { + "name": "OH_NNCompilation_SetPriority" + }, + { + "name": "OH_NNCompilation_EnableFloat16" + }, + { + "name": "OH_NNCompilation_Build" + }, + { + "name": "OH_NNCompilation_Destroy" + }, + { + "name": "OH_NNTensorDesc_Create" + }, + { + "name": "OH_NNTensorDesc_Destroy" + }, + { + "name": "OH_NNTensorDesc_SetName" + }, + { + "name": "OH_NNTensorDesc_GetName" + }, + { + "name": "OH_NNTensorDesc_SetDataType" + }, + { + "name": "OH_NNTensorDesc_GetDataType" + }, + { + "name": "OH_NNTensorDesc_SetShape" + }, + { + "name": "OH_NNTensorDesc_GetShape" + }, + { + "name": "OH_NNTensorDesc_SetFormat" + }, + { + "name": "OH_NNTensorDesc_GetFormat" + }, + { + "name": "OH_NNTensorDesc_GetElementCount" + }, + { + "name": "OH_NNTensorDesc_GetByteSize" + }, + { + "name": "OH_NNTensor_Create" + }, + { + "name": "OH_NNTensor_CreateWithSize" + }, + { + "name": "OH_NNTensor_CreateWithFd" + }, + { + "name": "OH_NNTensor_Destroy" + }, + { + "name": "OH_NNTensor_GetTensorDesc" + }, + { + "name": "OH_NNTensor_GetDataBuffer" + }, + { + "name": "OH_NNTensor_GetSize" + }, + { + "name": "OH_NNTensor_GetFd" + }, + { + "name": "OH_NNTensor_GetOffset" + }, + { + "name": "OH_NNExecutor_Construct" + }, + { + "name": "OH_NNExecutor_GetOutputShape" + }, + { + "name": "OH_NNExecutor_Destroy" + }, + { + "name": "OH_NNExecutor_GetInputCount" + }, + { + "name": "OH_NNExecutor_GetOutputCount" + }, + { + "name": "OH_NNExecutor_CreateInputTensorDesc" + }, + { + "name": "OH_NNExecutor_CreateOutputTensorDesc" + }, + { + "name": "OH_NNExecutor_GetInputDimRange" + }, + { + "name": "OH_NNExecutor_SetOnRunDone" + }, + { + "name": "OH_NNExecutor_SetOnServiceDied" + }, + { + "name": "OH_NNExecutor_RunSync" + }, + { + "name": "OH_NNExecutor_RunAsync" + }, + { + "name": "OH_NNDevice_GetAllDevicesID" + }, + { + "name": "OH_NNDevice_GetName" + }, + { + "name": "OH_NNDevice_GetType" + } +] \ No newline at end of file diff --git a/ai/neural_network_runtime/libneural_network_runtime.ndk.json b/ai/neural_network_runtime/libneural_network_runtime.ndk.json index 0d58444cb13d1d058014fcf82380c03675ff81da..cdbf858a500b4b77d07f3259ed5b68ed0c52be07 100644 --- a/ai/neural_network_runtime/libneural_network_runtime.ndk.json +++ b/ai/neural_network_runtime/libneural_network_runtime.ndk.json @@ -1,54 +1,51 @@ [ { - "name": "OH_NNModel_Construct" + "name": "OH_NNQuantParam_Create" }, { - "name": "OH_NNModel_AddTensor" + "name": "OH_NNQuantParam_SetScales" }, { - "name": "OH_NNModel_SetTensorData" + "name": "OH_NNQuantParam_SetZeroPoints" }, { - "name": "OH_NNModel_AddOperation" - }, - { - "name": "OH_NNModel_SpecifyInputsAndOutputs" + "name": "OH_NNQuantParam_SetNumBits" }, { - "name": "OH_NNModel_Finish" + "name": "OH_NNQuantParam_Destroy" }, { - "name": "OH_NNModel_Destroy" + "name": "OH_NNModel_Construct" }, { - "name": "OH_NNModel_GetAvailableOperations" + "name": "OH_NNModel_AddTensor" }, { - "name": "OH_NNCompilation_Construct" + "name": "OH_NNModel_AddTensorToModel" }, { - "name": "OH_NNCompilation_SetDevice" + "name": "OH_NNModel_SetTensorData" }, { - "name": "OH_NNCompilation_SetCache" + "name": "OH_NNModel_SetTensorQuantParams" }, { - "name": "OH_NNCompilation_SetPerformanceMode" + "name": "OH_NNModel_SetTensorType" }, { - "name": "OH_NNCompilation_SetPriority" + "name": "OH_NNModel_AddOperation" }, { - "name": "OH_NNCompilation_EnableFloat16" + "name": "OH_NNModel_SpecifyInputsAndOutputs" }, { - "name": "OH_NNCompilation_Build" + "name": "OH_NNModel_Finish" }, { - "name": "OH_NNCompilation_Destroy" + "name": "OH_NNModel_Destroy" }, { - "name": "OH_NNExecutor_Construct" + "name": "OH_NNModel_GetAvailableOperations" }, { "name": "OH_NNExecutor_SetInput" @@ -56,9 +53,6 @@ { "name": "OH_NNExecutor_SetOutput" }, - { - "name": "OH_NNExecutor_GetOutputShape" - }, { "name": "OH_NNExecutor_Run" }, @@ -79,17 +73,5 @@ }, { "name": "OH_NNExecutor_SetOutputWithMemory" - }, - { - "name": "OH_NNExecutor_Destroy" - }, - { - "name": "OH_NNDevice_GetAllDevicesID" - }, - { - "name": "OH_NNDevice_GetName" - }, - { - "name": "OH_NNDevice_GetType" } ] \ No newline at end of file diff --git a/ai/neural_network_runtime/neural_network_core.h b/ai/neural_network_runtime/neural_network_core.h new file mode 100644 index 0000000000000000000000000000000000000000..6ab1c86accaa303be0c1a3f49cdb72bf220eccdd --- /dev/null +++ b/ai/neural_network_runtime/neural_network_core.h @@ -0,0 +1,1041 @@ +/* + * Copyright (c) 2022-2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup NeuralNeworkRuntime + * @{ + * + * @brief Provides APIs of Neural Network Runtime for accelerating the model inference. + * + * @since 9 + * @version 2.0 + */ + +/** + * @file neural_network_core.h + * + * @brief Defines the Neural Network Core APIs. The AI inference framework uses the Native APIs provided by Neural Network Core + * to compile models and perform inference and computing on acceleration hardware. + * + * Note: Currently, the APIs of Neural Network Core do not support multi-thread calling. \n + * + * include "neural_network_runtime/neural_network_core.h" + * @library libneural_network_core.so + * @Syscap SystemCapability.Ai.NeuralNetworkRuntime + * @since 11 + * @version 1.0 + */ + +#ifndef NEURAL_NETWORK_CORE_H +#define NEURAL_NETWORK_CORE_H + +#include "neural_network_runtime_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Creates a compilation instance of the {@link OH_NNCompilation} type. + * + * After the OH_NNModel module completes model construction, APIs provided by the OH_NNCompilation module pass the model + * to underlying device for compilation. This method creates a {@link OH_NNCompilation} instance + * based on the passed {@link OH_NNModel} instance. The {@link OH_NNCompilation_SetDevice} method is called + * to set the device to compile on, and {@link OH_NNCompilation_Build} is then called to complete compilation. \n + * + * In addition to computing device selection, the OH_NNCompilation module supports features such as model caching, performance preference, + * priority setting, and float16 computing, which can be implemented by the following methods: + * - {@link OH_NNCompilation_SetCache} + * - {@link OH_NNCompilation_SetPerformanceMode} + * - {@link OH_NNCompilation_SetPriority} + * - {@link OH_NNCompilation_EnableFloat16} \n + * + * After {@link OH_NNCompilation_Build} is called, the {@link OH_NNModel} instance can be released. \n + * + * @param model Pointer to the {@link OH_NNModel} instance. + * @return Pointer to a {@link OH_NNCompilation} instance, or NULL if it fails to create. + * @since 9 + * @version 1.0 + */ +OH_NNCompilation *OH_NNCompilation_Construct(const OH_NNModel *model); + +/** + * @brief Creates a compilation instance based on an offline model file. + * + * This method conflicts with the way of passing an online built model or an offline model file buffer, + * and you have to choose only one of the three construction methods. \n + * + * Offline model is a type of model that is offline compiled by the model converter provided by a device vendor. + * So that the offline model can only be used on the specified device, but the compilation time of offline model is usually + * much less than {@link OH_NNModel}. \n + * + * You should perform the offline compilation during your development and deploy the offline model in your app package. \n + * + * @param modelPath Offline model file path. + * @return Pointer to an {@link OH_NNCompilation} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +OH_NNCompilation *OH_NNCompilation_ConstructWithOfflineModelFile(const char *modelPath); + +/** + * @brief Creates a compilation instance based on an offline model file buffer. + * + * This method conflicts with the way of passing an online built model or an offline model file path, + * and you have to choose only one of the three construction methods. \n + * + * Note that the returned {@link OH_NNCompilation} instance only saves the modelBuffer pointer inside, instead of + * copying its data. You should not release modelBuffer before the {@link OH_NNCompilation} instance is destroied. \n + * + * @param modelBuffer Offline model file buffer. + * @param modelSize Offfline model buffer size. + * @return Pointer to an {@link OH_NNCompilation} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +OH_NNCompilation *OH_NNCompilation_ConstructWithOfflineModelBuffer(const void *modelBuffer, size_t modelSize); + +/** + * @brief Creates a empty compilation instance for restoration from cache later. + * + * The restoration time from the cache is less than compilation with {@link OH_NNModel}. \n + * + * You should call {@link OH_NNCompilation_SetCache} or {@link OH_NNCompilation_ImportCacheFromBuffer} first, + * and then call {@link OH_NNCompilation_Build} to complete the restoration. \n + * + * @return Pointer to an {@link OH_NNCompilation} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +OH_NNCompilation *OH_NNCompilation_ConstructForCache(); + +/** + * @brief Exports the cache to a given buffer. + * + * The cache is the result of compilation building {@link OH_NNCompilation_Build}, + * so that this method must be called after {@link OH_NNCompilation_Build}. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param buffer Pointer to the given buffer. + * @param length Buffer length. + * @param modelSize Byte size of the model cache. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_ExportCacheToBuffer(OH_NNCompilation *compilation, + const void *buffer, + size_t length, + size_t *modelSize); + +/** + * @brief Imports the cache from a given buffer. + * + * {@link OH_NNCompilation_Build} should be called to complete the restoration after {@link OH_NNCompilation_ImportCacheFromBuffer} is called. \n + * + * Note that compilation only saves the buffer pointer inside, instead of copying its data. You should not + * release buffer before compilation is destroied. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param buffer Pointer to the given buffer. + * @param modelSize Byte size of the model cache. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_ImportCacheFromBuffer(OH_NNCompilation *compilation, + const void *buffer, + size_t modelSize); + +/** + * @brief Adds an extension config for a custom hardware attribute. + * + * Some devices have their own specific attributes which have not been opened in NNRt. This method provides an additional way for you + * to set these custom hardware attributes of the device. You should query their names and values from the device + * vendor's documents, and add them into compilation instance one by one. These attributes will be passed directly to device + * driver, and this method will return error code if the driver cannot parse them. \n + * + * After {@link OH_NNCompilation_Build} is called, the configName and configValue can be released. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param configName Config name. + * @param configValue A byte buffer saving the config value. + * @param configValueSize Byte size of the config value. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_AddExtensionConfig(OH_NNCompilation *compilation, + const char *configName, + const void *configValue, + const size_t configValueSize); + +/** + * @brief Specifies the device for model compilation and computing. + * + * In the compilation phase, you need to specify the device for model compilation and computing. Call {@link OH_NNDevice_GetAllDevicesID} + * to obtain available device IDs. Call {@link OH_NNDevice_GetType} and {@link OH_NNDevice_GetName} to obtain device information + * and pass target device ID to this method for setting. \n + * + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param deviceID Device id. If it is 0, the first device in the current device list will be used by default. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_SetDevice(OH_NNCompilation *compilation, size_t deviceID); + +/** + * @brief Set the cache directory and version of the compiled model. + * + * On the device that supports caching, a model can be saved as a cache file after being compiled on the device driver. + * The model can be directly read from the cache file in the next compilation, saving recompilation time. + * This method performs different operations based on the passed cache directory and version: \n + * + * - No file exists in the cache directory: + * Caches the compiled model to the directory and sets the cache version to version. \n + * + * - A complete cache file exists in the cache directory, and its version is version: + * Reads the cache file in the path and passes the data to the underlying device for conversion into executable model instances. \n + * + * - A complete cache file exists in the cache directory, and its version is earlier than version: + * When model compilation is complete on the underlying device, overwrites the cache file and changes the version number to version. \n + * + * - A complete cache file exists in the cache directory, and its version is later than version: + * Returns the {@link OH_NN_INVALID_PARAMETER} error code without reading the cache file. \n + * + * - The cache file in the cache directory is incomplete or you do not have the permission to access the cache file. + * Returns the {@link OH_NN_INVALID_FILE} error code. \n + * + * - The cache directory does not exist or you do not have the access permission. + * Returns the {@link OH_NN_INVALID_PATH} error code. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param cachePath Directory for storing model cache files. This method creates directories for different devices in the cachePath directory. + * You are advised to use a separate cache directory for each model. + * @param version Cache version. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_SetCache(OH_NNCompilation *compilation, const char *cachePath, uint32_t version); + +/** + * @brief Sets the performance mode for model computing. + * + * Allows you to set the performance mode for model computing to meet the requirements of low power consumption + * and ultimate performance. If this method is not called to set the performance mode in the compilation phase, the compilation instance assigns + * the {@link OH_NN_PERFORMANCE_NONE} mode for the model by default. In this case, the device performs computing in the default performance mode. \n + * + * If this method is called on the device that does not support the setting of the performance mode, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param performanceMode Performance mode. For details about the available performance modes, see {@link OH_NN_PerformanceMode}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_SetPerformanceMode(OH_NNCompilation *compilation, + OH_NN_PerformanceMode performanceMode); + +/** + * @brief Sets the model computing priority. + * + * Allows you to set computing priorities for models. + * The priorities apply only to models created by the process with the same UID. + * The settings will not affect models created by processes with different UIDs on different devices. \n + * + * If this method is called on the device that does not support the priority setting, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param priority Priority. For details about the optional priorities, see {@link OH_NN_Priority}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_SetPriority(OH_NNCompilation *compilation, OH_NN_Priority priority); + +/** + * @brief Enables float16 for computing. + * + * Float32 is used by default for the model of float type. If this method is called on a device that supports float16, + * float16 will be used for computing the float32 model to reduce memory usage and execution time. \n + * + * This option is useless for the model of int type, e.g. int8 type. \n + * + * If this method is called on the device that does not support float16, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @param enableFloat16 Indicates whether to enable float16. If this parameter is set to true, float16 inference is performed. + * If this parameter is set to false, float32 inference is performed. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, an error code is returned. + * For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_EnableFloat16(OH_NNCompilation *compilation, bool enableFloat16); + +/** + * @brief Compiles a model. + * + * After the compilation configuration is complete, call this method to return the compilation result. The compilation instance pushes the model and + * compilation options to the device for compilation. After this method is called, additional compilation operations cannot be performed. \n + * + * If the {@link OH_NNCompilation_SetDevice}, {@link OH_NNCompilation_SetCache}, {@link OH_NNCompilation_SetPerformanceMode}, + * {@link OH_NNCompilation_SetPriority}, and {@link OH_NNCompilation_EnableFloat16} methods are called, {@link OH_NN_OPERATION_FORBIDDEN} is returned. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNCompilation_Build(OH_NNCompilation *compilation); + +/** + * @brief Releases the Compilation object. + * + * This method needs to be called to release the compilation instance created by {@link OH_NNCompilation_Construct}, + * {@link OH_NNCompilation_ConstructWithOfflineModelFile}, {@link OH_NNCompilation_ConstructWithOfflineModelBuffer} and + * {@link OH_NNCompilation_ConstructForCache}. Otherwise, the memory leak will occur. \n + * + * If compilation or *compilation is a null pointer, this method only prints warning logs and does not execute the release. \n + * + * @param compilation Double pointer to the {@link OH_NNCompilation} instance. After a compilation instance is destroyed, + * this method sets *compilation to a null pointer. + * @since 9 + * @version 1.0 + */ +void OH_NNCompilation_Destroy(OH_NNCompilation **compilation); + + +/** + * @brief Creates an {@link NN_TensorDesc} instance. + * + * The {@link NN_TensorDesc} describes various tensor attributes, such as name/data type/shape/format, etc. \n + * + * The following methods can be called to create a {@link NN_Tensor} instance based on the passed {@link NN_TensorDesc} instance: + * - {@link OH_NNTensor_Create} + * - {@link OH_NNTensor_CreateWithSize} + * - {@link OH_NNTensor_CreateWithFd} \n + * Note that these methods will copy the {@link NN_TensorDesc} instance into {@link NN_Tensor}. Therefore you can create multiple + * {@link NN_Tensor} instances with the same {@link NN_TensorDesc} instance. And you should destroy the {@link NN_TensorDesc} instance + * by {@link OH_NNTensorDesc_Destroy} when it is no longer used. \n + * + * @return Pointer to a {@link NN_TensorDesc} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_TensorDesc *OH_NNTensorDesc_Create(); + +/** + * @brief Releases an {@link NN_TensorDesc} instance. + * + * When the {@link NN_TensorDesc} instance is no longer used, this method needs to be called to release it. Otherwise, + * the memory leak will occur. \n + * + * If tensorDesc or *tensorDesc is a null pointer, this method will return error code and does not execute the release. \n + * + * @param tensorDesc Double pointer to the {@link NN_TensorDesc} instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_Destroy(NN_TensorDesc **tensorDesc); + +/** + * @brief Sets the name of a {@link NN_TensorDesc}. + * + * After the {@link NN_TensorDesc} instance is created, call this method to set the tensor name. + * The value of (*name) is a C-style string ended with '\0'. \n + * + * if tensorDesc or name is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param name The name of the tensor that needs to be set. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_SetName(NN_TensorDesc *tensorDesc, const char *name); + +/** + * @brief Gets the name of a {@link NN_TensorDesc}. + * + * Call this method to obtain the name of the specified {@link NN_TensorDesc} instance. + * The value of (*name) is a C-style string ended with '\0'. \n + * + * if tensorDesc or name is a null pointer, this method will return error code. + * As an output parameter, *name must be a null pointer, otherwise the method will return an error code. + * Fou example, you should define char* tensorName = NULL, and pass &tensorName as the argument of name. \n + * + * You do not need to release the memory of name. It will be released when tensorDesc is destroied. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param name The retured name of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetName(const NN_TensorDesc *tensorDesc, const char **name); + +/** + * @brief Sets the data type of a {@link NN_TensorDesc}. + * + * After the {@link NN_TensorDesc} instance is created, call this method to set the tensor data type. \n + * + * if tensorDesc is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param dataType The data type of the tensor that needs to be set. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_SetDataType(NN_TensorDesc *tensorDesc, OH_NN_DataType dataType); + +/** + * @brief Gets the data type of a {@link NN_TensorDesc}. + * + * Call this method to obtain the data type of the specified {@link NN_TensorDesc} instance. \n + * + * if tensorDesc or dataType is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param dataType The returned data type of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetDataType(const NN_TensorDesc *tensorDesc, OH_NN_DataType *dataType); + +/** + * @brief Sets the shape of a {@link NN_TensorDesc}. + * + * After the {@link NN_TensorDesc} instance is created, call this method to set the tensor shape. \n + * + * if tensorDesc or shape is a null pointer, or shapeLength is 0, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param shape The shape list of the tensor that needs to be set. + * @param shapeLength The length of the shape list that needs to be set. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_SetShape(NN_TensorDesc *tensorDesc, const int32_t *shape, size_t shapeLength); + +/** + * @brief Gets the shape of a {@link NN_TensorDesc}. + * + * Call this method to obtain the shape of the specified {@link NN_TensorDesc} instance. \n + * + * if tensorDesc, shape or shapeLength is a null pointer, this method will return error code. + * As an output parameter, *shape must be a null pointer, otherwise the method will return an error code. + * Fou example, you should define int32_t* tensorShape = NULL, and pass &tensorShape as the argument of shape. \n + * + * You do not need to release the memory of shape. It will be released when tensorDesc is destroied. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param shape Return the shape list of the tensor. + * @param shapeLength The returned length of the shape list. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetShape(const NN_TensorDesc *tensorDesc, int32_t **shape, size_t *shapeLength); + +/** + * @brief Sets the format of a {@link NN_TensorDesc}. + * + * After the {@link NN_TensorDesc} instance is created, call this method to set the tensor format. \n + * + * if tensorDesc is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param format The format of the tensor that needs to be set. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_SetFormat(NN_TensorDesc *tensorDesc, OH_NN_Format format); + +/** + * @brief Gets the format of a {@link NN_TensorDesc}. + * + * Call this method to obtain the format of the specified {@link NN_TensorDesc} instance. \n + * + * if tensorDesc or format is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param format The returned format of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetFormat(const NN_TensorDesc *tensorDesc, OH_NN_Format *format); + +/** + * @brief Gets the element count of a {@link NN_TensorDesc}. + * + * Call this method to obtain the element count of the specified {@link NN_TensorDesc} instance. + * If you need to obtain byte size of the tensor data, call {@link OH_NNTensorDesc_GetByteSize}. \n + * + * If the tensor shape is dynamic, this method will return error code, and elementCount will be 0. \n + * + * if tensorDesc or elementCount is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param elementCount The returned element count of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetElementCount(const NN_TensorDesc *tensorDesc, size_t *elementCount); + +/** + * @brief Gets the byte size of a {@link NN_TensorDesc}. + * + * Call this method to obtain the byte size of the specified {@link NN_TensorDesc} instance. \n + * + * If the tensor shape is dynamic, this method will return error code, and byteSize will be 0. \n + * + * If you need to obtain element count of the tensor data, call {@link OH_NNTensorDesc_GetElementCount}. \n + * + * if tensorDesc or byteSize is a null pointer, this method will return error code. \n + * + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param byteSize The returned byte size of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensorDesc_GetByteSize(const NN_TensorDesc *tensorDesc, size_t *byteSize); + +/** + * @brief Creates a {@link NN_Tensor} instance from {@link NN_TensorDesc}. + * + * This method use {@link OH_NNTensorDesc_GetByteSize} to calculate the byte size of tensor data and allocate device memory for it. + * The device dirver will get the tensor data directly by the "zero-copy" way. \n + * + * Note that this method will copy the tensorDesc into {@link NN_Tensor}. Therefore you should destroy tensorDesc + * by {@link OH_NNTensorDesc_Destroy} when it is no longer used. \n + * + * If the tensor shape is dynamic, this method will return error code. \n + * + * deviceID indicates the selected device. If it is 0, the first device in the current device list will be used by default. \n + * + * tensorDesc must be provided, and this method will return an error code if it is a null pointer. \n + * + * Call {@link OH_NNTensor_DestroyTensor} to release the {@link NN_Tensor} instance. \n + * + * @param deviceID Device id. If it is 0, the first device in the current device list will be used by default. + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @return Pointer to a {@link NN_Tensor} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_Tensor* OH_NNTensor_Create(size_t deviceID, NN_TensorDesc *tensorDesc); + +/** + * @brief Creates a {@link NN_Tensor} instance with specified size. + * + * This method use size as the byte size of tensor data and allocate device memory for it. + * The device dirver will get the tensor data directly by the "zero-copy" way. \n + * + * Note that this method will copy the tensorDesc into {@link NN_Tensor}. Therefore you should destroy tensorDesc + * by {@link OH_NNTensorDesc_Destroy} when it is no longer used. \n + * + * deviceID indicates the selected device. If it is 0, the first device in the current device list will be used by default. \n + * + * tensorDesc must be provided, if it is a null pointer, the method returns an error code. + * size must be no less than the byte size of tensorDesc. Otherwise, this method will return an error code. If the tensor + * shape is dynamic, the size will not be checked. \n + * + * Call {@link OH_NNTensor_DestroyTensor} to release the {@link NN_Tensor} instance. \n + * + * @param deviceID Device id. If it is 0, the first device in the current device list will be used by default. + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param size Size of tensor data that need to be allocated. + * @return Pointer to a {@link NN_Tensor} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_Tensor* OH_NNTensor_CreateWithSize(size_t deviceID, NN_TensorDesc *tensorDesc, size_t size); + +/** + * @brief Creates a {@link NN_Tensor} instance with specified fd. + * + * This method reuses the shared memory corresponding to the argument fd passed. It may comes from another {@link NN_Tensor} instance. + * When you call the {@link OH_NNTensor_DestroyTensor} method to release the tensor created by this method, the tensor data memory will not be released. \n + * + * Note that this method will copy the tensorDesc into {@link NN_Tensor}. Therefore you should destroy tensorDesc + * by {@link OH_NNTensorDesc_Destroy} when it is no longer used. \n + * + * Note that the tensorDesc will be released along with the {@link NN_Tensor} instance. Therefore every {@link NN_Tensor} + * instance you created must use a new tensorDesc that has not been used by another {@link NN_Tensor} instance. + * Otherwise, a tensorDesc will be released twice, which will bring a memory corruption of doulbe free. \n + * + * deviceID indicates the selected device. If it is 0, the first device in the current device list will be used by default. \n + * + * tensorDesc must be provided, if it is a null pointer, the method returns an error code. \n + * + * Call {@link OH_NNTensor_DestroyTensor} to release the {@link NN_Tensor} instance. \n + * + * @param deviceID Device id. If it is 0, the first device in the current device list will be used by default. + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. + * @param fd Fd of the shared memory to be resued. + * @param size Size of the shared memory to be resued. + * @param offset Offset of the shared memory to be resued. + * @return Pinter to a {@link NN_Tensor} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_Tensor* OH_NNTensor_CreateWithFd(size_t deviceID, + NN_TensorDesc *tensorDesc, + int fd, + size_t size, + size_t offset); + +/** + * @brief Releases a {@link NN_Tensor} instance. + * + * When the {@link NN_Tensor} instance is no longer used, this method needs to be called to release the instance. + * Otherwise, the memory leak will occur. \n + * + * If tensor or *tensor is a null pointer, this method will return error code and does not execute the release. \n + * + * @param tensorDesc Double pointer to the {@link NN_Tensor} instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensor_Destroy(NN_Tensor **tensor); + +/** + * @brief Gets the {@link NN_TensorDesc} instance of a {@link NN_Tensor}. + * + * Call this method to obtain the inner {@link NN_TensorDesc} instance pointer of the specified {@link NN_Tensor} instance. + * You can get various types of the tensor attributes such as name/format/data type/shape from the returned {@link NN_TensorDesc} instance. \n + * + * You should not destory the returned {@link NN_TensorDesc} instance because it points to the inner instance of {@link NN_Tensor}. + * Otherwise, a menory corruption of double free will occur when {@link OH_NNTensor_Destroy} is called. + * + * if tensor is a null pointer, this method will return null pointer. \n + * + * @param tensor Pointer to the {@link NN_Tensor} instance. + * @return Pointer to the {@link NN_TensorDesc} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_TensorDesc* OH_NNTensor_GetTensorDesc(const NN_Tensor *tensor); + +/** + * @brief Gets the data buffer of a {@link NN_Tensor}. + * + * You can read/write data from/to the tensor data buffer. The buffer is mapped from a shared memory on device, so the device dirver + * will get the tensor data directly by this "zero-copy" way. \n + * + * Note that you are only allowed to access the tensor data buffer with length of (size - offset), otherwise a heap corruption may occur. \n + * + * if tensor is a null pointer, this method will return null pointer. \n + * + * @param tensor Pointer to the {@link NN_Tensor} instance. + * @return Pointer to data buffer of the tensor, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +void* OH_NNTensor_GetDataBuffer(const NN_Tensor *tensor); + +/** + * @brief Gets the data fd of a {@link NN_Tensor}. + * + * The fd corresponds to a shared memory on device driver, and can be resued by another {@link NN_Tensor} through + * {@link OH_NNTensor_CreateWithFd}. \n + * + * if tensor or fd is a null pointer, this method will return error code. \n + * + * @param tensor Pointer to the {@link NN_Tensor} instance. + * @param fd The returned fd of tensor data. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensor_GetFd(const NN_Tensor *tensor, int *fd); + +/** + * @brief Gets the data size of a {@link NN_Tensor}. + * + * The size is as same as the argument size of {@link OH_NNTensor_CreateWithSize} and {@link OH_NNTensor_CreateWithFd}. + * But for a tensor created by {@link OH_NNTensor_Create}, it equals to the tensor byte size. \n + * + * Note that the real tensor data just uses the buffer segment [offset, size] of the Fd. \n + * + * if tensor or size is a null pointer, this method will return error code. \n + * + * @param tensor Pointer to the {@link NN_Tensor} instance. + * @param size The returned size of tensor data. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensor_GetSize(const NN_Tensor *tensor, size_t *size); + +/** + * @brief Get the data offset of a tensor. + * + * The offset corresponds to the fd of the tensor data, and can be resued by another {@link NN_Tensor} through + * {@link OH_NNTensor_CreateWithFd}. \n + * + * Note that the real tensor data just uses the buffer segment [offset, size] of the Fd. \n + * + * if tensor or offset is a null pointer, this method will return error code. \n + * + * @param tensor Pointer to the {@link NN_Tensor} instance. + * @param offset The returned offset of tensor data. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNTensor_GetOffset(const NN_Tensor *tensor, size_t *offset); + +/** + * @brief Creates an executor instance of the {@link OH_NNExecutor} type. + * + * This method constructs a model inference executor associated with the device based on the passed compilation. \n + * + * After the {@link OH_NNExecutor} instance is created, you can release the {@link OH_NNCompilation} + * instance if you do not need to create any other executors. \n + * + * @param compilation Pointer to the {@link OH_NNCompilation} instance. + * @return Pointer to a {@link OH_NNExecutor} instance, or NULL if it fails to create. + * @since 9 + * @version 1.0 + */ +OH_NNExecutor *OH_NNExecutor_Construct(OH_NNCompilation *compilation); + +/** + * @brief Obtains the dimension information about the output tensor. + * + * After {@link OH_NNExecutor_Run} is called to complete a single inference, call this method to obtain the specified output dimension + * information and number of dimensions. It is commonly used in dynamic shape input and output scenarios. \n + * + * As an output parameter, *shape must be a null pointer, otherwise the method will return an error code. + * Fou example, you should define int32_t* tensorShape = NULL, and pass &tensorShape as the argument of shape. \n + * + * You do not need to release the memory of shape. It will be released when executor is destroied. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * When {@link OH_NNExecutor_GetOutputShape} is called to obtain dimension information about the output tensor, + * outputIndices is {0, 1, 2}. + * + * @param shape Pointer to the int32_t array. The value of each element in the array is the length of the output tensor in each dimension. + * @param shapeLength Pointer to the uint32_t type. The number of output dimensions is returned. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_GetOutputShape(OH_NNExecutor *executor, + uint32_t outputIndex, + int32_t **shape, + uint32_t *shapeLength); + +/** + * @brief Destroys an executor instance to release the memory occupied by the executor. + * + * This method needs to be called to release the executor instance created by calling {@link OH_NNExecutor_Construct}. Otherwise, + * the memory leak will occur. \n + * + * If executor or *executor is a null pointer, this method only prints warning logs and does not execute the release. \n + * + * @param executor Double pointer to the {@link OH_NNExecutor} instance. + * @since 9 + * @version 1.0 + */ +void OH_NNExecutor_Destroy(OH_NNExecutor **executor); + +/** + * @brief Gets the input tensor count. + * + * You can get the input tensor count from the executor, and then create an input tensor descriptor with its index by + * {@link OH_NNExecutor_CreateInputTensorDesc}. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputCount Input tensor count returned. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_GetInputCount(const OH_NNExecutor *executor, size_t *inputCount); + +/** + * @brief Gets the output tensor count. + * + * You can get the output tensor count from the executor, and then create an output tensor descriptor with its index by + * {@link OH_NNExecutor_CreateOutputTensorDesc}. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param OutputCount Output tensor count returned. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_GetOutputCount(const OH_NNExecutor *executor, size_t *outputCount); + +/** + * @brief Creates an input tensor descriptor with its index. + * + * The input tensor descriptor contains all attributes of the input tensor. + * If the index exceeds the inputCount - 1, this method will return error code. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param index Input tensor index. + * @return Pointer to {@link NN_TensorDesc} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_TensorDesc* OH_NNExecutor_CreateInputTensorDesc(const OH_NNExecutor *executor, size_t index); + +/** + * @brief Creates an output tensor descriptor with its index. + * + * The output tensor descriptor contains all attributes of the output tensor. + * If the index exceeds the outputCount - 1, this method will return error code. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param index Output tensor index. + * @return Pointer to {@link NN_TensorDesc} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_TensorDesc* OH_NNExecutor_CreateOutputTensorDesc(const OH_NNExecutor *executor, size_t index); + +/** + * @brief Gets the dimension ranges of an input tensor. + * + * The supported dimension ranges of an input tensor with dynamic shape may be different among various devices. + * You can call this method to get the dimension ranges of the input tensor supported by the device. + * *minInputDims contains the minimum demensions of the input tensor, and *maxInputDims contains the maximum, + * e.g. if an input tensor has dynamic shape [-1, -1, -1, 3], its *minInputDims may be [1, 10, 10, 3] and + * *maxInputDims may be [100, 1024, 1024, 3] on the device. \n + * + * If the index exceeds the inputCount - 1, this method will return error code. \n + * + * As an output parameter, *minInputDims or *maxInputDims must be a null pointer, otherwise the method will return an error code. + * For example, you should define int32_t* minInDims = NULL, and pass &minInDims as the argument of minInputDims. \n + * + * You do not need to release the memory of *minInputDims or *maxInputDims. It will be released when executor is destroied. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param index Input tensor index. + * @param minInputDims Returned pointer to an array contains the minimum dimensions of the input tensor. + * @param maxInputDims Returned pointer to an array contains the maximum dimensions of the input tensor. + * @param shapeLength Returned length of the shape of input tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_GetInputDimRange(const OH_NNExecutor *executor, + size_t index, + size_t **minInputDims, + size_t **maxInputDims, + size_t *shapeLength); + +/** + * @brief Sets the callback function handle for the post-process when the asynchronous execution has been done. + * + * The definition fo the callback function: {@link NN_OnRunDone}. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param onRunDone Callback function handle {@link NN_OnRunDone}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetOnRunDone(OH_NNExecutor *executor, NN_OnRunDone onRunDone); + +/** + * @brief Sets the callback function handle for the post-process when the device driver service is dead during asynchronous execution. + * + * The definition fo the callback function: {@link NN_OnServiceDied}. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param onServiceDied Callback function handle {@link NN_OnServiceDied}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetOnServiceDied(OH_NNExecutor *executor, NN_OnServiceDied onServiceDied); + +/** + * @brief Synchronous execution of the model inference. + * + * Input and output tensors should be created first by {@link OH_NNTensor_Create}, {@link OH_NNTensor_CreateWithSize} or + * {@link OH_NNTensor_CreateWithFd}. And then the input tensors data which is got by {@link OH_NNTensor_GetDataBuffer} must be filled. + * The executor will then yield out the results by inference execution and fill them into output tensors data for you to read. \n + * + * In the case of dynamic shape, you can get the real output shape directly by {@link OH_NNExecutor_GetOutputShape}, or you + * can create a tensor descriptor from an output tensor by {@link OH_NNTensor_GetTensorDesc}, and then read its real shape + * by {@link OH_NNTensorDesc_GetShape}. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputTensor An array of input tensors {@link NN_Tensor}. + * @param inputCount Number of input tensors. + * @param outputTensor An array of output tensors {@link NN_Tensor}. + * @param outputCount Number of output tensors. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_RunSync(OH_NNExecutor *executor, + NN_Tensor *inputTensor[], + size_t inputCount, + NN_Tensor *outputTensor[], + size_t outputCount); + +/** + * @brief Asynchronous execution of the model inference. + * + * Input and output tensors should be created first by {@link OH_NNTensor_Create}, {@link OH_NNTensor_CreateWithSize} or + * {@link OH_NNTensor_CreateWithFd}. And then the input tensors data which is got by {@link OH_NNTensor_GetDataBuffer} must be filled. + * The executor will yield out the results by inference execution and fill them into output tensors data for you to read. \n + * + * In the case of dynamic shape, you can get the real output shape directly by {@link OH_NNExecutor_GetOutputShape}, or you + * can create a tensor descriptor from an output tensor by {@link OH_NNTensor_GetTensorDesc}, and then read its real shape + * by {@link OH_NNTensorDesc_GetShape}. \n + * + * The method is non-blocked and will return immediately. The callback function handles are set by {@link OH_NNExecutor_SetOnRunDone} + * and {@link OH_NNExecutor_SetOnServiceDied}. If the execution time reaches the timeout, the execution will be terminated + * with no outputs, and the errCode returned in callback function {@link NN_OnRunDone} will be {@link OH_NN_TIMEOUT}. \n + * + * The userData is asynchronous execution identifier and will be returned as the first parameter of the callback function. + * You can input any value you want as long as it can identify different asynchronous executions. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputTensor An array of input tensors {@link NN_Tensor}. + * @param inputCount Number of input tensors. + * @param outputTensor An array of output tensors {@link NN_Tensor}. + * @param outputCount Number of output tensors. + * @param timeout Time limit (millisecond) of the asynchronous execution, e.g. 1000. + * @param userData Asynchronous execution identifier. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_RunAsync(OH_NNExecutor *executor, + NN_Tensor *inputTensor[], + size_t inputCount, + NN_Tensor *outputTensor[], + size_t outputCount, + int32_t timeout, + void* userData); + +/** + * @brief Obtains the IDs of all devices connected. + * + * Each device has an unique and fixed ID. This method returns device IDs on the current device through the uint32_t array. \n + * + * Device IDs are returned through the size_t array. Each element of the array is the ID of a single device. \n + * + * The array memory is managed inside, so you do not need to care about it. + * The data pointer is valid before this method is called next time. \n + * + * @param allDevicesID Pointer to the size_t array. The input *allDevicesID must be a null pointer. Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. + * @param deviceCount Pointer of the uint32_t type, which is used to return the length of (*allDevicesID). + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNDevice_GetAllDevicesID(const size_t **allDevicesID, uint32_t *deviceCount); + +/** + * @brief Obtains the name of the specified device. + * + * deviceID specifies the device whose name will be obtained. The device ID needs to be obtained by calling {@link OH_NNDevice_GetAllDevicesID}. + * If it is 0, the first device in the current device list will be used by default. \n + * + * The value of (*name) is a C-style string ended with '\0'. *name must be a null pointer. + * Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. + * Fou example, you should define char* deviceName = NULL, and pass &deviceName as the argument of name. \n + * + * @param deviceID Device ID. If it is 0, the first device in the current device list will be used by default. + * @param name The device name returned. + + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNDevice_GetName(size_t deviceID, const char **name); + +/** + * @brief Obtains the type information of the specified device. + * + * deviceID specifies the device whose type will be obtained. If it is 0, the first device in the current device + * list will be used. Currently the following device types are supported: + * - OH_NN_CPU: CPU device. + * - OH_NN_GPU: GPU device. + * - OH_NN_ACCELERATOR: machine learning dedicated accelerator. + * - OH_NN_OTHERS: other hardware types. \n + * + * @param deviceID Device ID. If it is 0, the first device in the current device list will be used by default. + * @param deviceType The device type {@link OH_NN_DeviceType} returned. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNDevice_GetType(size_t deviceID, OH_NN_DeviceType *deviceType); + +#ifdef __cplusplus +} +#endif // __cplusplus + +/** @} */ +#endif // NEURAL_NETWORK_CORE_H diff --git a/ai/neural_network_runtime/neural_network_runtime.h b/ai/neural_network_runtime/neural_network_runtime.h index b7740e18b332cf62ae3e71445f2e79965194699d..215fa0b33df50e9bc623674a1c6211100b5a2e5d 100644 --- a/ai/neural_network_runtime/neural_network_runtime.h +++ b/ai/neural_network_runtime/neural_network_runtime.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022 Huawei Device Co., Ltd. + * Copyright (c) 2022-2023 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at @@ -21,76 +21,158 @@ * * @Syscap SystemCapability.Ai.NeuralNetworkRuntime * @since 9 - * @version 1.0 + * @version 2.0 */ /** * @file neural_network_runtime.h * * @brief Defines the Neural Network Runtime APIs. The AI inference framework uses the Native APIs provided by Neural Network Runtime - * to construct and compile models and perform inference and computing on acceleration hardware. + * to construct models. + * * Note: Currently, the APIs of Neural Network Runtime do not support multi-thread calling. \n * + * include "neural_network_runtime/neural_network_runtime.h" * @library libneural_network_runtime.so * @since 9 - * @version 1.0 + * @version 2.0 */ #ifndef NEURAL_NETWORK_RUNTIME_H #define NEURAL_NETWORK_RUNTIME_H #include "neural_network_runtime_type.h" +#include "neural_network_core.h" +#include "neural_network_runtime_compat.h" #ifdef __cplusplus extern "C" { #endif +/** + * @brief Creates a {@link NN_QuantParam} instance. + * + * After the {@link NN_QuantParam} instance is created, call {@link OH_NNQuantParam_SetScales}, {@link OH_NNQuantParam_SetZeroPoints}, + * {@link OH_NNQuantParam_SetNumBits} to set its attributes, and then call {@link OH_NNModel_SetTensorQuantParams} to set it + * to a tensor. After that you should destroy it by calling {@link OH_NNQuantParam_Destroy} to avoid memory leak. \n + * + * @return Pointer to a {@link NN_QuantParam} instance, or NULL if it fails to create. + * @since 11 + * @version 1.0 + */ +NN_QuantParam *OH_NNQuantParam_Create(); + +/** + * @brief Sets the scales of the {@link NN_QuantParam} instance. + * + * The parameter quantCount<\b> is the number of quantization parameters of a tensor, e.g. the quantCount is the channel + * count if the tensor is per-channel quantized. \n + * + * @param quantParams Pointer to the {@link NN_QuantParam} instance. + * @param scales An array of scales for all quantization parameters of the tensor. + * @param quantCount Number of quantization parameters of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNQuantParam_SetScales(NN_QuantParam *quantParams, const double *scales, size_t quantCount); + +/** + * @brief Sets the zero points of the {@link NN_QuantParam} instance. + * + * The parameter quantCount<\b> is the number of quantization parameters of a tensor, e.g. the quantCount is the channel + * count if the tensor is per-channel quantized. \n + * + * @param quantParams Pointer to the {@link NN_QuantParam} instance. + * @param zeroPoints An array of zero points for all quantization parameters of the tensor. + * @param quantCount Number of quantization parameters of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNQuantParam_SetZeroPoints(NN_QuantParam *quantParams, const int32_t *zeroPoints, size_t quantCount); + +/** + * @brief Sets the number bits of the {@link NN_QuantParam} instance. + * + * The parameter quantCount<\b> is the number of quantization parameters of a tensor, e.g. the quantCount is the channel + * count if the tensor is per-channel quantized. \n + * + * @param quantParams Pointer to the {@link NN_QuantParam} instance. + * @param numBits An array of number bits for all quantization parameters of the tensor. + * @param quantCount Number of quantization parameters of the tensor. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNQuantParam_SetNumBits(NN_QuantParam *quantParams, const uint32_t *numBits, size_t quantCount); + +/** + * @brief Releases a {@link NN_QuantParam} instance. + * + * The {@link NN_QuantParam} instance needs to be released to avoid memory leak after it is set to a {@link NN_TensorDesc}. \n + * + * If quantParams or *quantParams is a null pointer, this method only prints warning logs and does not + * execute the release. \n + * + * @param quantParams Double pointer to the {@link NN_QuantParam} instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNQuantParam_Destroy(NN_QuantParam **quantParams); + /** * @brief Creates a model instance of the {@link OH_NNModel} type and uses other APIs provided by OH_NNModel to construct the model instance. * * Before composition, call {@link OH_NNModel_Construct} to create a model instance. Based on the model topology, - * call the {@link OH_NNModel_AddTensor}, {@link OH_NNModel_AddOperation}, and {@link OH_NNModel_SetTensorData} methods - * to fill in the data and operator nodes of the model, and then call {@link OH_NNModel_SpecifyInputsAndOutputs} to specify the inputs and outputs of the model. + * call the {@link OH_NNModel_AddTensorToModel}, {@link OH_NNModel_AddOperation}, and {@link OH_NNModel_SetTensorData} methods + * to fill in the data and operator nodes of the model, and then call {@link OH_NNModel_SpecifyInputsAndOutputs} to specify the inputs and outputs of the model. * After the model topology is constructed, call {@link OH_NNModel_Finish} to build the model. \n * - * After a model instance is used, you need to destroy it by calling {@link OH_NNModel_Destroy} to avoid memory leak. \n + * After a model instance is no longer used, you need to destroy it by calling {@link OH_NNModel_Destroy} to avoid memory leak. \n * - * @return Returns the pointer to a {@link OH_NNModel} instance. + * @return Pointer to a {@link OH_NNModel} instance, or NULL if it fails to create. * @since 9 * @version 1.0 */ OH_NNModel *OH_NNModel_Construct(void); /** - * @brief Adds a tensor to a model instance. + * @brief Adds a tensor to the model instance. * * The data node and operator parameters in the Neural Network Runtime model are composed of tensors of the model. - * This method is used to add tensors to a model instance based on the tensor parameter. - * The sequence of adding tensors is specified by the index value recorded in the model. The {@link OH_NNModel_SetTensorData}, {@link OH_NNModel_AddOperation}, - * and {@link OH_NNModel_SpecifyInputsAndOutputs} methods specifies tensors based on the index value. \n + * This method is used to add tensors to a model instance based on the tensorDesc parameter with type of {@link NN_TensorDesc}. + * {@link NN_TensorDesc} contains some attributes such as shape, format, data type and provides corresponding APIs to access them. + * The order of adding tensors is specified by the indices recorded in the model. The {@link OH_NNModel_SetTensorData}, {@link OH_NNModel_AddOperation}, + * and {@link OH_NNModel_SpecifyInputsAndOutputs} methods specify tensors based on the indices. \n * * Neural Network Runtime supports inputs and outputs of the dynamic shape. When adding a data node with a dynamic shape, - * you need to set the dimensions that support dynamic changes in tensor.dimensions to -1. - * For example, if tensor.dimensions of a four-dimensional tensor is set to [1, -1, 2, 2], the second dimension supports dynamic changes. \n + * you need to set the dimensions that support dynamic changes to -1. + * For example, if the shape of a four-dimensional tensor is set to [1, -1, 2, 2], the second dimension supports dynamic changes. \n * * @param model Pointer to the {@link OH_NNModel} instance. - * @param tensor Pointer to the {@link OH_NN_Tensor} tensor. The tensor specifies the attributes of the tensor added to the model instance. + * @param tensorDesc Pointer to the {@link NN_TensorDesc} instance. The tensor descriptor specifies the attributes of the tensor added to the model instance. * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 + * @since 11 * @version 1.0 */ -OH_NN_ReturnCode OH_NNModel_AddTensor(OH_NNModel *model, const OH_NN_Tensor *tensor); +OH_NN_ReturnCode OH_NNModel_AddTensorToModel(OH_NNModel *model, const NN_TensorDesc *tensorDesc); /** * @brief Sets the tensor value. * - * For tensors with constant values (such as model weights), you need to use this method in the composition phase. - * The index value of a tensor is determined by the sequence in which the tensor is added to the model. - * For details about how to add a tensor, see {@link OH_NNModel_AddTensor}. \n + * For tensors with constant values (such as model weights), you need to use this method to set their data. + * The index of a tensor is determined by the order in which the tensor is added to the model. + * For details about how to add a tensor, see {@link OH_NNModel_AddTensorToModel}. \n * * @param model Pointer to the {@link OH_NNModel} instance. - * @param index Index value of a tensor. + * @param index Index of a tensor. * @param dataBuffer Pointer to real data. * @param length Length of the data buffer. * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. @@ -100,20 +182,46 @@ OH_NN_ReturnCode OH_NNModel_AddTensor(OH_NNModel *model, const OH_NN_Tensor *ten */ OH_NN_ReturnCode OH_NNModel_SetTensorData(OH_NNModel *model, uint32_t index, const void *dataBuffer, size_t length); +/** + * @brief Sets the quantization parameter of a tensor. + * + * @param model Pointer to the {@link OH_NNModel} instance. + * @param index Index of a tensor. + * @param quantParam Pointer to the quantization parameter instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNModel_SetTensorQuantParams(OH_NNModel *model, uint32_t index, NN_QuantParam *quantParam); + +/** + * @brief Sets the tensor type. See {@link OH_NN_TensorType} for details. + * + * @param model Pointer to the {@link OH_NNModel} instance. + * @param index Index of a tensor. + * @param tensorType Tensor type of {@link OH_NN_TensorType}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @since 11 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNModel_SetTensorType(OH_NNModel *model, uint32_t index, OH_NN_TensorType tensorType); + /** * @brief Adds an operator to a model instance. * * This method is used to add an operator to a model instance. The operator type is specified by op, and - * the operator parameters, inputs, and outputs are specified by paramIndices, inputIndices, and outputIndices respectively. + * the operator parameters, inputs, and outputs are specified by paramIndices, inputIndices, and outputIndices respectively. * This method verifies the attributes of operator parameters and the number of input and output parameters. - * These attributes must be correctly set when {@link OH_NNModel_AddTensor} is called to add tensors. + * These attributes must be correctly set when {@link OH_NNModel_AddTensorToModel} is called to add tensors. * For details about the expected parameters, input attributes, and output attributes of each operator, see {@link OH_NN_OperationType}. \n * - * paramIndices, inputIndices, and outputIndices store index values of tensors. - * Index values are determined by the sequence in which tensors are added to the model. - * For details about how to add a tensor, see {@link OH_NNModel_AddTensor}. \n + * paramIndices, inputIndices, and outputIndices store the indices of tensors. + * The indices are determined by the order in which tensors are added to the model. + * For details about how to add a tensor, see {@link OH_NNModel_AddTensorToModel}. \n * - * If unnecessary parameters are added for adding an operator, this method returns {@link OH_NN_INVALID_PARAMETER}. + * If unnecessary parameters are added when adding an operator, this method returns {@link OH_NN_INVALID_PARAMETER}. * If no operator parameter is set, the operator uses the default parameter value. * For details about the default values, see {@link OH_NN_OperationType}. \n * @@ -137,10 +245,10 @@ OH_NN_ReturnCode OH_NNModel_AddOperation(OH_NNModel *model, * @brief Specifies the inputs and outputs of a model. * * A tensor must be specified as the end-to-end inputs and outputs of a model instance. This type of tensor cannot be set - * using {@link OH_NNModel_SetTensorData}. The OH_NNExecutor method needs to be called in the execution phase to set the input and output data. \n + * using {@link OH_NNModel_SetTensorData}. \n * - * The index value of a tensor is determined by the sequence in which the tensor is added to the model. - * For details about how to add a tensor, see {@link OH_NNModel_AddTensor}. \n + * The index of a tensor is determined by the order in which the tensor is added to the model. + * For details about how to add a tensor, see {@link OH_NNModel_AddTensorToModel}. \n * * Currently, the model inputs and outputs cannot be set asynchronously. \n * @@ -159,8 +267,8 @@ OH_NN_ReturnCode OH_NNModel_SpecifyInputsAndOutputs(OH_NNModel *model, /** * @brief Completes model composition. * - * After the model topology is set up, call this method to indicate that the composition is complete. After this method is called, - * additional composition operations cannot be performed. If {@link OH_NNModel_AddTensor}, {@link OH_NNModel_AddOperation}, + * After the model topology is set up, call this method to indicate that the composition is complete. After this method is called, + * additional composition operations cannot be performed. If {@link OH_NNModel_AddTensorToModel}, {@link OH_NNModel_AddOperation}, * {@link OH_NNModel_SetTensorData}, and {@link OH_NNModel_SpecifyInputsAndOutputs} are called, * {@link OH_NN_OPERATION_FORBIDDEN} is returned. \n * @@ -180,9 +288,9 @@ OH_NN_ReturnCode OH_NNModel_Finish(OH_NNModel *model); * * This method needs to be called to release the model instance created by calling {@link OH_NNModel_Construct}. Otherwise, memory leak will occur. \n * - * If model or *model is a null pointer, this method only prints warning logs and does not execute the release logic. \n + * If model or *model is a null pointer, this method only prints warning logs and does not execute the release. \n * - * @param model Level-2 pointer to the {@link OH_NNModel} instance. After a model instance is destroyed, this method sets *model to a null pointer. + * @param model Double pointer to the {@link OH_NNModel} instance. After a model instance is destroyed, this method sets *model to a null pointer. * @since 9 * @version 1.0 */ @@ -201,9 +309,8 @@ void OH_NNModel_Destroy(OH_NNModel **model); * * @param model Pointer to the {@link OH_NNModel} instance. * @param deviceID Device ID to be queried, which can be obtained by using {@link OH_NNDevice_GetAllDevicesID}. - * @param isSupported Pointer to the bool array. When this method is called, (*isSupported) must be a null pointer. - * Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. - * + * @param isSupported Pointer to the bool array. When this method is called, (*isSupported) must be a null pointer. + * Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. * @param opCount Number of operators in a model instance, corresponding to the length of the (*isSupported) array. * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. @@ -215,474 +322,6 @@ OH_NN_ReturnCode OH_NNModel_GetAvailableOperations(OH_NNModel *model, const bool **isSupported, uint32_t *opCount); - -/** - * @brief Creates a compilation instance of the {@link OH_NNCompilation} type. - * - * After the OH_NNModel module completes model construction, APIs provided by the OH_NNCompilation module pass the model - * to underlying device for compilation. This method creates a {@link OH_NNCompilation} instance - * based on the passed {@link OH_NNModel} instance. The {@link OH_NNCompilation_SetDevice} method is called - * to set the device to compile on, and {@link OH_NNCompilation_Build} is then called to complete compilation.\n - * - * In addition to computing device selection, the OH_NNCompilation module supports features such as model caching, performance preference, - * priority setting, and float16 computing, which can be implemented by the following methods: - * - {@link OH_NNCompilation_SetCache} - * - {@link OH_NNCompilation_SetPerformanceMode} - * - {@link OH_NNCompilation_SetPriority} - * - {@link OH_NNCompilation_EnableFloat16} \n - * - * After {@link OH_NNCompilation} is created by calling this method, the {@link OH_NNModel} instance can be released. \n - * - * @param model Pointer to the {@link OH_NNModel} instance. - * @return Returns the pointer to a {@link OH_NNCompilation} instance. - * @since 9 - * @version 1.0 - */ -OH_NNCompilation *OH_NNCompilation_Construct(const OH_NNModel *model); - -/** - * @brief Specifies the device for model compilation and computing. - * - * In the compilation phase, you need to specify the device for model compilation and computing. Call {@link OH_NNDevice_GetAllDevicesID} - * to obtain available device IDs. Call {@link OH_NNDevice_GetType} and {@link OH_NNDevice_GetName} to obtain device information - * and pass target device IDs to this method for setting. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @param deviceID Device ID. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. - * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_SetDevice(OH_NNCompilation *compilation, size_t deviceID); - -/** - * @brief Set the cache directory and version of the compiled model. - * - * On the device that supports caching, a model can be saved as a cache file after being compiled at the device driver layer. - * The model can be directly read from the cache file in the next compilation, saving recompilation time. - * This method performs different operations based on the passed cache directory and version:\n - * - * - No file exists in the cache directory: - * Caches the compiled model to the directory and sets the cache version to version. \n - * - * - A complete cache file exists in the cache directory, and its version is version: - * Reads the cache file in the path and passes the data to the underlying device for conversion into executable model instances. \n - * - * - A complete cache file exists in the cache directory, and its version is earlier than version: - * When model compilation is complete on the underlying device, overwrites the cache file and changes the version number to version. \n - * - * - A complete cache file exists in the cache directory, and its version is later than version: - * Returns the {@link OH_NN_INVALID_PARAMETER} error code without reading the cache file. \n - * - * - The cache file in the cache directory is incomplete or you do not have the permission to access the cache file. - * Returns the {@link OH_NN_INVALID_FILE} error code. \n - * - * - The cache directory does not exist or you do not have the access permission. - * Returns the {@link OH_NN_INVALID_PATH} error code. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @param cachePath Directory for storing model cache files. This method creates directories for different devices in the cachePath directory. - * You are advised to use a separate cache directory for each model. - * @param version Cache version. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_SetCache(OH_NNCompilation *compilation, const char *cachePath, uint32_t version); - -/** - * @brief Sets the performance mode for model computing. - * - * Neural Network Runtime allows you to set the performance mode for model computing to meet the requirements of low power consumption - * and ultimate performance. If this method is not called to set the performance mode in the compilation phase, the compilation instance assigns - * the {@link OH_NN_PERFORMANCE_NONE} mode for the model by default. In this case, the device performs computing in the default performance mode. \n - * - * If this method is called on the device that does not support the setting of the performance mode, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @param performanceMode Performance mode. For details about the available performance modes, see {@link OH_NN_PerformanceMode}. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_SetPerformanceMode(OH_NNCompilation *compilation, - OH_NN_PerformanceMode performanceMode); - -/** - * @brief Sets the model computing priority. - * - * Neural Network Runtime allows you to set computing priorities for models. - * The priorities apply only to models created by the process with the same UID. - * The settings will not affect models created by processes with different UIDs on different devices. \n - * - * If this method is called on the device that does not support the priority setting, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @param priority Priority. For details about the optional priorities, see {@link OH_NN_Priority}. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_SetPriority(OH_NNCompilation *compilation, OH_NN_Priority priority); - -/** - * @brief Enables float16 for computing. - * - * Currently, Neural Network Runtime supports only float32 and int8. If this method is called on a device that supports float16, - * float16 will be used for computing the float32 model to reduce memory usage and execution time. \n - * - * If this method is called on the device that does not support float16, the {@link OH_NN_UNAVALIDABLE_DEVICE} error code is returned. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @param enableFloat16 Indicates whether to enable float16. If this parameter is set to true, float16 inference is performed. - * If this parameter is set to false, float32 inference is performed. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, an error code is returned. - * For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_EnableFloat16(OH_NNCompilation *compilation, bool enableFloat16); - -/** - * @brief Compiles a model. - * - * After the compilation configuration is complete, call this method to return the compilation result. The compilation instance pushes the model and - * compilation options to the device for compilation. After this method is called, additional compilation operations cannot be performed. - * If the {@link OH_NNCompilation_SetDevice}, {@link OH_NNCompilation_SetCache}, {@link OH_NNCompilation_SetPerformanceMode}, - * {@link OH_NNCompilation_SetPriority}, and {@link OH_NNCompilation_EnableFloat16} methods are called, {@link OH_NN_OPERATION_FORBIDDEN} is returned. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. - * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNCompilation_Build(OH_NNCompilation *compilation); - -/** - * @brief Releases the Compilation object. - * - * This method needs to be called to release the compilation instance created by calling {@link OH_NNCompilation_Construct}. Otherwise, memory leak will occur. \n - * - * If compilation or *compilation is a null pointer, this method only prints warning logs and does not execute the release logic. \n - * - * @param compilation Level-2 pointer to the {@link OH_NNCompilation} instance. After a compilation instance is destroyed, - * this method sets *compilation to a null pointer. - * @since 9 - * @version 1.0 - */ -void OH_NNCompilation_Destroy(OH_NNCompilation **compilation); - - -/** - * @brief Creates an executor instance of the {@link OH_NNExecutor} type. - * - * This method constructs a model inference executor associated with the device based on the passed compiler. Use {@link OH_NNExecutor_SetInput} - * to set the model input data. After the input data is set, call {@link OH_NNExecutor_Run} to perform inference and then call - * {@link OH_NNExecutor_SetOutput} to obtain the computing result. \n - * - * After calling this method to create the {@link OH_NNExecutor} instance, you can release the {@link OH_NNCompilation} - * instance if you do not need to create any other executors. \n - * - * @param compilation Pointer to the {@link OH_NNCompilation} instance. - * @return Pointer to a {@link OH_NNExecutor} instance. - * @since 9 - * @version 1.0 - */ -OH_NNExecutor *OH_NNExecutor_Construct(OH_NNCompilation *compilation); - -/** - * @brief Sets the single input data for a model. - * - * This method copies the data whose length is specified by length (in bytes) in dataBuffer to the shared memory - * of the underlying device. inputIndex specifies the input to be set and tensor sets information such as the input shape, - * type, and quantization parameters. \n - * - * Neural Network Runtime supports models with dynamical shape input. For fixed shape input and dynamic shape input scenarios, - * this method uses different processing policies. - * - * - Fixed shape input: The attributes of tensor must be the same as those of the tensor added by calling - * {@link OH_NNModel_AddTensor} in the composition phase. - * - Dynamic shape input: In the composition phase, because the shape is not fixed, each value in tensor.dimensions must be greater than - * 0 in the method calls to determine the shape input in the calculation phase. When setting the shape, you can modify - * only the dimension whose value is -1. Assume that [-1, 224, 224, 3] is input as the the dimension of A in the composition phase. - * When this method is called, only the size of the first dimension can be modified, for example, to [3, 224, 224, 3]. - * If other dimensions are adjusted, {@link OH_NN_INVALID_PARAMETER} is returned. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * In input settings, the index value for the three inputs is {0, 1, 2}. \n - * - * @param tensor Sets the tensor corresponding to the input data. - * @param dataBuffer Pointer to the input data. - * @param length Length of the data buffer, in bytes. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_SetInput(OH_NNExecutor *executor, - uint32_t inputIndex, - const OH_NN_Tensor *tensor, - const void *dataBuffer, - size_t length); - -/** - * @brief Sets the buffer for a single output of a model. - * - * This method binds the buffer to which dataBuffer points to the output specified by outputIndex. - * The length of the buffer is specified by length. \n - * - * After {@link OH_NNExecutor_Run} is called to complete a single model inference, Neural Network Runtime compares - * the length of the buffer to which dataBuffer points with the length of the output data and returns different results - * based on the actual situation. \n - * - * - If the buffer length is greater than or equal to the data length, the inference result is copied to the buffer and - * {@link OH_NN_SUCCESS} is returned. You can read the inference result from dataBuffer. - * - If the buffer length is smaller than the data length, {@link OH_NNExecutor_Run} returns {@link OH_NN_INVALID_PARAMETER} - * and generates a log indicating that the buffer is too small. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} - * is called. In output buffer settings, the index value for the three outputs is {0, 1, 2}. - * @param dataBuffer Pointer to the output data. - * @param length Length of the data buffer, in bytes. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_SetOutput(OH_NNExecutor *executor, - uint32_t outputIndex, - void *dataBuffer, - size_t length); - -/** - * @brief Obtains the dimension information about the output tensor. - * - * After {@link OH_NNExecutor_Run} is called to complete a single inference, call this method to obtain the specified output dimension - * information and number of dimensions. It is commonly used in dynamic shape input and output scenarios. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * When {@link OH_NNExecutor_GetOutputShape} is called to obtain dimension information about the output tensor, - * outputIndices is {0, 1, 2}. - * - * @param shape Pointer to the int32_t array. The value of each element in the array is the length of the output tensor in each dimension. - * @param shapeLength Pointer to the uint32_t type. The number of output dimensions is returned. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_GetOutputShape(OH_NNExecutor *executor, - uint32_t outputIndex, - int32_t **shape, - uint32_t *shapeLength); - -/** - * @brief Performs inference. - * - * Performs end-to-end inference and computing of the model on the device associated with the executor. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_Run(OH_NNExecutor *executor); - -/** - * @brief Allocates shared memory to a single input on a device. - * - * Neural Network Runtime provides a method for proactively allocating shared memory on a device. By specifying the executor and input index value, - * this method allocates shared memory whose size is specified by length on the device associated with a single input and returns the - * operation result through the {@link OH_NN_Memory} instance. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * In the memory input application, the index value for the three inputs is {0, 1, 2}. - * @param length Memory size to be applied for, in bytes. - * @return Pointer to a {@link OH_NN_Memory} instance. - * @since 9 - * @version 1.0 - */ -OH_NN_Memory *OH_NNExecutor_AllocateInputMemory(OH_NNExecutor *executor, uint32_t inputIndex, size_t length); - -/** - * @brief Allocates shared memory to a single output on a device. - * - * Neural Network Runtime provides a method for proactively allocating shared memory on a device. By specifying the executor and - * output index value, this method allocates shared memory whose size is specified by length on the device associated with - * a single output and returns the operation result through the {@link OH_NN_Memory} instance. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * In output memory application, the index value for the three outputs is {0, 1, 2}. - * @param length Memory size to be applied for, in bytes. - * @return Pointer to a {@link OH_NN_Memory} instance. - * @since 9 - * @version 1.0 - */ -OH_NN_Memory *OH_NNExecutor_AllocateOutputMemory(OH_NNExecutor *executor, uint32_t outputIndex, size_t length); - -/** - * @brief Releases the input memory to which the {@link OH_NN_Memory} instance points. - * - * This method needs to be called to release the memory instance created by calling {@link OH_NNExecutor_AllocateInputMemory}. - * Otherwise, memory leak will occur. - * The mapping between inputIndex and memory must be the same as that in memory instance creation. \n - * - * If memory or *memory is a null pointer, this method only prints warning logs and does not execute the release logic. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * In memory input release, the index value for the three inputs is {0, 1, 2}. - * @param memory Level-2 pointer to the {@link OH_NN_Memory} instance. After shared memory is destroyed, this method sets *memory to a null pointer. - * @since 9 - * @version 1.0 - */ -void OH_NNExecutor_DestroyInputMemory(OH_NNExecutor *executor, uint32_t inputIndex, OH_NN_Memory **memory); - -/** - * @brief Releases the output memory to which the {@link OH_NN_Memory} instance points. - * - * This method needs to be called to release the memory instance created by calling {@link OH_NNExecutor_AllocateOutputMemory}. Otherwise, memory leak will occur. - * The mapping between outputIndex and memory must be the same as that in memory instance creation. \n - * - * If memory or *memory is a null pointer, this method only prints warning logs and does not execute the release logic. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * In output memory release, the index value for the three outputs is {0, 1, 2}. - * @param memory Level-2 pointer to the {@link OH_NN_Memory} instance. After shared memory is destroyed, this method sets *memory to a null pointer. - * @since 9 - * @version 1.0 - */ -void OH_NNExecutor_DestroyOutputMemory(OH_NNExecutor *executor, uint32_t outputIndex, OH_NN_Memory **memory); - -/** - * @brief Specifies the hardware shared memory pointed to by the {@link OH_NN_Memory} instance as the shared memory used by a single input. - * - * In scenarios where memory needs to be managed by yourself, this method binds the execution input to the {@link OH_NN_Memory} memory instance. - * During computing, the underlying device reads the input data from the shared memory pointed to by the memory instance. - * By using this method, concurrent execution of input setting, computing, and read can be implemented to improve inference efficiency of a data flow. \n - * - * @param executor Pointer to the {@link OH_NNExecutor} instance. - * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * When the input shared memory is specified, the index value for the three inputs is {0, 1, 2}. - * @param tensor Pointer to {@link OH_NN_Tensor}, used to set the tensor corresponding to a single input. - * @param memory Pointer to {@link OH_NN_Memory}. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_SetInputWithMemory(OH_NNExecutor *executor, - uint32_t inputIndex, - const OH_NN_Tensor *tensor, - const OH_NN_Memory *memory); - -/** - * @brief Specifies the hardware shared memory pointed to by the {@link OH_NN_Memory} instance as the shared memory used by a single output. - * - * In scenarios where memory needs to be managed by yourself, this method binds the execution output to the {@link OH_NN_Memory} memory instance. - * When computing is performed, the underlying hardware directly writes the computing result to the shared memory to which the memory instance points. - * By using this method, concurrent execution of input setting, computing, and read can be implemented to improve inference efficiency of a data flow. \n - * - * @param executor Executor. - * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. - * When output shared memory is specified, the index value for the three outputs is {0, 1, 2}. - * @param memory Pointer to {@link OH_NN_Memory}. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNExecutor_SetOutputWithMemory(OH_NNExecutor *executor, - uint32_t outputIndex, - const OH_NN_Memory *memory); - -/** - * @brief Destroys an executor instance to release the memory occupied by the executor. - * - * This method needs to be called to release the executor instance created by calling {@link OH_NNExecutor_Construct}. Otherwise, - * memory leak will occur. \n - * - * If executor or *executor is a null pointer, this method only prints warning logs and does not execute the release logic. \n - * - * @param executor Level-2 pointer to the {@link OH_NNExecutor} instance. - * @since 9 - * @version 1.0 - */ -void OH_NNExecutor_Destroy(OH_NNExecutor **executor); - - -/** - * @brief Obtains the ID of the device connected to Neural Network Runtime. - * - * Each device has a unique and fixed ID in Neural Network Runtime. This method returns device IDs on the current device through the uint32_t array. \n - * - * Device IDs are returned through the size_t array. Each element of the array is the ID of a single device. - * The array memory is managed by Neural Network Runtime. - * The data pointer is valid before this method is called next time. \n - * - * @param allDevicesID Pointer to the size_t array. The input *allDevicesID must be a null pointer. Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. - * @param deviceCount Pointer of the uint32_t type, which is used to return the length of (*allDevicesID). - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. - * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNDevice_GetAllDevicesID(const size_t **allDevicesID, uint32_t *deviceCount); - -/** - * @brief Obtains the name of the specified device. - * - * deviceID specifies the device whose name will be obtained. The device ID needs to be obtained by calling {@link OH_NNDevice_GetAllDevicesID}. \n - * - * @param deviceID Device ID. - * @param name Pointer to the char array. The passed (*char) must be a null pointer. Otherwise, {@link OH_NN_INVALID_PARAMETER} is returned. - * The value of (*name) is a C-style string ended with '\0'. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNDevice_GetName(size_t deviceID, const char **name); - -/** - * @brief Obtains the type information of the specified device. - * - * deviceID specifies the device whose type will be obtained. Currently, Neural Network Runtime supports the following device types: - * - OH_NN_CPU: CPU device. - * - OH_NN_GPU: GPU device. - * - OH_NN_ACCELERATOR: machine learning dedicated accelerator. - * - OH_NN_OTHERS: other hardware types. \n - * - * @param deviceID Device ID. - * @param deviceType Pointer to the {@link OH_NN_DeviceType} instance. The device type information is returned. - * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, - * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. - * @since 9 - * @version 1.0 - */ -OH_NN_ReturnCode OH_NNDevice_GetType(size_t deviceID, OH_NN_DeviceType *deviceType); - #ifdef __cplusplus } #endif // __cplusplus diff --git a/ai/neural_network_runtime/neural_network_runtime_compat.h b/ai/neural_network_runtime/neural_network_runtime_compat.h new file mode 100644 index 0000000000000000000000000000000000000000..0e73606773ecf882f263db0547b74ca3a15821d5 --- /dev/null +++ b/ai/neural_network_runtime/neural_network_runtime_compat.h @@ -0,0 +1,294 @@ +/* + * Copyright (c) 2022-2023 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup NeuralNeworkRuntime + * @{ + * + * @brief Provides APIs of Neural Network Runtime for accelerating the model inference. + * + * @Syscap SystemCapability.Ai.NeuralNetworkRuntime + * @since 9 + * @version 2.0 + */ + +/** + * @file neural_network_runtime_compat.h + * + * @brief The APIs defined in this document are all compatible APIs of the previous version, which will be deprecated after five versions. + * It is recommended to use the new APIs defined by neural_network_core.h and neural_network_runtime.h. + * + * Note: Currently, the APIs of Neural Network Runtime do not support multi-thread calling. \n + * + * include "neural_network_runtime/neural_network_runtime_compat.h" + * @library libneural_network_runtime.so + * @since 11 + * @version 1.0 + */ + +#ifndef NEURAL_NETWORK_RUNTIME_COMPAT_H +#define NEURAL_NETWORK_RUNTIME_COMPAT_H + +#include "neural_network_runtime_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Adds a tensor to a model instance. + * + * The data node and operator parameters in the Neural Network Runtime model are composed of tensors of the model. + * This method is used to add tensors to a model instance based on the tensor parameter. + * The sequence of adding tensors is specified by the index value recorded in the model. The {@link OH_NNModel_SetTensorData}, {@link OH_NNModel_AddOperation}, + * and {@link OH_NNModel_SpecifyInputsAndOutputs} methods specifies tensors based on the index value. \n + * + * Neural Network Runtime supports inputs and outputs of the dynamic shape. When adding a data node with a dynamic shape, + * you need to set the dimensions that support dynamic changes in tensor.dimensions to -1. + * For example, if tensor.dimensions of a four-dimensional tensor is set to [1, -1, 2, 2], the second dimension supports dynamic changes. \n + * + * @param model Pointer to the {@link OH_NNModel} instance. + * @param tensor Pointer to the {@link OH_NN_Tensor} tensor. The tensor specifies the attributes of the tensor added to the model instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. + * If the operation fails, an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNModel_AddTensorToModel} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNModel_AddTensor(OH_NNModel *model, const OH_NN_Tensor *tensor); + +/** + * @brief Sets the single input data for a model. + * + * This method copies the data whose length is specified by length (in bytes) in dataBuffer to the shared memory + * of the underlying device. inputIndex specifies the input to be set and tensor sets information such as the input shape, + * type, and quantization parameters. \n + * + * Neural Network Runtime supports models with dynamical shape input. For fixed shape input and dynamic shape input scenarios, + * this method uses different processing policies. \n + * + * - Fixed shape input: The attributes of tensor must be the same as those of the tensor added by calling + * {@link OH_NNModel_AddTensor} in the composition phase. + * - Dynamic shape input: In the composition phase, because the shape is not fixed, each value in tensor.dimensions must be greater than + * 0 in the method calls to determine the shape input in the calculation phase. When setting the shape, you can modify + * only the dimension whose value is -1. Assume that [-1, 224, 224, 3] is input as the the dimension of A in the composition phase. + * When this method is called, only the size of the first dimension can be modified, for example, to [3, 224, 224, 3]. + * If other dimensions are adjusted, {@link OH_NN_INVALID_PARAMETER} is returned. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * In input settings, the index value for the three inputs is {0, 1, 2}. \n + * + * @param tensor Sets the tensor corresponding to the input data. + * @param dataBuffer Pointer to the input data. + * @param length Length of the data buffer, in bytes. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNExecutor_RunSync} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetInput(OH_NNExecutor *executor, + uint32_t inputIndex, + const OH_NN_Tensor *tensor, + const void *dataBuffer, + size_t length); + +/** + * @brief Sets the buffer for a single output of a model. + * + * This method binds the buffer to which dataBuffer points to the output specified by outputIndex. + * The length of the buffer is specified by length. \n + * + * After {@link OH_NNExecutor_Run} is called to complete a single model inference, Neural Network Runtime compares + * the length of the buffer to which dataBuffer points with the length of the output data and returns different results + * based on the actual situation. \n + * + * - If the buffer length is greater than or equal to the data length, the inference result is copied to the buffer and + * {@link OH_NN_SUCCESS} is returned. You can read the inference result from dataBuffer. + * - If the buffer length is smaller than the data length, {@link OH_NNExecutor_Run} returns {@link OH_NN_INVALID_PARAMETER} + * and generates a log indicating that the buffer is too small. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} + * is called. In output buffer settings, the index value for the three outputs is {0, 1, 2}. + * @param dataBuffer Pointer to the output data. + * @param length Length of the data buffer, in bytes. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNExecutor_RunSync} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetOutput(OH_NNExecutor *executor, + uint32_t outputIndex, + void *dataBuffer, + size_t length); + +/** + * @brief Performs inference. + * + * Performs end-to-end inference and computing of the model on the device associated with the executor. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNExecutor_RunSync} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_Run(OH_NNExecutor *executor); + +/** + * @brief Allocates shared memory to a single input on a device. + * + * Neural Network Runtime provides a method for proactively allocating shared memory on a device. By specifying the executor and input index value, + * this method allocates shared memory whose size is specified by length on the device associated with a single input and returns the + * operation result through the {@link OH_NN_Memory} instance. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * In the memory input application, the index value for the three inputs is {0, 1, 2}. + * @param length Memory size to be applied for, in bytes. + * @return Pointer to a {@link OH_NN_Memory} instance, or NULL if it fails to create. + * @deprecated since 11 + * @useinstead {@link OH_NNTensor_CreateWithSize} + * @since 9 + * @version 1.0 + */ +OH_NN_Memory *OH_NNExecutor_AllocateInputMemory(OH_NNExecutor *executor, uint32_t inputIndex, size_t length); + +/** + * @brief Allocates shared memory to a single output on a device. + * + * Neural Network Runtime provides a method for proactively allocating shared memory on a device. By specifying the executor and + * output index value, this method allocates shared memory whose size is specified by length on the device associated with + * a single output and returns the operation result through the {@link OH_NN_Memory} instance. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * In output memory application, the index value for the three outputs is {0, 1, 2}. + * @param length Memory size to be applied for, in bytes. + * @return Pointer to a {@link OH_NN_Memory} instance, or NULL if it fails to create. + * @deprecated since 11 + * @useinstead {@link OH_NNTensor_CreateWithSize} + * @since 9 + * @version 1.0 + */ +OH_NN_Memory *OH_NNExecutor_AllocateOutputMemory(OH_NNExecutor *executor, uint32_t outputIndex, size_t length); + +/** + * @brief Releases the input memory to which the {@link OH_NN_Memory} instance points. + * + * This method needs to be called to release the memory instance created by calling {@link OH_NNExecutor_AllocateInputMemory}. + * Otherwise, memory leak will occur. + * The mapping between inputIndex and memory must be the same as that in memory instance creation. \n + * + * If memory or *memory is a null pointer, this method only prints warning logs and does not execute the release logic. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * In memory input release, the index value for the three inputs is {0, 1, 2}. + * @param memory Double pointer to the {@link OH_NN_Memory} instance. After shared memory is destroyed, this method sets *memory to a null pointer. + * @deprecated since 11 + * @useinstead {@link OH_NNTensor_Destroy} + * @since 9 + * @version 1.0 + */ +void OH_NNExecutor_DestroyInputMemory(OH_NNExecutor *executor, uint32_t inputIndex, OH_NN_Memory **memory); + +/** + * @brief Releases the output memory to which the {@link OH_NN_Memory} instance points. + * + * This method needs to be called to release the memory instance created by calling {@link OH_NNExecutor_AllocateOutputMemory}. Otherwise, memory leak will occur. + * The mapping between outputIndex and memory must be the same as that in memory instance creation. \n + * + * If memory or *memory is a null pointer, this method only prints warning logs and does not execute the release logic. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * In output memory release, the index value for the three outputs is {0, 1, 2}. + * @param memory Double pointer to the {@link OH_NN_Memory} instance. After shared memory is destroyed, this method sets *memory to a null pointer. + * @deprecated since 11 + * @useinstead {@link OH_NNTensor_Destroy} + * @since 9 + * @version 1.0 + */ +void OH_NNExecutor_DestroyOutputMemory(OH_NNExecutor *executor, uint32_t outputIndex, OH_NN_Memory **memory); + +/** + * @brief Specifies the hardware shared memory pointed to by the {@link OH_NN_Memory} instance as the shared memory used by a single input. + * + * In scenarios where memory needs to be managed by yourself, this method binds the execution input to the {@link OH_NN_Memory} memory instance. + * During computing, the underlying device reads the input data from the shared memory pointed to by the memory instance. + * By using this method, concurrent execution of input setting, computing, and read can be implemented to improve inference efficiency of a data flow. \n + * + * @param executor Pointer to the {@link OH_NNExecutor} instance. + * @param inputIndex Input index value, which is in the same sequence of the data input when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of inputIndices is {1, 5, 9} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * When the input shared memory is specified, the index value for the three inputs is {0, 1, 2}. + * @param tensor Pointer to {@link OH_NN_Tensor}, used to set the tensor corresponding to a single input. + * @param memory Pointer to {@link OH_NN_Memory}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNExecutor_RunSync} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetInputWithMemory(OH_NNExecutor *executor, + uint32_t inputIndex, + const OH_NN_Tensor *tensor, + const OH_NN_Memory *memory); + +/** + * @brief Specifies the hardware shared memory pointed to by the {@link OH_NN_Memory} instance as the shared memory used by a single output. + * + * In scenarios where memory needs to be managed by yourself, this method binds the execution output to the {@link OH_NN_Memory} memory instance. + * When computing is performed, the underlying hardware directly writes the computing result to the shared memory to which the memory instance points. + * By using this method, concurrent execution of input setting, computing, and read can be implemented to improve inference efficiency of a data flow. \n + * + * @param executor Executor. + * @param outputIndex Output Index value, which is in the same sequence of the data output when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * Assume that the value of outputIndices is {4, 6, 8} when {@link OH_NNModel_SpecifyInputsAndOutputs} is called. + * When output shared memory is specified, the index value for the three outputs is {0, 1, 2}. + * @param memory Pointer to {@link OH_NN_Memory}. + * @return Execution result of the function. If the operation is successful, OH_NN_SUCCESS is returned. If the operation fails, + * an error code is returned. For details about the error codes, see {@link OH_NN_ReturnCode}. + * @deprecated since 11 + * @useinstead {@link OH_NNExecutor_RunSync} + * @since 9 + * @version 1.0 + */ +OH_NN_ReturnCode OH_NNExecutor_SetOutputWithMemory(OH_NNExecutor *executor, + uint32_t outputIndex, + const OH_NN_Memory *memory); + +#ifdef __cplusplus +} +#endif // __cplusplus + +/** @} */ +#endif // NEURAL_NETWORK_RUNTIME_COMPAT_H diff --git a/ai/neural_network_runtime/neural_network_runtime_type.h b/ai/neural_network_runtime/neural_network_runtime_type.h index 00aefb6562d55ee218615a0a923c6e90423bc633..0049af247ed926ba41a6b9f403f0bec1b017b615 100644 --- a/ai/neural_network_runtime/neural_network_runtime_type.h +++ b/ai/neural_network_runtime/neural_network_runtime_type.h @@ -21,17 +21,18 @@ * * @Syscap SystemCapability.Ai.NeuralNetworkRuntime * @since 9 - * @version 1.0 + * @version 2.0 */ /** * @file neural_network_runtime_type.h * - * @brief Defines the structure and enumeration for Neural Network Runtime. + * @brief Defines the structure and enumeration. * + * include "neural_network_runtime/neural_network_runtime_type.h" * @library libneural_network_runtime.so * @since 9 - * @version 1.0 + * @version 2.0 */ #ifndef NEURAL_NETWORK_RUNTIME_TYPE_H @@ -45,7 +46,7 @@ extern "C" { #endif /** - * @brief Defines the handles of models for Neural Network Runtime. + * @brief Defines the handles of models. * * @since 9 * @version 1.0 @@ -53,7 +54,7 @@ extern "C" { typedef struct OH_NNModel OH_NNModel; /** - * @brief Defines the compiler handle for Neural Network Runtime. + * @brief Defines the compilation handle. * * @since 9 * @version 1.0 @@ -61,13 +62,37 @@ typedef struct OH_NNModel OH_NNModel; typedef struct OH_NNCompilation OH_NNCompilation; /** - * @brief Defines the executor handle for Neural Network Runtime. + * @brief Defines the executor handle. * * @since 9 * @version 1.0 */ typedef struct OH_NNExecutor OH_NNExecutor; +/** + * @brief Defines the quantization parameter handle. + * + * @since 11 + * @version 1.0 + */ +typedef struct NN_QuantParam NN_QuantParam; + +/** + * @brief Defines the tensor descriptor handle. + * + * @since 11 + * @version 1.0 + */ +typedef struct NN_TensorDesc NN_TensorDesc; + +/** + * @brief Defines the tensor handle. + * + * @since 11 + * @version 1.0 + */ +typedef struct NN_Tensor NN_Tensor; + /** * @brief Defines the hardware performance mode. * @@ -105,10 +130,10 @@ typedef enum { } OH_NN_Priority; /** - * @brief Defines error codes for Neural Network Runtime. + * @brief Defines error codes. * * @since 9 - * @version 1.0 + * @version 2.0 */ typedef enum { /** The operation is successful. */ @@ -125,14 +150,69 @@ typedef enum { OH_NN_NULL_PTR = 5, /** Invalid file. */ OH_NN_INVALID_FILE = 6, - /** A hardware error occurs, for example, HDL service crash. */ + /** A hardware error occurs, for example, HDL service crash. + * @deprecated since 11 + * @useinstead {@link OH_NN_UNAVAILABLE_DEVICE} + */ OH_NN_UNAVALIDABLE_DEVICE = 7, /** Invalid path. */ - OH_NN_INVALID_PATH = 8 + OH_NN_INVALID_PATH = 8, + /** Timeout. + * @since 11 + */ + OH_NN_TIMEOUT = 9, + /** Unsupported. + * @since 11 + */ + OH_NN_UNSUPPORTED = 10, + /** Connection Exception. + * @since 11 + */ + OH_NN_CONNECTION_EXCEPTION = 11, + /** Save cache exception. + * @since 11 + */ + OH_NN_SAVE_CACHE_EXCEPTION = 12, + /** Dynamic shape. + * @since 11 + */ + OH_NN_DYNAMIC_SHAPE = 13, + /** A hardware error occurs, for example, HDL service crash. + * @since 11 + */ + OH_NN_UNAVAILABLE_DEVICE = 14 } OH_NN_ReturnCode; + +/** + * @brief Defines the callback function handle for the post-process when the asynchronous execution has been done. + * + * Use the first argument userData to identify the asynchronous execution you want to get. + * It is the argument userData passed to {@link OH_NNExecutor_RunAsync}. \n + * Use the second argument errCode of type {@link OH_NN_ReturnCode} to get the error code returned by the asynchronous execution. \n + * + * @param userData Asynchronous execution identifier, which is the argument userData passed to {@link OH_NNExecutor_RunAsync}. + * @param errCode Error code {@link OH_NN_ReturnCode} returned by the asynchronous execution. + * @param outputTensor An array of output tensors {@link NN_Tensor} of the model, which is the same as the argument outputTensor passed to {@link OH_NNExecutor_RunAsync} + * @param outputCount Output tensor count, which is the same as the argument outputCount passed to {@link OH_NNExecutor_RunAsync} + * @since 11 + * @version 1.0 + */ +typedef void (*NN_OnRunDone)(void*, OH_NN_ReturnCode, void* [], int32_t); + +/** + * @brief Defines the callback function handle for the post-process when the device driver service is dead during asynchronous execution. + * + * You should recompile the model if this callback function is called. \n + * + * @param userData Asynchronous execution identifier, which is the argument userData passed to {@link OH_NNExecutor_RunAsync}. + * @since 11 + * @version 1.0 + */ +typedef void (*NN_OnServiceDied)(void*); + /** - * @brief Defines activation function types in the fusion operator for Neural Network Runtime. + * @brief Defines activation function types in the fusion operator. * * @since 9 * @version 1.0 @@ -150,7 +230,7 @@ typedef enum : int8_t { * @brief Defines the layout type of tensor data. * * @since 9 - * @version 1.0 + * @version 2.0 */ typedef enum { /** The tensor does not have a specific layout type (such as scalar or vector). */ @@ -158,11 +238,15 @@ typedef enum { /** The tensor arranges data in NCHW format.*/ OH_NN_FORMAT_NCHW = 1, /** The tensor arranges data in NHWC format.*/ - OH_NN_FORMAT_NHWC = 2 + OH_NN_FORMAT_NHWC = 2, + /** The tensor arranges data in ND format. + * @since 11 + */ + OH_NN_FORMAT_ND = 3 } OH_NN_Format; /** - * @brief Defines device types supported by Neural Network Runtime. + * @brief Defines device types. * * @since 9 * @version 1.0 @@ -179,7 +263,7 @@ typedef enum { } OH_NN_DeviceType; /** - * @brief Defines tensor data types supported by Neural Network Runtime. + * @brief Defines tensor data types. * * @since 9 * @version 1.0 @@ -215,7 +299,7 @@ typedef enum { /** - * @brief Defines operator types supported by Neural Network Runtime. + * @brief Defines operator types. * * @since 9 * @version 1.0 @@ -1720,6 +1804,8 @@ typedef struct OH_NN_UInt32Array { \end{cases} \f] * + * @deprecated since 11 + * @useinstead {@link NN_QuantParam} * @since 9 * @version 1.0 */ @@ -1744,6 +1830,8 @@ typedef struct OH_NN_QuantParam { * It is usually used to construct data nodes and operator parameters in a model graph. When constructing a tensor, * you need to specify the data type, number of dimensions, dimension information, and quantization information. * + * @deprecated since 11 + * @useinstead {@link NN_TensorDesc} * @since 9 * @version 1.0 */ @@ -1766,6 +1854,8 @@ typedef struct OH_NN_Tensor { /** * @brief Defines the memory structure. * + * @deprecated since 11 + * @useinstead {@link NN_Tensor} * @since 9 * @version 1.0 */