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.1; 18 19 import @1.0::Operand; 20 import @1.0::OperationType; 21 import @1.0::PerformanceInfo; 22 23 /** 24 * Operation types. 25 * 26 * The type of an operation in a model. 27 */ 28 enum OperationType : @1.0::OperationType { 29 /** 30 * BatchToSpace for N-dimensional tensors. 31 * 32 * This operation reshapes the batch dimension (dimension 0) into M + 1 33 * dimensions of shape block_shape + [batch], interleaves these blocks back 34 * into the grid defined by the spatial dimensions [1, ..., M], to obtain a 35 * result with the same rank as the input. 36 * 37 * This is the reverse of SpaceToBatch. 38 * 39 * Supported tensor {@link OperandType}: 40 * * {@link OperandType::TENSOR_FLOAT32} 41 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 42 * 43 * Supported tensor rank: 4 44 * 45 * Inputs: 46 * * 0: An n-D tensor, specifying the tensor to be reshaped 47 * * 1: A 1-D Tensor of {@link OperandType::TENSOR_INT32}, the block 48 * sizes for each spatial dimension of the input tensor. All values 49 * must be >= 1. 50 * 51 * Outputs: 52 * * 0: A tensor of the same {@link OperandType} as input0. 53 */ 54 BATCH_TO_SPACE_ND = 29, 55 56 /** 57 * Element-wise division of two tensors. 58 * 59 * Takes two input tensors of identical {@link OperandType} and compatible 60 * dimensions. The output is the result of dividing the first input tensor 61 * by the second, optionally modified by an activation function. 62 * 63 * Two dimensions are compatible when: 64 * 1. they are equal, or 65 * 2. one of them is 1 66 * 67 * The size of the output is the maximum size along each dimension of the 68 * input operands. It starts with the trailing dimensions, and works its way 69 * forward. 70 * 71 * Example: 72 * input1.dimension = {4, 1, 2} 73 * input2.dimension = {5, 4, 3, 1} 74 * output.dimension = {5, 4, 3, 2} 75 * 76 * Supported tensor {@link OperandType}: 77 * * {@link OperandType::TENSOR_FLOAT32} 78 * 79 * Supported tensor rank: up to 4 80 * 81 * Inputs: 82 * * 0: An n-D tensor, specifying the first input. 83 * * 1: A tensor of the same {@link OperandType}, and compatible dimensions 84 * as input0. 85 * * 2: An {@link OperandType::INT32} scalar, and has to be one of the 86 * {@link FusedActivationFunc} values. Specifies the activation to 87 * invoke on the result. 88 * 89 * Outputs: 90 * * 0: A tensor of the same {@link OperandType} as input0. 91 */ 92 DIV = 30, 93 94 /** 95 * Computes the mean of elements across dimensions of a tensor. 96 * 97 * Reduces the input tensor along the given dimensions to reduce. Unless 98 * keep_dims is true, the rank of the tensor is reduced by 1 for each entry 99 * in axis. If keep_dims is true, the reduced dimensions are retained with 100 * length 1. 101 * 102 * If dimensions to reduce have no entries, all dimensions are reduced, and 103 * a tensor with a single element is returned. 104 * 105 * Supported tensor {@link OperandType}: 106 * * {@link OperandType::TENSOR_FLOAT32} 107 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 108 * 109 * Supported tensor rank: up to 4 110 * 111 * Inputs: 112 * * 0: A tensor, specifying the input. 113 * * 1: A 1-D Tensor of {@link OperandType::TENSOR_INT32}. The dimensions 114 * to reduce. If None (the default), reduces all dimensions. Must be in 115 * the range [-rank(input_tensor), rank(input_tensor)). 116 * * 2: An {@link OperandType::INT32} scalar, keep_dims. If positive, 117 * retains reduced dimensions with length 1. 118 * 119 * Outputs: 120 * * 0: A tensor of the same {@link OperandType} as input0. 121 */ 122 MEAN = 31, 123 124 /** 125 * Pads a tensor. 126 * 127 * This operation pads a tensor according to the specified paddings. 128 * 129 * Supported tensor {@link OperandType}: 130 * * {@link OperandType::TENSOR_FLOAT32} 131 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 132 * 133 * Supported tensor rank: up to 4 134 * 135 * Inputs: 136 * * 0: An n-D tensor, specifying the tensor to be padded. 137 * * 1: A 2-D Tensor of {@link OperandType::TENSOR_INT32}, the paddings 138 * for each spatial dimension of the input tensor. The shape of the 139 * tensor must be {rank(input0), 2}. 140 * padding[i, 0] specifies the number of element to be padded in the 141 * front of dimension i. 142 * padding[i, 1] specifies the number of element to be padded after the 143 * end of dimension i. 144 * 145 * Outputs: 146 * * 0: A tensor of the same {@link OperandType} as input0. 147 */ 148 PAD = 32, 149 150 /** 151 * SpaceToBatch for N-Dimensional tensors. 152 * 153 * This operation divides "spatial" dimensions [1, ..., M] of the input into 154 * a grid of blocks of shape block_shape, and interleaves these blocks with 155 * the "batch" dimension (0) such that in the output, the spatial dimensions 156 * [1, ..., M] correspond to the position within the grid, and the batch 157 * dimension combines both the position within a spatial block and the 158 * original batch position. Prior to division into blocks, the spatial 159 * dimensions of the input are optionally zero padded according to paddings. 160 * 161 * Supported tensor {@link OperandType}: 162 * * {@link OperandType::TENSOR_FLOAT32} 163 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 164 * 165 * Supported tensor rank: 4 166 * 167 * Inputs: 168 * * 0: An n-D tensor, specifying the input. 169 * * 1: A 1-D Tensor of {@link OperandType::TENSOR_INT32}, the block 170 * sizes for each spatial dimension of the input tensor. All values 171 * must be >= 1. 172 * * 2: A 2-D Tensor of {@link OperandType::TENSOR_INT32}, the paddings 173 * for each spatial dimension of the input tensor. All values must be 174 * >= 0. The shape of the tensor must be {rank(input0), 2}. 175 * padding[i, 0] specifies the number of element to be padded in the 176 * front of dimension i. 177 * padding[i, 1] specifies the number of element to be padded after the 178 * end of dimension i. 179 * 180 * Outputs: 181 * * 0: A tensor of the same {@link OperandType} as input0. 182 */ 183 SPACE_TO_BATCH_ND = 33, 184 185 /** 186 * Removes dimensions of size 1 from the shape of a tensor. 187 * 188 * Given a tensor input, this operation returns a tensor of the same 189 * {@link OperandType} with all dimensions of size 1 removed. If you don't 190 * want to remove all size 1 dimensions, you can remove specific size 1 191 * dimensions by specifying the axes (input1). 192 * 193 * Supported tensor {@link OperandType}: 194 * * {@link OperandType::TENSOR_FLOAT32} 195 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 196 * 197 * Supported tensor rank: up to 4 198 * 199 * Inputs: 200 * * 0: An n-D tensor, the tensor to be squeezed. 201 * * 1: An optional 1-D tensor of {@link OperandType::TENSOR_INT32}. The 202 * dimensions to squeeze. If specified only squeezes the dimensions 203 * listed. Otherwise, squeezes all dimensions. The dimension index 204 * starts at 0. An error must be reported if squeezing a dimension that 205 * is not 1. 206 * 207 * Outputs: 208 * * 0: A tensor of the same {@link OperandType} as input0. Contains the 209 * same data as input, but has one or more dimensions of size 1 210 * removed. 211 */ 212 SQUEEZE = 34, 213 214 /** 215 * Extracts a strided slice of a tensor. 216 * 217 * Roughly speaking, this op extracts a slice of size (end - begin) / stride 218 * from the given input tensor. Starting at the location specified by begin 219 * the slice continues by adding stride to the index until all dimensions 220 * are not less than end. Note that a stride can be negative, which causes a 221 * reverse slice. 222 * 223 * Supported tensor {@link OperandType}: 224 * * {@link OperandType::TENSOR_FLOAT32} 225 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 226 * 227 * Supported tensor rank: up to 4 228 * 229 * Inputs: 230 * * 0: An n-D tensor, specifying the tensor to be sliced. 231 * * 1: A 1-D Tensor of {@link OperandType::TENSOR_INT32}, the starts of 232 * the dimensions of the input tensor to be sliced. The length must be 233 * of rank(input0). 234 * * 2: A 1-D Tensor of {@link OperandType::TENSOR_INT32}, the ends of 235 * the dimensions of the input tensor to be sliced. The length must be 236 * of rank(input0). 237 * * 3: A 1-D Tensor of {@link OperandType::TENSOR_INT32}, the strides of 238 * the dimensions of the input tensor to be sliced. The length must be 239 * of rank(input0). 240 * * 4: An {@link OperandType::INT32} scalar, begin_mask. If the ith bit 241 * of begin_mask is set, begin[i] is ignored and the fullest possible 242 * range in that dimension is used instead. 243 * * 5: An {@link OperandType::INT32} scalar, end_mask. If the ith bit of 244 * end_mask is set, end[i] is ignored and the fullest possible range in 245 * that dimension is used instead. 246 * * 6: An {@link OperandType::INT32} scalar, shrink_axis_mask. An int32 247 * mask. If the ith bit of shrink_axis_mask is set, it implies that the 248 * ith specification shrinks the dimensionality by 1. A slice of size 1 249 * starting from begin[i] in the dimension must be preserved. 250 * 251 * Outputs: 252 * * 0: A tensor of the same {@link OperandType} as input0. 253 */ 254 STRIDED_SLICE = 35, 255 256 /** 257 * Element-wise subtraction of two tensors. 258 * 259 * Takes two input tensors of identical {@link OperandType} and compatible 260 * dimensions. The output is the result of subtracting the second input 261 * tensor from the first one, optionally modified by an activation function. 262 * 263 * Two dimensions are compatible when: 264 * 1. they are equal, or 265 * 2. one of them is 1 266 * 267 * The size of the output is the maximum size along each dimension of the 268 * input operands. It starts with the trailing dimensions, and works its way 269 * forward. 270 * 271 * Example: 272 * input1.dimension = {4, 1, 2} 273 * input2.dimension = {5, 4, 3, 1} 274 * output.dimension = {5, 4, 3, 2} 275 * 276 * Supported tensor {@link OperandType}: 277 * * {@link OperandType::TENSOR_FLOAT32} 278 * 279 * Supported tensor rank: up to 4 280 * 281 * Inputs: 282 * * 0: An n-D tensor, specifying the first input. 283 * * 1: A tensor of the same {@link OperandType}, and compatible dimensions 284 * as input0. 285 * * 2: An {@link OperandType::INT32} scalar, and has to be one of the 286 * {@link FusedActivationFunc} values. Specifies the activation to 287 * invoke on the result. 288 * 289 * Outputs: 290 * * 0: A tensor of the same {@link OperandType} as input0. 291 */ 292 SUB = 36, 293 294 /** 295 * Transposes the input tensor, permuting the dimensions according to the 296 * perm tensor. 297 * 298 * The returned tensor's dimension i corresponds to the input dimension 299 * perm[i]. If perm is not given, it is set to (n-1...0), where n is the 300 * rank of the input tensor. Hence by default, this operation performs a 301 * regular matrix transpose on 2-D input Tensors. 302 * 303 * Supported tensor {@link OperandType}: 304 * * {@link OperandType::TENSOR_FLOAT32} 305 * * {@link OperandType::TENSOR_QUANT8_ASYMM} 306 * 307 * Supported tensor rank: up to 4 308 * 309 * Inputs: 310 * * 0: An n-D tensor, specifying the tensor to be transposed. 311 * * 1: An optional 1-D Tensor of {@link OperandType::TENSOR_INT32}, 312 * the permutation of the dimensions of the input tensor. 313 * 314 * Outputs: 315 * * 0: A tensor of the same {@link OperandType} as input0. 316 */ 317 TRANSPOSE = 37, 318 }; 319 320 /** 321 * The capabilities of a driver. 322 */ 323 struct Capabilities { 324 /** 325 * Driver performance when operating on float32 data. 326 */ 327 PerformanceInfo float32Performance; 328 329 /** 330 * Driver performance when operating on asymmetric 8-bit quantized data. 331 */ 332 PerformanceInfo quantized8Performance; 333 334 /** 335 * Driver performance when operating on float32 data but performing 336 * calculations with range and/or precision as low as that of the IEEE 337 * 754 16-bit floating-point format. 338 */ 339 PerformanceInfo relaxedFloat32toFloat16Performance; 340 }; 341 342 /** 343 * Describes one operation of the model's graph. 344 */ 345 struct Operation { 346 /** 347 * The operation type. 348 */ 349 OperationType type; 350 351 /** 352 * Describes the table that contains the indexes of the inputs of the 353 * operation. The offset is the index in the operandIndexes table. 354 */ 355 vec<uint32_t> inputs; 356 357 /** 358 * Describes the table that contains the indexes of the outputs of the 359 * operation. The offset is the index in the operandIndexes table. 360 */ 361 vec<uint32_t> outputs; 362 }; 363 364 /** 365 * A Neural Network Model. 366 * 367 * This includes not only the execution graph, but also constant data such as 368 * weights or scalars added at construction time. The only information that 369 * may not be known is the shape of the input tensors. 370 */ 371 struct Model { 372 /** 373 * All operands included in the model. 374 */ 375 vec<Operand> operands; 376 377 /** 378 * All operations included in the model. 379 * 380 * The operations are sorted into execution order. 381 */ 382 vec<Operation> operations; 383 384 /** 385 * Input indexes of the model. 386 * 387 * Each value corresponds to the index of the operand in "operands". 388 */ 389 vec<uint32_t> inputIndexes; 390 391 /** 392 * Output indexes of the model. 393 * 394 * Each value corresponds to the index of the operand in "operands". 395 */ 396 vec<uint32_t> outputIndexes; 397 398 /** 399 * A byte buffer containing operand data that were copied into the model. 400 * 401 * An operand's value must be located here if and only if Operand::lifetime 402 * equals OperandLifeTime::CONSTANT_COPY. 403 */ 404 vec<uint8_t> operandValues; 405 406 /** 407 * A collection of shared memory pools containing operand data that were 408 * registered by the model. 409 * 410 * An operand's value must be located here if and only if Operand::lifetime 411 * equals OperandLifeTime::CONSTANT_REFERENCE. 412 */ 413 vec<memory> pools; 414 415 /** 416 * 'true' indicates TENSOR_FLOAT32 may be calculated with range and/or 417 * precision as low as that of the IEEE 754 16-bit floating-point format. 418 * 'false' indicates TENSOR_FLOAT32 must be calculated using at least the 419 * range and precision of the IEEE 754 32-bit floating-point format. 420 */ 421 bool relaxComputationFloat32toFloat16; 422 }; 423 424 /** 425 * Execution preferences. 426 */ 427 enum ExecutionPreference : int32_t { 428 /** 429 * Prefer executing in a way that minimizes battery drain. 430 * This is desirable for compilations that will be executed often. 431 */ 432 LOW_POWER = 0, 433 /** 434 * Prefer returning a single answer as fast as possible, even if this causes 435 * more power consumption. 436 */ 437 FAST_SINGLE_ANSWER = 1, 438 /** 439 * Prefer maximizing the throughput of successive frames, for example when 440 * processing successive frames coming from the camera. 441 */ 442 SUSTAINED_SPEED = 2, 443 }; 444