/*
 * Copyright (c) 2022 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 NNRt
 * @{
 *
 * @brief Provides a unified interface for AI chip drivers to access OpenHarmony. 
 * Neural Network Runtime (NNRt) is a cross-chip inference computing runtime environment oriented to the AI field.
 * It serves as a bridge between the upper-layer AI inference framework and the underlying acceleration chip to implement cross-chip inference computing of AI models.
 * @since 3.2
 * @version 1.0
 */

/**
 * @file INnrtDevice.idl
 *
 * @brief Defines methods related to chip devices.
 *
 * You can use the methods to query chip device information and build AI models.
 *
 * @since 3.2
 * @version 1.0
 */

/**
 * @brief Defines the package path of the NNRt module.
 *
 * @since 3.2
 * @version 1.0
 */
package ohos.hdi.nnrt.v1_0;

import ohos.hdi.nnrt.v1_0.NnrtTypes;
import ohos.hdi.nnrt.v1_0.ModelTypes;
import ohos.hdi.nnrt.v1_0.IPreparedModel;

/**
 * @brief Provides methods for device management and model building.
 *
 * When multiple devices are registered, ensure that the combination of the device name and vendor name is globally unique.
 *
 * @since 3.2
 * @version 1.0
 */
interface INnrtDevice {
    /**
     * @brief Obtains the device name.
     *
     * @param name Indicates the device name obtained.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    GetDeviceName([out] String name);

    /**
     * @brief Obtains the device vendor name.
     *
     * @param name Indicates the device vendor name obtained.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    GetVendorName([out] String name);

    /**
     * @brief Obtains the device type.
     *
     * @param deviceType Indicates the device type obtained. For details, see {@link DeviceType}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    GetDeviceType([out] enum DeviceType deviceType);

    /**
      * @brief Obtains the device status.
     *
     * @param deviceType Indicates the device status obtained. For details, see {@link DeviceStatus}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    GetDeviceStatus([out] enum DeviceStatus status);

    /**
     * @brief Obtains the device's support for the operators of the specified AI model.
     *
     * @param model Indicates the AI model. For details, see {@link Model}.
     * @param ops Indicates the operators supported and not supported by the device. The operators are listed in the same sequence as they listed in the API model.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    GetSupportedOperation([in] struct Model model, [out] boolean[] ops);

    /**
     * @brief Checks whether the device supports the Float32 model with the Float16 precision.
     *
     * @param isSupported Indicates whether the Float16 precision is supported.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    IsFloat16PrecisionSupported([out] boolean isSupported);

    /**
     * @brief Checks whether the device supports performance preference settings. For details about the performance preference, see {@link PerformanceMode}.
     *
     * @param isSupported Indicates whether the device supports performance preference settings.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    IsPerformanceModeSupported([out] boolean isSupported);

    /**
     * @brief Checks whether the device supports task priority settings. For details about the priority, see {@link Priority}.
     *
     * @param isSupported Indicates whether the device supports task priority settings.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    IsPrioritySupported([out] boolean isSupported);

    /**
     * @brief Checks whether the device supports dynamic input, which allows a model of different shapes to be used for different operations.
     *
     * If dynamic input is supported, <b>-1</b> is added in the shape of the input tensor.
     *
     * @param isSupported Indicates whether dynamic input is supported.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    IsDynamicInputSupported([out] boolean isSupported);

    /**
     * @brief Builds a model.
     *
     * If the AI model supports dynamic input, at least one dimension of the input tensor contains <b>-1</b>.
     *
     * @param model indicates the module to build. For details, see {@link Model}.
     * @param config Indicates the module configuration. For details, see {@link ModelConfig}.
     * @param preparedModel Indicates the model object built. For details, see {@link IPreparedModel}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    PrepareModel([in] struct Model model, [in] struct ModelConfig config, [out] IPreparedModel preparedModel);

    /**
     * @brief Checks whether the device supports caching of the AI models built.
     *
     * If yes, <b>PrepareModelFromModelCache()</b> and <b>ExportModelCache()</b> need to be implemented.
     *
     * @param isSupported Indicates whether the device supports caching of the AI models built.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    IsModelCacheSupported([out] boolean isSupported);

    /**
     * @brief Loads an AI model from the cache. The AI model is exported by using <b>ExportModelCache()</b>.
     *
     * @param modelCache Indicates an array of the model files, which are in the same sequence as they exported. For details, see {@link SharedBuffer}.
     * @param config Indicates the configuration for loading the model. For details, see {@link ModelConfig}.
     * @param preparedModel Indicates the model object obtained. For details, see {@link IPreparedModel}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    PrepareModelFromModelCache([in] struct SharedBuffer[] modelCache, [in] struct ModelConfig config,
                               [out] IPreparedModel preparedModel);

    /**
     * @brief Allocates the shared memory for the device. The shared memory allows quick access to the input and output data for AI inference.
     *
     * @param length Indicates the shared memory to allocate, in bytes.
     * @param buffer Indicates the information about the shared memory allocated, including the file descriptor and size of the shared memory. For details, see {@link SharedBuffer}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    AllocateBuffer([in] unsigned int length, [out] struct SharedBuffer buffer);

    /**
      * @brief Releases the shared memory.
     *
     * @param buffer Indicates the shared memory to release. For details, see {@link SharedBuffer}.
     *
     * @return Returns <b>0</b> if the operation is successful.
     * @return Returns a negative number if the operation fails.
     */
    ReleaseBuffer([in] struct SharedBuffer buffer);
}

/** @} */