Merge "Fix implicit-fallthrough warnings."
[android/platform-hardware-interfaces.git] / neuralnetworks / 1.2 / types.hal
1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
17 package android.hardware.neuralnetworks@1.2;
19 import @1.0::DataLocation;
20 import @1.0::OperandLifeTime;
21 import @1.0::OperandType;
22 import @1.0::PerformanceInfo;
23 import @1.1::OperationType;
25 enum OperandType : @1.0::OperandType {
26     /**
27      * An 8 bit boolean scalar value.
28      *
29      * Values of this operand type are either true or false. A zero value
30      * represents false; any other value represents true.
31      */
32     BOOL = 6,
33     /**
34      * A tensor of 16 bit signed integers that represent real numbers.
35      *
36      * Attached to this tensor are two numbers that are used to convert the 16
37      * bit integer to the real value and vice versa. These two numbers are:
38      * - scale: a 32 bit floating point value greater than zero.
39      * - zeroPoint: a 32 bit integer, in range [-32768, 32767].
40      *
41      * The formula is:
42      * realValue = (integerValue - zeroPoint) * scale.
43      */
44     TENSOR_QUANT16_ASYMM = 7,
45     /** A tensor of 16 bit floating point values. */
46     TENSOR_FLOAT16 = 8,
47 };
49 /**
50  * Operation types.
51  *
52  * The type of an operation in a model.
53  */
54 enum OperationType : @1.1::OperationType {
55     // TODO(b/116445845): Sync docs when all ops are implemented.
56     ARGMAX = 38,
57     ARGMIN = 39,
58     PAD_V2 = 40,
59     AXIS_ALIGNED_BBOX_TRANSFORM = 41,
60     BIDIRECTIONAL_SEQUENCE_LSTM = 42,
61     BIDIRECTIONAL_SEQUENCE_RNN = 43,
62     BOX_WITH_NMS_LIMIT = 44,
63     CAST = 45,
64     CHANNEL_SHUFFLE = 46,
65     DETECTION_OUTPUT = 47,
66     EMBEDDING_LOOKUP_SPARSE = 48,
67     EXP = 49,
68     EXPAND_DIMS = 50,
69     GATHER = 51,
70     GENERATE_PROPOSALS = 52,
71     GREATER = 53,
72     GREATER_EQUAL = 54,
73     GROUPED_CONV_2D = 55,
74     HEATMAP_MAX_KEYPOINT = 56,
75     LESS = 57,
76     LESS_EQUAL = 58,
77     LOG = 59,
78     LOGICAL_AND = 60,
79     LOGICAL_NOT = 61,
80     LOGICAL_OR = 62,
81     LOG_SOFTMAX = 63,
82     MAXIMUM = 64,
83     MINIMUM = 65,
84     NEG = 66,
85     POW = 67,
86     PRELU = 68,
87     PRIOR_BOX = 69,
88     QUANTIZE = 70,
89     QUANTIZED_16BIT_LSTM = 71,
90     RANDOM_MULTINOMIAL = 72,
91     REDUCE = 73,
92     ROI_ALIGN = 74,
93     RSQRT = 75,
94     SELECT = 76,
95     SIN = 77,
96     SLICE = 78,
97     SPARSE_TO_DENSE = 79,
98     SPLIT = 80,
99     SQRT = 81,
100     TILE = 82,
101     TOPK_V2 = 83,
102     TRANSPOSE_CONV_2D = 84,
103     UNIDIRECTIONAL_SEQUENCE_LSTM = 85,
104     UNIDIRECTIONAL_SEQUENCE_RNN = 86,
105     ROTATED_BBOX_TRANSFORM = 87,
106 };
108 /**
109  * Describes one operation of the model's graph.
110  */
111 struct Operation {
112     /**
113      * The operation type.
114      */
115     OperationType type;
117     /**
118      * Describes the table that contains the indexes of the inputs of the
119      * operation. The offset is the index in the operandIndexes table.
120      */
121     vec<uint32_t> inputs;
123     /**
124      * Describes the table that contains the indexes of the outputs of the
125      * operation. The offset is the index in the operandIndexes table.
126      */
127     vec<uint32_t> outputs;
128 };
130 /**
131  * Describes one operand of the model's graph.
132  */
133 struct Operand {
134     /**
135      * Data type of the operand.
136      */
137     OperandType type;
139     /**
140      * Dimensions of the operand.
141      *
142      * For a scalar operand, dimensions.size() must be 0.
143      *
144      * For a tensor operand, dimensions.size() must be at least 1;
145      * however, any of the dimensions may be unspecified.
146      *
147      * A tensor operand with all dimensions specified has "fully
148      * specified" dimensions. Whenever possible (i.e., whenever the
149      * dimensions are known at model construction time), a tensor
150      * operand should have (but is not required to have) fully
151      * specified dimensions, in order to enable the best possible
152      * performance.
153      *
154      * If a tensor operand's dimensions are not fully specified, the
155      * dimensions of the operand are deduced from the operand
156      * dimensions and values of the operation for which that operand
157      * is an output.
158      *
159      * In the following situations, a tensor operand's dimensions must
160      * be fully specified:
161      *
162      *     . The operand has lifetime CONSTANT_COPY or
163      *       CONSTANT_REFERENCE.
164      *
165      *     . The operand has lifetime MODEL_INPUT or MODEL_OUTPUT. Fully
166      *       specified dimensions must either be present in the
167      *       Operand or they must be provided in the corresponding
168      *       RequestArgument.
169      *       EXCEPTION: If the input or output is optional and omitted
170      *       (by setting the hasNoValue field of the corresponding
171      *       RequestArgument to true) then it need not have fully
172      *       specified dimensions.
173      *
174      * A tensor operand with some number of unspecified dimensions is
175      * represented by setting each unspecified dimension to 0.
176      */
177     vec<uint32_t> dimensions;
179     /**
180      * The number of times this operand appears as an operation input.
181      *
182      * (For example, if this operand appears once in one operation's
183      * input list, and three times in another operation's input list,
184      * then numberOfConsumers = 4.)
185      */
186     uint32_t numberOfConsumers;
188     /**
189      * Quantized scale of the operand.
190      *
191      * Only applicable if the operand is of type TENSOR_QUANT8_ASYMM or
192      * TENSOR_INT32.
193      */
194     float scale;
196     /**
197      * Quantized zero-point offset of the operand.
198      *
199      * Only applicable if the operand is of type TENSOR_QUANT8_ASYMM.
200      */
201     int32_t zeroPoint;
203     /**
204      * How the operand is used.
205      */
206     OperandLifeTime lifetime;
208     /**
209      * Where to find the data for this operand.
210      * If the lifetime is TEMPORARY_VARIABLE, MODEL_INPUT, MODEL_OUTPUT, or
211      * NO_VALUE:
212      * - All the fields must be 0.
213      * If the lifetime is CONSTANT_COPY:
214      * - location.poolIndex is 0.
215      * - location.offset is the offset in bytes into Model.operandValues.
216      * - location.length is set.
217      * If the lifetime is CONSTANT_REFERENCE:
218      * - location.poolIndex is set.
219      * - location.offset is the offset in bytes into the specified pool.
220      * - location.length is set.
221      */
222     DataLocation location;
223 };
225 /**
226  * A Neural Network Model.
227  *
228  * This includes not only the execution graph, but also constant data such as
229  * weights or scalars added at construction time. The only information that
230  * may not be known is the shape of the input tensors.
231  */
232 struct Model {
233     /**
234      * All operands included in the model.
235      */
236     vec<Operand> operands;
238     /**
239      * All operations included in the model.
240      *
241      * The operations are sorted into execution order. Every operand
242      * with lifetime MODEL_OUTPUT or TEMPORARY_VARIABLE must be
243      * written before it is read.
244      */
245     vec<Operation> operations;
247     /**
248      * Input indexes of the model. There must be at least one.
249      *
250      * Each value corresponds to the index of the operand in "operands".
251      */
252     vec<uint32_t> inputIndexes;
254     /**
255      * Output indexes of the model. There must be at least one.
256      *
257      * Each value corresponds to the index of the operand in "operands".
258      */
259     vec<uint32_t> outputIndexes;
261     /**
262      * A byte buffer containing operand data that were copied into the model.
263      *
264      * An operand's value must be located here if and only if Operand::lifetime
265      * equals OperandLifeTime::CONSTANT_COPY.
266      */
267     vec<uint8_t> operandValues;
269     /**
270      * A collection of shared memory pools containing operand values.
271      *
272      * An operand's value must be located here if and only if Operand::lifetime
273      * equals OperandLifeTime::CONSTANT_REFERENCE.
274      */
275     vec<memory> pools;
277     /**
278      * 'true' indicates TENSOR_FLOAT32 may be calculated with range and/or
279      * precision as low as that of the IEEE 754 16-bit floating-point format.
280      * 'false' indicates TENSOR_FLOAT32 must be calculated using at least the
281      * range and precision of the IEEE 754 32-bit floating-point format.
282      */
283     bool relaxComputationFloat32toFloat16;
284 };