1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup NNRt
18 * @{
19 *
20 * @brief Provides a unified interface for AI chip drivers to access OpenHarmony.\n
21 * Neural Network Runtime (NNRt) is a cross-chip inference computing runtime environment oriented to the AI field.
22 *
23 * @since 3.2
24 * @version 2.1
25 */
26
27/**
28 * @file ModelTypes.idl
29 *
30 * @brief Defines AI model structures.
31 *
32 * In {@link PrepareModel}, the AI model is parsed and converted into the structure for inference.\n
33 * Then, model inference is performed in {@link Run}. The process is as follows.
34 * - 1. Write the functions for each operator in the {@link NodeAttrTypes.idl} file and associate\n
35 * each function with a {@link NodeType}.
36 * - 2. The <b>subGraph</b> parameter of {@link Model} is traversed to obtain the operator nodes\n
37 * contained in the subgraph, the input and output tensors of the operator, and the input and output tensors\n
38 * of the entire {@link Model} from <b>nodeIndecies</b> of the subgraph.
39 * - 3. The operator functions are located based on the <b>nodeType</b> parameter of {@link Node} to\n
40 * build the model structure for runtime.
41 * - 4. When the tensors input by the user are passed to the model, the NNRt module performs model inference\n
42 * and the outputs the model inference result.
43 *
44 * @since 3.2
45 * @version 2.1
46 */
47
48/**
49 * @brief Defines the package path of the NNRt module.
50 *
51 * @since 3.2
52 * @version 2.1
53 */
54package ohos.hdi.nnrt.v2_1;
55
56import ohos.hdi.nnrt.v2_1.NnrtTypes;
57
58/**
59 * @brief Defines the tensor structure.
60 *
61 * @since 3.2
62 * @version 2.1
63 */
64struct Tensor {
65    /** Tensor name. */
66    String name;
67    /** Tensor data type. For details, see {@link DataType}. */
68    enum DataType dataType;
69    /** Tensor dimensions. */
70    int[] dims;
71    /** Format of the tensor data. For details, see {@link Format}. */
72    enum Format format;
73    /** Structure used for passing the tensor data during process communication.\n
74      * For details, see {@link SharedBuffer}.
75      */
76    struct SharedBuffer data;
77    /**
78     * Array of quantization parameters of the tensor. For details, see {@link QuantParam}.
79     * If the length is <b>1</b>, all axes share one quantization parameter.
80     * If the length is not <b>1</b>, each quantization parameter in the array corresponds to an axis.
81     */
82    struct QuantParam[] quantParams;
83};
84
85/**
86 * @brief Defines the operator node structure.
87 *
88 * <b>nodeAttr</b> is a segment of serialized data. Specific parameters can be obtained only by using
89 * the deserialization interface of OpenHarmony HDI.
90 *      The process is as follows:
91 *      - Define the operator parameter structure <b>OP op{}</b>, where <b>OP</b> can be replaced with
92 *      the operator parameter structure defined in {@link NodeAttrTypes.idl} and <b>op</b> is a variable name.
93 *      - Declare `OHOS::MessageParcel data;`, that is, the <b>MessageParcle</b> object used to store deserialized data.
94 *      - Use <b>data.WriteBuffer (nodeAttr.data(),nodeAttr.size());</b> to write <b>nodeAttr</b> to <b>data</b>.
95 *      - Use <b>(void)OPBlockUnmarshalling(data, op);</b> to deserialize <b>data</b> to the <b>op</b> structure. <br>
96 *      Then, you can view the parameter values of the operator in <b>op</b>.
97 *
98 *      Example:
99 *      If <b>nodeType</b> of an operator is <b>NODE_TYPE_FULL_CONNECTION</b>, the corresponding operator
100 *      parameter structure is {@link FullConnection}.
101 *      The operator has four parameters: <b>hasBias</b>, <b>useAxis</b>, <b>axis</b>, and <b>activationType</b>.<br>
102 *      The invoking process is as follows: <br>
103 *      FullConnection full_connection{};<br>
104 *      OHOS::MessageParcel data;<br>
105 *      data.WriteBuffer(nodeAttr.data(),nodeAttr.size());<br>
106 *      (void)FullConnectionBlockUnmarshalling(data, full_connection);<br>
107 *      Up to now, the four parameters are written into <b>full_connection</b>.
108 *
109 * @since 3.2
110 * @version 2.1
111 */
112struct Node {
113    /** Operator node name. */
114    String name;
115    /** Operator node type. For details, see {@link NodeType}. */
116    enum NodeType nodeType;
117    /**
118     * Array of the serialized data corresponding to the operator node parameters.
119     */
120    byte[] nodeAttr;
121    /** Subscript of the input node of the operator node. */
122    unsigned int[] inputIndex;
123    /** Subscript of the output node of the operator node. */
124    unsigned int[] outputIndex;
125    /** Quantization parameter of the operator node. For details, see {@link QuantType}. */
126    enum QuantType quantType;
127};
128
129/**
130 * @brief Defines the subgraph structure.
131 *
132 * @since 3.2
133 * @version 2.1
134 */
135struct SubGraph {
136    /** Subgraph name. */
137    String name;
138    /** Indices of the input subgraphs in <b>subGraph</b> of {@link Model}. */
139    unsigned int[] inputIndices;
140    /** Indices of the output subgraphs in <b>subGraph</b> of {@link Model}. */
141    unsigned int[] outputIndices;
142    /** Indices of the operator nodes related to the subgraph in the <b>nodes</b> array of {@link Model}. */
143    unsigned int[] nodeIndices;
144};
145
146/**
147 * @brief Defines the model structure.
148 *
149 * This structure stores all information required for model inference. Subgraph 0 of each model is the main subgraph.\n
150 * Generally, a model has only one <b>subGraph</b>.
151 *
152 * @since 3.2
153 * @version 2.1
154 */
155struct Model {
156    /** Model name. */
157    String name;
158    /**
159     * Index of the input tensor of the model in <b>allTensors</b>.
160     */
161    unsigned int[] inputIndex;
162    /**
163     * Index of the output tensor of the model in <b>allTensors</b>.
164     */
165    unsigned int[] outputIndex;
166    /**
167     * Array of all operator nodes in the model. For details, see {@link Node}.
168     */
169    struct Node[] nodes;
170    /**
171     * Array of all tensors in the model. The array contains input tensors, output tensors, and constant tensors.\n
172     * For details, see {@link Tensor}.
173     */
174    struct Tensor[] allTensors;
175    /**
176     * Array of all subgraphs in the model. For details, see {@link SubGraph}.
177     */
178    struct SubGraph[] subGraph;
179};
180
181/** @} */
182