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  */
  16
  17 package android.hardware.neuralnetworks@1.2;
  18
  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;
  24
  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 };
  48
  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 };
 107
 108 /**
 109  * Describes one operation of the model's graph.
 110  */
 111 struct Operation {
 112     /**
 113      * The operation type.
 114      */
 115     OperationType type;
 116
 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;
 122
 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 };
 129
 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;
 138
 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;
 178
 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;
 187
 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;
 195
 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;
 202
 203     /**
 204      * How the operand is used.
 205      */
 206     OperandLifeTime lifetime;
 207
 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 };
 224
 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;
 237
 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;
 246
 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;
 253
 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;
 260
 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;
 268
 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;
 276
 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 };