1/*
2 * Copyright (c) 2022 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. 
21 * Neural Network Runtime (NNRt) is a cross-chip inference computing runtime environment oriented to the AI field.
22 * 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.
23 * @since 3.2
24 * @version 1.0
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. Then, model inference is performed in {@link Run}. The process is as follows.
33 * - 1. Write the functions for each operator in the {@link NodeAttrTypes.idl} file and associate each function with a {@link NodeType}.
34 * - 2. The <b>subGraph</b> parameter of {@link Model} is traversed to obtain the operator nodes contained in the subgraph, the input and output tensors of the operator, and the input and output tensors of the entire {@link Model} from <b>nodeIndecies</b> of the subgraph.
35 * - 3. The operator functions are located based on the <b>nodeType</b> parameter of {@link Node} to build the model structure for runtime.
36 * - 4. When the tensors input by the user are passed to the model, model inference is performed. The model inference result is output.
37 *
38 * @since 3.2
39 * @version 1.0
40 */
41
42/**
43 * @brief Defines the package path of the NNRt module.
44 *
45 * @since 3.2
46 * @version 1.0
47 */
48package ohos.hdi.nnrt.v1_0;
49
50import ohos.hdi.nnrt.v1_0.NnrtTypes;
51
52/**
53 * @brief Defines the tensor structure.
54 *
55 * @since 3.2
56 * @version 1.0
57 */
58struct Tensor {
59    /** Tensor name. */
60    String name;
61    /** Tensor data type. For details, see {@link DataType}. */
62    enum DataType dataType;
63    /** Tensor dimensions. */
64    int[] dims;
65    /** Format of the tensor data. For details, see {@link Format}. */
66    enum Format format;
67    /** Structure used for passing the tensor data during process communication. For details, see {@link SharedBuffer}. */
68    struct SharedBuffer data;
69    /**
70     * Array of quantization parameters of the tensor. For details, see {@link QuantParam}.
71     * If the length is <b>1</b>, all axes share one quantization parameter.
72     * If the length is not <b>1</b>, each quantization parameter in the array corresponds to an axis.
73     */
74    struct QuantParam[] quantParams;
75};
76
77/**
78 * @brief Defines the operator node structure.
79 * 
80 * <b>nodeAttr</b> is a segment of serialized data. Specific parameters can be obtained only by using the deserialization interface of OpenHarmony HDI.
81 The process is as follows:
82 * - Define the operator parameter structure <b>OP op{}</b>, where <b>OP</b> can be replaced with the operator parameter structure defined in {@link NodeAttrTypes.idl} and <b>op</b> is a variable name.
83 * - Declare `OHOS::MessageParcel data;`, the <b>MessageParcle</b> object, which is used to store deserialized data. 
84 * - Use <b>data.WriteBuffer (nodeAttr.data(),nodeAttr.size());</b> to write <b>nodeAttr</b> to <b>data</b>.
85 * - Use <b>(void)OPBlockUnmarshalling(data, op);</b> to deserialize <b>data</b> to the <b>op</b> structure. <br>
86 * Then, you can view the parameter values of the operator in <b>op</b>.
87 *
88 * Example:
89 * If <b>nodeType</b> of an operator is <b>NODE_TYPE_FULL_CONNECTION</b>, the corresponding operator parameter structure is {@link FullConnection}.
90 * The operator has four parameters: <b>hasBias</b>, <b>useAxis</b>, <b>axis</b>, and <b>activationType</b>. <br>
91 * The invoking process is as follows: <br>
92 *      FullConnection full_connection{};<br>
93 *      OHOS::MessageParcel data;<br>
94 *      data.WriteBuffer(nodeAttr.data(),nodeAttr.size());<br>
95 *      (void)FullConnectionBlockUnmarshalling(data, full_connection);<br>
96 * The four parameters are written into <b>full_connection</b>.
97 * 
98 * @since 3.2
99 * @version 1.0
100 */
101struct Node {
102    /** Operator node name. */
103    String name;
104    /** Operator node type. For details, see {@link NodeType}. */
105    enum NodeType nodeType;
106    /**
107     * Array of the serialized data corresponding to the operator node parameters.
108     */
109    byte[] nodeAttr;
110    /** Subscript of the input node of the operator node. */
111    unsigned int[] inputIndex;
112    /** Subscript of the output node of the operator node. */
113    unsigned int[] outputIndex;
114    /** Quantization parameter of the operator node. For details, see {@link QuantType}. */
115    enum QuantType quantType;
116};
117
118/**
119 * @brief Defines the subgraph structure.
120 *
121 * @since 3.2
122 * @version 1.0
123 */
124struct SubGraph {
125    /** Subgraph name. */
126    String name;
127    /** Indices of the input subgraphs in <b>subGraph</b> of {@link Model}. */
128    unsigned int[] inputIndices;
129    /** Indices of the output subgraphs in <b>subGraph</b> of {@link Model}. */
130    unsigned int[] outputIndices;
131    /** Indices of the operator nodes related to the subgraph in the <b>nodes</b> array of {@link Model}. */
132    unsigned int[] nodeIndices;
133};
134
135/**
136 * @brief Defines the model structure.
137 * 
138 * This structure stores all information required for model inference. Subgraph 0 of each model is the main subgraph. Generally, a model has only one <b>subGraph</b>.
139 * 
140 * @since 3.2
141 * @version 1.0
142 */
143struct Model {
144    /** Model name. */
145    String name;
146    /** 
147     * Index of the input tensor of the model in <b>allTensors</b>.
148     */
149    unsigned int[] inputIndex;
150    /** 
151     * Index of the output tensor of the model in <b>allTensors</b>.
152     */
153    unsigned int[] outputIndex;
154    /** 
155     * Array of all operator nodes in the model. For details, see {@link Node}.
156     */
157    struct Node[] nodes;
158    /** 
159     * Array of all tensors in the model. The array contains input tensors, output tensors, and constant tensors. For details, see {@link Tensor}.
160     */
161    struct Tensor[] allTensors;
162    /** 
163     * Array of all subgraphs in the model. For details, see {@link SubGraph}.
164     */
165    struct SubGraph[] subGraph;
166};
167
168/** @} */
169