1 /* Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 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 #ifndef TENSORFLOW_LITE_NNAPI_NNAPI_IMPLEMENTATION_H_ 16 #define TENSORFLOW_LITE_NNAPI_NNAPI_IMPLEMENTATION_H_ 17 18 #include <stdint.h> 19 #include <stdio.h> 20 #include <stdlib.h> 21 22 #include <memory> 23 24 #include "tensorflow/lite/nnapi/NeuralNetworksTypes.h" 25 26 struct NnApi { 27 bool nnapi_exists; 28 int32_t android_sdk_version; 29 // NNAPI feature level should be used when deciding which NNAPI feature to 30 // use, as feature levels after Android API level 31 have no association with 31 // API level because the NNAPI specification can be updated between Android 32 // API releases. 33 int64_t nnapi_runtime_feature_level; 34 35 /** 36 * Creates a shared memory object from a file descriptor. 37 * 38 * The shared memory is backed by a file descriptor via mmap. 39 * See {@link ANeuralNetworksMemory} for a description on how to use 40 * this shared memory. 41 * 42 * @param size The requested size in bytes. 43 * Must not be larger than the file size. 44 * @param prot The desired memory protection for the mapping. 45 * It is either PROT_NONE or the bitwise OR of one or 46 * more of the following flags: PROT_READ, PROT_WRITE. 47 * @param fd The requested file descriptor. 48 * The file descriptor has to be mmap-able. The file 49 * descriptor will be duplicated. 50 * @param offset The offset to the beginning of the file of the area to map. 51 * The offset has to be aligned to a page size. 52 * @param memory The memory object to be created. 53 * Set to NULL if unsuccessful. 54 * 55 * @return ANEURALNETWORKS_NO_ERROR if the request completed normally. 56 */ 57 int (*ANeuralNetworksMemory_createFromFd)(size_t size, int protect, int fd, 58 size_t offset, 59 ANeuralNetworksMemory** memory); 60 61 /** 62 * Delete a memory object. 63 * 64 * Destroys the object used by the run time to keep track of the memory. 65 * This will free the underlying actual memory if no other code has open 66 * handles to this memory. 67 * 68 * @param memory The memory object to be freed. 69 */ 70 void (*ANeuralNetworksMemory_free)(ANeuralNetworksMemory* memory); 71 72 /** 73 * Create an empty {@link ANeuralNetworksModel}. 74 * 75 * <p>This only creates the object. Computation is performed once 76 * {@link ANeuralNetworksExecution_startCompute} is invoked. 77 * 78 * The model should be constructed with calls to 79 * {@link ANeuralNetworksModel_addOperation} and 80 * {@link ANeuralNetworksModel_addOperand} 81 * 82 * <p>{@link ANeuralNetworksModel_finish} should be called once the model 83 * has been fully constructed.</p> 84 * 85 * <p>{@link ANeuralNetworksModel_free} should be called once the model 86 * is no longer needed.</p> 87 * 88 * @param model The {@link ANeuralNetworksModel} to be created. 89 * Set to NULL if unsuccessful. 90 * 91 * @return ANEURALNETWORKS_NO_ERROR if successful. 92 */ 93 int (*ANeuralNetworksModel_create)(ANeuralNetworksModel** model); 94 95 /** 96 * Destroy a model. 97 * 98 * The model need not have been finished by a call to 99 * {@link ANeuralNetworksModel_finish}. 100 * 101 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 102 * 103 * @param model The model to be destroyed. Passing NULL is acceptable and 104 * results in no operation. 105 */ 106 void (*ANeuralNetworksModel_free)(ANeuralNetworksModel* model); 107 108 /** 109 * Indicate that we have finished modifying a model. Required before 110 * calling {@link ANeuralNetworksCompilation_compile}. 111 * 112 * An application is responsible to make sure that no other thread uses 113 * the model at the same time. 114 * 115 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 116 * 117 * @param model The model to be finished. 118 * 119 * @return ANEURALNETWORKS_NO_ERROR if successful. 120 */ 121 int (*ANeuralNetworksModel_finish)(ANeuralNetworksModel* model); 122 123 /** 124 * Add an operand to a model. 125 * 126 * The order in which the operands are added is important. The first one added 127 * to a model will have the index value 0, the second 1, etc. These indexes 128 * are used as operand identifiers in 129 * {@link ANeuralNetworksModel_addOperation}, 130 * {@link ANeuralNetworksExecution_setInput}, 131 * {@link ANeuralNetworksExecution_setInputFromMemory}, 132 * {@link ANeuralNetworksExecution_setOutput}, 133 * {@link ANeuralNetworksExecution_setOutputFromMemory} and 134 * {@link ANeuralNetworksExecution_setOperandValue}. 135 * 136 * To build a model that can accommodate inputs of various sizes, as you may 137 * want to do for a CNN, set the size of the dimensions that will vary at run 138 * time to 0. If you do so, provide the full dimensions when calling 139 * {@link ANeuralNetworksExecution_setInput} or {@link 140 * ANeuralNetworksExecution_setInputFromMemory}. 141 * 142 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 143 * been called will return an error. 144 * 145 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 146 * 147 * @param model The model to be modified. 148 * @param type The {@link ANeuralNetworksOperandType} that describes the shape 149 * of the operand. 150 * 151 * @return ANEURALNETWORKS_NO_ERROR if successful. 152 */ 153 int (*ANeuralNetworksModel_addOperand)( 154 ANeuralNetworksModel* model, const ANeuralNetworksOperandType* type); 155 156 /** 157 * Sets an operand to a constant value. 158 * 159 * For scalar values, the content of buffer is copied into the model. 160 * 161 * For tensor values, a pointer to the buffer is stored within the model. 162 * The application is responsible for not changing the content of this region 163 * until all executions using this model have completed. As the data may 164 * be copied during processing, modifying the data after this call yields 165 * undefined results. 166 * 167 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 168 * been called will return an error. 169 * 170 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 171 * 172 * @param model The model to be modified. 173 * @param index The index of the model operand we're setting. 174 * @param buffer A pointer to the data to use. 175 * @param length The size in bytes of the data value. 176 * 177 * @return ANEURALNETWORKS_NO_ERROR if successful. 178 */ 179 int (*ANeuralNetworksModel_setOperandValue)(ANeuralNetworksModel* model, 180 int32_t index, const void* buffer, 181 size_t length); 182 183 /** 184 * Sets an operand's per channel quantization parameters. 185 * 186 * Sets parameters required by a tensor of type 187 * {@link ANEURALNETWORKS_TENSOR_QUANT8_SYMM_PER_CHANNEL}. 188 * This function must be called for every tensor of type 189 * {@link ANEURALNETWORKS_TENSOR_QUANT8_SYMM_PER_CHANNEL} before 190 * calling {@link ANeuralNetworksModel_finish}. 191 * 192 * Available since API level 29. 193 * 194 * @param model The model to be modified. 195 * @param index The index of the model operand we're setting. 196 * @param channelQuant The per channel quantization parameters for the 197 * operand. No memory in this struct needs to outlive the 198 * call to this function. 199 * 200 * @return ANEURALNETWORKS_NO_ERROR if successful. 201 */ 202 int (*ANeuralNetworksModel_setOperandSymmPerChannelQuantParams)( 203 ANeuralNetworksModel* model, int32_t index, 204 const ANeuralNetworksSymmPerChannelQuantParams* channelQuant); 205 206 /** 207 * Sets an operand to a value stored in a memory object. 208 * 209 * The content of the memory is not copied. A reference to that memory is 210 * stored inside the model. The application is responsible for not changing 211 * the content of the memory region until all executions using this model have 212 * completed. 213 * As the data may be copied during processing, modifying the data after this 214 * call yields undefined results. 215 * 216 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 217 * been called will return an error. 218 * 219 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 220 * 221 * @param model The model to be modified. 222 * @param index The index of the model operand we're setting. 223 * @param buffer A pointer to the data to use. 224 * @param memory The memory containing the data. 225 * @param offset This specifies the location of the data within the memory. 226 * The offset is in bytes from the start of memory. 227 * @param length The size in bytes of the data value. 228 * 229 * @return ANEURALNETWORKS_NO_ERROR if successful. 230 */ 231 int (*ANeuralNetworksModel_setOperandValueFromMemory)( 232 ANeuralNetworksModel* model, int32_t index, 233 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 234 235 /** 236 * Add an operation to a model. 237 * 238 * @param model The model to be modified. 239 * @param type The type of the operation. 240 * @param inputCount The number of entries in the inputs array. 241 * @param inputs An array of indexes identifying each operand. 242 * @param outputCount The number of entries in the outputs array. 243 * @param outputs An array of indexes identifying each operand. 244 * 245 * The operands specified by inputs and outputs must have been 246 * previously added by calls to {@link ANeuralNetworksModel_addOperand}. 247 * 248 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 249 * been called will return an error. 250 * 251 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 252 * 253 * @return ANEURALNETWORKS_NO_ERROR if successful. 254 */ 255 int (*ANeuralNetworksModel_addOperation)(ANeuralNetworksModel* model, 256 ANeuralNetworksOperationType type, 257 uint32_t inputCount, 258 const uint32_t* inputs, 259 uint32_t outputCount, 260 const uint32_t* outputs); 261 262 /** 263 * Specifies which operands will be the model's inputs and outputs. 264 * 265 * An operand cannot be used for both input and output. Doing so will 266 * return an error. 267 * 268 * @param model The model to be modified. 269 * @param inputCount The number of entries in the inputs array. 270 * @param inputs An array of indexes identifying the input operands. 271 * @param outputCount The number of entries in the outputs array. 272 * @param outputs An array of indexes identifying the output operands. 273 * 274 * The operands specified by inputs and outputs must have been 275 * previously added by calls to {@link ANeuralNetworksModel_addOperand}. 276 * 277 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 278 * been called will return an error. 279 * 280 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 281 * 282 * @return ANEURALNETWORKS_NO_ERROR if successful. 283 */ 284 int (*ANeuralNetworksModel_identifyInputsAndOutputs)( 285 ANeuralNetworksModel* model, uint32_t inputCount, const uint32_t* inputs, 286 uint32_t outputCount, const uint32_t* outputs); 287 288 /** 289 * Specifies whether {@link ANEURALNETWORKS_TENSOR_FLOAT32} is allowed to be 290 * calculated with range and/or precision as low as that of the 291 * IEEE 754 16-bit floating-point format. By default, 292 * {@link ANEURALNETWORKS_TENSOR_FLOAT32} must be calculated using at least 293 * the range and precision of the IEEE 754 32-bit floating-point format. 294 * 295 * @param model The model to be modified. 296 * @param allow 'true' indicates {@link ANEURALNETWORKS_TENSOR_FLOAT32} may be 297 * calculated with range and/or precision as low as that of the 298 * IEEE 754 16-bit floating point format. 'false' indicates 299 * {@link ANEURALNETWORKS_TENSOR_FLOAT32} must be calculated 300 * using at least the range and precision of the IEEE 754 32-bit 301 * floating point format. 302 * 303 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 304 * been called will return an error. 305 * 306 * Available since API level 28. 307 * 308 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 309 * 310 * @return ANEURALNETWORKS_NO_ERROR if successful. 311 */ 312 int (*ANeuralNetworksModel_relaxComputationFloat32toFloat16)( 313 ANeuralNetworksModel* model, bool allow); 314 315 /** 316 * Create a {@link ANeuralNetworksCompilation} to compile the given model. 317 * This only creates the object. Compilation is only performed once 318 * {@link ANeuralNetworksCompilation_start} is invoked. 319 * 320 * <p>The provided model must outlive the compilation.</p> 321 * 322 * The model must already have been finished by a call to 323 * {@link ANeuralNetworksModel_finish}. 324 * 325 * See {@link ANeuralNetworksCompilation} for information on multithreaded 326 * usage. 327 * 328 * @param model The {@link ANeuralNetworksModel} to be compiled. 329 * @param compilation The newly created object or NULL if unsuccessful. 330 * 331 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 332 * if the model is invalid. 333 */ 334 int (*ANeuralNetworksCompilation_create)( 335 ANeuralNetworksModel* model, ANeuralNetworksCompilation** compilation); 336 337 /** 338 * Destroy a compilation. 339 * 340 * <p>If called on a compilation for which 341 * {@link ANeuralNetworksCompilation_start} has been called, the 342 * function will return immediately but will mark the compilation to be 343 * deleted once the compilation completes. The 344 * {@link ANeuralNetworksCompilation_wait} will return ERROR_DELETED. 345 * 346 * See {@link ANeuralNetworksCompilation} for information on multithreaded 347 * usage. 348 * 349 * @param compilation The compilation to be destroyed. Passing NULL is 350 * acceptable and results in no operation. 351 */ 352 void (*ANeuralNetworksCompilation_free)( 353 ANeuralNetworksCompilation* compilation); 354 355 /** 356 * Sets the execution preference. 357 * 358 * <p>Provides guidance to the runtime when trade-offs are possible.</p> 359 * 360 * See {@link ANeuralNetworksCompilation} for information on multithreaded 361 * usage. 362 * 363 * @param compilation The compilation to be modified. 364 * @param preference Either {@link PREFER_LOW_POWER}, 365 * {@link PREFER_SINGLE_FAST_ANSWER}, or 366 * {@link PREFER_SUSTAINED_SPEED}. 367 * 368 * @return ANEURALNETWORKS_NO_ERROR if successful. 369 */ 370 int (*ANeuralNetworksCompilation_setPreference)( 371 ANeuralNetworksCompilation* compilation, int32_t preference); 372 373 /** 374 * Waits until the compilation completes. 375 * 376 * More than one thread can wait on a compilation. When the compilation 377 * completes, all threads will be released. 378 * 379 * See {@link ANeuralNetworksCompilation} for information on multithreaded 380 * usage. 381 * 382 * @return ANEURALNETWORKS_NO_ERROR if the compilation completed normally. 383 */ 384 int (*ANeuralNetworksCompilation_finish)( 385 ANeuralNetworksCompilation* compilation); 386 387 /** 388 * Create a {@link ANeuralNetworksExecution} to apply the given compilation. 389 * This only creates the object. Computation is only performed once 390 * {@link ANeuralNetworksExecution_startCompute} is invoked. 391 * 392 * <p>The provided compilation must outlive the execution.</p> 393 * 394 * See {@link ANeuralNetworksExecution} for information on multithreaded 395 * usage. 396 * 397 * @param compilation The {@link ANeuralNetworksCompilation} to be evaluated. 398 * @param execution The newly created object or NULL if unsuccessful. 399 * 400 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 401 * if the compilation is invalid. 402 */ 403 int (*ANeuralNetworksExecution_create)( 404 ANeuralNetworksCompilation* compilation, 405 ANeuralNetworksExecution** execution); 406 407 /** 408 * Destroy an execution. 409 * 410 * <p>If called on an execution for which 411 * {@link ANeuralNetworksExecution_startCompute} has been called, the 412 * function will return immediately but will mark the execution to be deleted 413 * once the computation completes. The {link ANeuralNetworksExecution_wait} 414 * will return ANEURALNETWORKS_ERROR_DELETED. 415 * 416 * See {@link ANeuralNetworksExecution} for information on multithreaded 417 * usage. 418 * 419 * @param execution The execution to be destroyed. Passing NULL is acceptable 420 * and results in no operation. 421 */ 422 void (*ANeuralNetworksExecution_free)(ANeuralNetworksExecution* execution); 423 424 /** 425 * Associate a user buffer with an input of the model of the 426 * {@link ANeuralNetworksExecution}. 427 * 428 * <p>The provided buffer must outlive the execution.</p> 429 * 430 * See {@link ANeuralNetworksExecution} for information on multithreaded 431 * usage. 432 * 433 * @param execution The execution to be modified. 434 * @param index The index of the input argument we are setting. It is 435 * an index into the lists passed to 436 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 437 * not the index associated with {@link 438 * ANeuralNetworksModel_addOperand}. 439 * @param type The type of the operand. This should be used to specify the 440 * dimensions that were set to 0 when the operand was added to the 441 * model. All other properties of the type must be the same as 442 * specified in the model. If the type is the same as specified 443 * when the model was built, NULL can be passed. 444 * @param buffer The buffer containing the data. 445 * @param length The length in bytes of the buffer. 446 * 447 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 448 * the name is not recognized or the buffer is too small for the input. 449 */ 450 int (*ANeuralNetworksExecution_setInput)( 451 ANeuralNetworksExecution* execution, int32_t index, 452 const ANeuralNetworksOperandType* type, const void* buffer, 453 size_t length); 454 455 /** 456 * Associate part of a memory object with an input of the model of the 457 * {@link ANeuralNetworksExecution}. 458 * 459 * <p>The provided memory must outlive the execution.</p> 460 * 461 * See {@link ANeuralNetworksExecution} for information on multithreaded 462 * usage. 463 * 464 * @param execution The execution to be modified. 465 * @param index The index of the input argument we are setting. It is 466 * an index into the lists passed to 467 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 468 * not the index associated with {@link 469 * ANeuralNetworksModel_addOperand}. 470 * @param type The type of the operand. This can be used to specify the 471 * dimensions that were set to 0 when the operand was added to the 472 * model. All other values must be the same as specified in the 473 * model. If the type is the same as specified when the model 474 * was built, NULL can be passed. 475 * @param memory The memory containing the data. 476 * @param offset This specifies the location of the data within the memory. 477 * The offset is in bytes from the start of memory. 478 * @param length The size in bytes of the data value. 479 * 480 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 481 * the name is not recognized or the buffer is too small for the input. 482 */ 483 int (*ANeuralNetworksExecution_setInputFromMemory)( 484 ANeuralNetworksExecution* execution, int32_t index, 485 const ANeuralNetworksOperandType* type, 486 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 487 488 /** 489 * Associate a user buffer with an output of the model of the 490 * {@link ANeuralNetworksExecution}. 491 * 492 * <p>The provided buffer must outlive the execution.</p> 493 * 494 * See {@link ANeuralNetworksExecution} for information on multithreaded 495 * usage. 496 * 497 * @param execution The execution to be modified. 498 * @param index The index of the output argument we are setting. It is 499 * an index into the lists passed to 500 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 501 * not the index associated with {@link 502 * ANeuralNetworksModel_addOperand}. 503 * @param type The type of the operand. This can be used to specify the 504 * dimensions that were set to 0 when the operand was added to the 505 * model. All other values must be the same as specified in the 506 * model. If the type is the same as specified when the model 507 * was built, NULL can be passed. 508 * @param buffer The buffer where the data is to be written. 509 * @param length The length in bytes of the buffer. 510 * 511 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 512 * the name is not recognized or the buffer is too small for the output. 513 */ 514 int (*ANeuralNetworksExecution_setOutput)( 515 ANeuralNetworksExecution* execution, int32_t index, 516 const ANeuralNetworksOperandType* type, void* buffer, size_t length); 517 518 /** 519 * Associate part of a memory object with an output of the model of the 520 * {@link ANeuralNetworksExecution}. 521 * 522 * <p>The provided memory must outlive the execution.</p> 523 * 524 * See {@link ANeuralNetworksExecution} for information on multithreaded 525 * usage. 526 * 527 * @param execution The execution to be modified. 528 * @param index The index of the output argument we are setting. It is 529 * an index into the lists passed to 530 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 531 * not the index associated with {@link 532 * ANeuralNetworksModel_addOperand}. 533 * @param type The type of the operand. This can be used to specify the 534 * dimensions that were set to 0 when the operand was added to the 535 * model. All other values must be the same as specified in the 536 * model. If the type is the same as specified when the model 537 * was built, NULL can be passed. 538 * @param memory The memory where the data is to be stored. 539 * @param offset This specifies the location of the data within the memory. 540 * The offset is in bytes from the start of memory. 541 * @param length The length in bytes of the data value. 542 * 543 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 544 * the name is not recognized or the buffer is too small for the output. 545 */ 546 int (*ANeuralNetworksExecution_setOutputFromMemory)( 547 ANeuralNetworksExecution* execution, int32_t index, 548 const ANeuralNetworksOperandType* type, 549 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 550 551 /** 552 * Schedule evaluation of the execution. 553 * 554 * <p>Schedules evaluation of the execution. Once the model has been 555 * applied and the outputs are ready to be consumed, the execution will be 556 * signaled. Use {@link ANeuralNetworksExecution_wait} to wait for that 557 * signal. 558 * </p> 559 * 560 * Multiple executions can be scheduled and evaluated concurrently, and 561 * compilations can be performed concurrently with executions. The runtime 562 * makes no guarantee on the ordering of the completion of compilations and 563 * executions. If it's important to the application, the application should 564 * enforce the ordering by using {@link ANeuralNetworksCompilation_wait} and 565 * {@link ANeuralNetworksExecution_wait}. 566 * 567 * ANeuralNetworksExecution_wait must be called to recuperate the resources 568 * used by the execution. 569 * 570 * See {@link ANeuralNetworksExecution} for information on multithreaded 571 * usage. 572 * 573 * @param execution The execution to be scheduled and executed. 574 * 575 * @return ANEURALNETWORKS_NO_ERROR if successful. 576 */ 577 int (*ANeuralNetworksExecution_startCompute)( 578 ANeuralNetworksExecution* execution, ANeuralNetworksEvent** event); 579 580 /** 581 * Waits until the execution completes. 582 * 583 * More than one thread can wait on an event. When the execution completes, 584 * all threads will be released. 585 * 586 * See {@link ANeuralNetworksExecution} for information on multithreaded 587 * usage. 588 * 589 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 590 */ 591 int (*ANeuralNetworksEvent_wait)(ANeuralNetworksEvent* event); 592 593 /** 594 * Destroys the event. 595 * 596 * See {@link ANeuralNetworksExecution} for information on multithreaded 597 * usage. 598 */ 599 void (*ANeuralNetworksEvent_free)(ANeuralNetworksEvent* event); 600 601 // ASharedMemory_create was added in Android 8.0, so safe to use with NNAPI 602 // which was added in 8.1. 603 int (*ASharedMemory_create)(const char* name, size_t size); 604 605 /** 606 * Get the number of available devices. 607 * 608 * @param numDevices Used to return the number of devices. 609 * 610 * @return ANEURALNETWORKS_NO_ERROR if successful. 611 * 612 * Available since API level 29. 613 */ 614 int (*ANeuralNetworks_getDeviceCount)(uint32_t* numDevices); 615 616 /** 617 * Get the representation of the specified device. 618 * 619 * @param devIndex The index of the specified device. Must be less than the 620 * number of available devices. 621 * @param device The representation of the specified device. 622 * The same representation will always be returned for the 623 * specified device. 624 * 625 * @return ANEURALNETWORKS_NO_ERROR if successful. 626 * 627 * Available since API level 29. 628 */ 629 630 int (*ANeuralNetworks_getDevice)(uint32_t devIndex, 631 ANeuralNetworksDevice** device); 632 633 /** 634 * Get the name of the specified device. 635 * 636 * @param device The representation of the specified device. 637 * @param name The returned name of the specified device. The name will be 638 * in UTF-8 and will be null-terminated. It will be recognizable 639 * as a known device name rather than a cryptic string. For 640 * devices with API level 29 and above, the format of the name is 641 * {VENDOR}-{DEVICE}, e.g. “google-ipu”. For devices with feature 642 * level 28 or lower, the name will always be “unknown-device”. 643 * The name will remain valid for the duration of the application. 644 * 645 * @return ANEURALNETWORKS_NO_ERROR if successful. 646 * 647 * Available since API level 29. 648 */ 649 int (*ANeuralNetworksDevice_getName)(const ANeuralNetworksDevice* device, 650 const char** name); 651 652 /** 653 * Get the version of the driver implementation of the specified device. 654 * 655 * It’s the responsibility of the driver implementor to insure that this 656 * version string uniquely distinguishes this implementation from all previous 657 * implementations. 658 * 659 * This version string must not be confused with the feature level which is 660 * solely defined by {@link ANeuralNetworksDevice_getFeatureLevel}. There is 661 * no implicit ordering of the versions. For example, it is not possible to 662 * filter all drivers older than a certain version. 663 * 664 * Application developers may use this version string to avoid or prefer 665 * specific driver implementations. For example, an application may want to do 666 * so because: 667 * - A specific version of the driver does not provide the required 668 * performance, perhaps because of a performance regression. 669 * - A specific version of the driver has a bug or returns results that 670 * don’t match the minimum precision requirement for the application. 671 * 672 * @param device The representation of the specified device. 673 * @param version The returned version string of the driver for the specified 674 * device. The string will be in UTF-8 and will be 675 * null-terminated. For devices with feature level 28 or lower, 676 * "UNKNOWN" will be returned. The version string will remain 677 * valid for the duration of the application. 678 * 679 * @return ANEURALNETWORKS_NO_ERROR if successful. 680 * 681 * Available since API level 29. 682 */ 683 int (*ANeuralNetworksDevice_getVersion)(const ANeuralNetworksDevice* device, 684 const char** version); 685 686 /** 687 * Get the supported NNAPI version of the specified device. 688 * 689 * Each device has a supported feature level, which is the most advanced 690 * feature this driver implements. For example, if the driver implements the 691 * features introduced in Android P, but does not implement the features 692 * introduced after Android P, the value would be 28. Developers could decide 693 * whether or not the specified device should be used for a Model that has 694 * certain feature requirements. 695 * 696 * @param device The representation of the specified device. 697 * @param featureLevel The API level of the most advanced feature this driver 698 * implements. 699 * 700 * @return ANEURALNETWORKS_NO_ERROR if successful. 701 * 702 * Available since API level 29. 703 */ 704 int (*ANeuralNetworksDevice_getFeatureLevel)( 705 const ANeuralNetworksDevice* device, int64_t* featureLevel); 706 707 /** 708 * Get the type of a given device. 709 * 710 * The device type can be used to help application developers to distribute 711 * Machine Learning workloads and other workloads such as graphical rendering. 712 * E.g., for an app which renders AR scenes based on real time object 713 * detection results, the developer could choose an ACCELERATOR type device 714 * for ML workloads, and reserve GPU for graphical rendering. 715 * 716 * @param device The representation of the specified device. 717 * @param type The returned {@link DeviceTypeCode} of the specified device. 718 * 719 * @return ANEURALNETWORKS_NO_ERROR if successful. 720 * 721 * Available since API level 29. 722 */ 723 int (*ANeuralNetworksDevice_getType)(const ANeuralNetworksDevice* device, 724 int32_t* type); 725 726 /** 727 * Get the supported operations for a specified set of devices. If multiple 728 * devices are selected, the supported operation list is a union of supported 729 * operations of all selected devices. 730 * 731 * @param model The model to be queried. 732 * @param devices The set of devices. Must not contain duplicates. 733 * @param numDevices The number of devices in the set. 734 * @param supportedOps The boolean array to be filled. True means supported. 735 * The size of the boolean array must be at least as large 736 * as the number of operations in the model. The order of 737 * elements in the supportedOps array matches the order in 738 * which the corresponding operations were added to the 739 * model. 740 * 741 * @return ANEURALNETWORKS_NO_ERROR if successful. 742 * 743 * Available since API level 29. 744 */ 745 int (*ANeuralNetworksModel_getSupportedOperationsForDevices)( 746 const ANeuralNetworksModel* model, 747 const ANeuralNetworksDevice* const* devices, uint32_t numDevices, 748 bool* supportedOps); 749 750 /** 751 * Create a {@link ANeuralNetworksCompilation} to compile the given model for 752 * a specified set of devices. If more than one device is specified, the 753 * compilation will distribute the workload automatically across the devices. 754 * The model must be fully supported by the specified set of devices. This 755 * means that ANeuralNetworksModel_getSupportedOperationsForDevices() must 756 * have returned true for every operation for that model/devices pair. 757 * 758 * @param model The {@link ANeuralNetworksModel} to be compiled. 759 * @param devices The set of devices. Must not contain duplicates. 760 * @param numDevices The number of devices in the set. 761 * @param compilation The newly created object or NULL if unsuccessful. 762 * 763 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 764 * if the model is invalid. 765 * 766 * Available since API level 29. 767 */ 768 int (*ANeuralNetworksCompilation_createForDevices)( 769 ANeuralNetworksModel* model, const ANeuralNetworksDevice* const* devices, 770 uint32_t numDevices, ANeuralNetworksCompilation** compilation); 771 772 /** 773 * Sets the compilation caching signature and the cache directory. 774 * 775 * Provides optional caching information to the runtime for faster repeated 776 * compilation. 777 * 778 * See {@link ANeuralNetworksCompilation} for information on multithreaded 779 * usage. 780 * 781 * @param compilation The compilation to be modified. 782 * @param cacheDir The cache directory to store and retrieve caching data. It 783 * is recommended to use the code_cache provided by the 784 * Android runtime. If not using the code_cache, the user 785 * should choose a directory local to the application, and is 786 * responsible to manage and clean the cache entries. 787 * @param token The token provided by the user to specify a model, must be of 788 * length ANEURALNETWORKS_BYTE_SIZE_OF_CACHE_TOKEN. The user 789 * should ensure that the token is unique to a model within the 790 * application. The NNAPI runtime will not detected token 791 * collisions. If there is a collision, the compilation outcome 792 * may be incorrect without notifying with error. 793 * 794 * @return ANEURALNETWORKS_NO_ERROR if successful. 795 * 796 * Available since API level 29. 797 */ 798 int (*ANeuralNetworksCompilation_setCaching)( 799 ANeuralNetworksCompilation* compilation, const char* cacheDir, 800 const uint8_t* token); 801 802 /** 803 * Set the maximum expected duration for compiling the model. 804 * 805 * If the device is not able to complete the compilation within the specified 806 * duration, the compilation may be aborted. The timeout duration begins at 807 * the call to {@link ANeuralNetworksCompilation_finish}. 808 * 809 * This timeout duration acts as a hint to drivers, and can be used to both 810 * free up compute resources within the driver and return control back to the 811 * application quicker than is possible without the hint. It enables drivers 812 * that are able to estimate how long a compilation will take to abort the 813 * compilation before it has even started if the driver believes the 814 * compilation cannot be completed within the timeout duration. Similarly, it 815 * enables drivers to abort an ongoing compilation if it is taking too long. 816 * However, this call does not guarantee that the compilation will complete or 817 * abort within the timeout duration. 818 * 819 * By default (i.e., unless ANeuralNetworksCompilation_setTimeout is called), 820 * the timeout duration for compiling the model is considered infinite. 821 * 822 * The {@link ANeuralNetworksCompilation} must have been created with 823 * {@link ANeuralNetworksCompilation_createForDevices} with numDevices = 1, 824 * otherwise this function will fail with ANEURALNETWORKS_BAD_DATA. If the 825 * device has a feature level reported by 826 * {@link ANeuralNetworksDevice_getFeatureLevel} that is lower than 30, then 827 * the timeout duration hint will be ignored. 828 * 829 * See {@link ANeuralNetworksCompilation} for information on multithreaded 830 * usage. 831 * 832 * @param compilation The compilation to be modified. 833 * @param duration The maximum amount of time in nanoseconds that is expected 834 * to be spent finishing a compilation. If this duration is exceeded, the 835 * compilation may be aborted. If set to 0, the timeout duration is 836 * considered infinite. 837 * 838 * @return ANEURALNETWORKS_NO_ERROR if successful. 839 * 840 * Available since API level 30. 841 */ 842 int (*ANeuralNetworksCompilation_setTimeout)( 843 ANeuralNetworksCompilation* compilation, uint64_t duration); 844 845 /** 846 * Set the execution priority. 847 * 848 * Execution priorities are relative to other executions created by the same 849 * application (specifically same uid) for the same device. Specifically, 850 * priorities of executions from one application will not affect executions 851 * from another application. Similarly, priorities of executions on one device 852 * will not affect executions on another device. 853 * 854 * Higher priority executions may use more compute resources than lower 855 * priority executions, and may preempt or starve lower priority executions. 856 * 857 * See {@link ANeuralNetworksCompilation} for information on multithreaded 858 * usage. 859 * 860 * Available since API level 30. 861 * 862 * @param compilation The compilation to be modified. 863 * @param priority The relative priority of the execution compared to other 864 * executions created by the application. Must be one of 865 * ANEURALNETWORKS_PRIORITY_*. 866 * 867 * @return ANEURALNETWORKS_NO_ERROR if successful. 868 */ 869 int (*ANeuralNetworksCompilation_setPriority)( 870 ANeuralNetworksCompilation* compilation, int priority); 871 872 /** 873 * Schedule synchronous evaluation of the execution. 874 * 875 * <p>Schedules synchronous evaluation of the execution. Returns once the 876 * execution has completed and the outputs are ready to be consumed. 877 * </p> 878 * 879 * See {@link ANeuralNetworksExecution} for information on multithreaded 880 * usage. 881 * 882 * See {@link ANeuralNetworksExecution_startCompute} for asynchronous 883 * execution. Synchronous execution incurs lower overhead than asynchronous 884 * execution. 885 * 886 * Available since API level 29. 887 * 888 * @param execution The execution to be scheduled and executed. 889 * 890 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 891 * ANEURALNETWORKS_UNMAPPABLE if the execution input or output memory 892 * cannot be properly mapped. 893 */ 894 int (*ANeuralNetworksExecution_compute)(ANeuralNetworksExecution* execution); 895 896 /** 897 * Set the maximum expected duration of the specified execution. 898 * 899 * If the device is not able to complete the execution within the specified 900 * duration, the execution may be aborted. The timeout duration begins at a 901 * call to one of: 902 * - {@link ANeuralNetworksExecution_burstCompute} 903 * - {@link ANeuralNetworksExecution_compute} 904 * - {@link ANeuralNetworksExecution_startCompute} 905 * - {@link ANeuralNetworksExecution_startComputeWithDependencies} 906 * 907 * This timeout duration acts as a hint to drivers, and can be used to both 908 * free up compute resources within the driver and return control back to the 909 * application quicker than is possible without the hint. It enables drivers 910 * that are able to estimate how long an execution will take to abort the 911 * execution before it has even started if the driver believes the execution 912 * cannot be completed within the timeout duration. Similarly, it enables 913 * drivers to abort an ongoing execution if it is taking too long. However, 914 * this call does not guarantee that the execution will complete or abort 915 * within the timeout duration. 916 * 917 * By default (i.e., unless ANeuralNetworksExecution_setTimeout is called), 918 * the timeout duration for execution is considered infinite. 919 * 920 * The {@link ANeuralNetworksExecution} must have been created from an 921 * {@link ANeuralNetworksCompilation} which in turn was created from 922 * {@link ANeuralNetworksCompilation_createForDevices} with numDevices = 1, 923 * otherwise this function will fail with ANEURALNETWORKS_BAD_DATA. If the 924 * device has a feature level reported by 925 * {@link ANeuralNetworksDevice_getFeatureLevel} that is lower than 30, then 926 * the timeout duration hint will be ignored. 927 * 928 * See {@link ANeuralNetworksExecution} for information on multithreaded 929 * usage. 930 * 931 * @param execution The execution to be modified. 932 * @param duration The maximum amount of time in nanoseconds that is expected 933 * to be spent executing a model. If this duration is exceeded, the execution 934 * may be aborted. If set to 0, the timeout duration is considered 935 * infinite. 936 * 937 * @return ANEURALNETWORKS_NO_ERROR if successful. 938 * 939 * Available since API level 30. 940 */ 941 int (*ANeuralNetworksExecution_setTimeout)( 942 ANeuralNetworksExecution* execution, uint64_t duration); 943 944 /** 945 * Set the maximum duration of WHILE loops in the specified execution. 946 * 947 * This is a fuzzy per-loop timeout intended to prevent infinite loops. 948 * 949 * If a WHILE loop condition model does not output false within the specified 950 * duration, the execution will be aborted. 951 * 952 * See {@link ANeuralNetworks_getDefaultLoopTimeout} and 953 * {@link ANeuralNetworks_getMaximumLoopTimeout} for the default 954 * and maximum timeout values. 955 * 956 * See {@link ANeuralNetworksExecution} for information on multithreaded 957 * usage. 958 * 959 * @param execution The execution to be modified. 960 * @param duration The maximum amount of time in nanoseconds that can be spent 961 * executing a WHILE loop. If the specified duration value exceeds the 962 * value produced by {@link ANeuralNetworks_getMaximumLoopTimeout}, it will be 963 * overridden by that value. 964 * 965 * @return ANEURALNETWORKS_NO_ERROR if successful. 966 * ANEURALNETWORKS_BAD_STATE if execution has started. 967 * ANEURALNETWORKS_UNEXPECTED_NULL if execution is NULL. 968 * 969 * Available since API level 30. 970 */ 971 int (*ANeuralNetworksExecution_setLoopTimeout)( 972 ANeuralNetworksExecution* execution, uint64_t duration); 973 974 /** 975 * Get the dimensional information of the specified output operand of the 976 * model of the 977 * {@link ANeuralNetworksExecution}. 978 * 979 * On asynchronous execution initiated by {@link 980 * ANeuralNetworksExecution_startCompute}, 981 * {@link ANeuralNetworksEvent_wait} must be called prior to this function to 982 * recuperate the resources used by the execution. 983 * 984 * @param execution The execution to be queried. 985 * @param index The index of the output argument we are querying. It is 986 * an index into the lists passed to 987 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 988 * not the index associated with 989 * {@link ANeuralNetworksModel_addOperand}. 990 * @param rank The rank of the output operand. 991 * 992 * @return ANEURALNETWORKS_NO_ERROR if successful, 993 * ANEURALNETWORKS_OUTPUT_INSUFFICIENT_SIZE if the target output is 994 * provided an insufficient buffer at execution time, 995 * ANEURALNETWORKS_BAD_DATA if the index is invalid. 996 * 997 * Available since API level 29. 998 */ 999 int (*ANeuralNetworksExecution_getOutputOperandRank)( 1000 ANeuralNetworksExecution* execution, int32_t index, uint32_t* rank); 1001 1002 /** 1003 * Get the dimensional information of the specified output operand of the 1004 * model of the 1005 * {@link ANeuralNetworksExecution}. The target output operand cannot be a 1006 * scalar. 1007 * 1008 * On asynchronous execution initiated by {@link 1009 * ANeuralNetworksExecution_startCompute}, 1010 * {@link ANeuralNetworksEvent_wait} must be called prior to this function to 1011 * recuperate the resources used by the execution. 1012 * 1013 * @param execution The execution to be queried. 1014 * @param index The index of the output argument we are querying. It is an 1015 * index into the lists passed to 1016 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 1017 * not the index associated with 1018 * {@link ANeuralNetworksModel_addOperand}. 1019 * @param dimensions The dimension array to be filled. The size of the array 1020 * must be exactly as large as the rank of the output 1021 * operand to be queried in the model. 1022 * 1023 * @return ANEURALNETWORKS_NO_ERROR if successful, 1024 * ANEURALNETWORKS_OUTPUT_INSUFFICIENT_SIZE if the target output is 1025 * provided an insufficient buffer at execution time, 1026 * ANEURALNETWORKS_BAD_DATA if the index is invalid or if the target 1027 * is a scalar. 1028 * 1029 * Available since API level 29. 1030 */ 1031 int (*ANeuralNetworksExecution_getOutputOperandDimensions)( 1032 ANeuralNetworksExecution* execution, int32_t index, uint32_t* dimensions); 1033 1034 /** 1035 * Create a {@link ANeuralNetworksBurst} to apply the given compilation. 1036 * This only creates the burst object. Computation is only performed once 1037 * {@link ANeuralNetworksExecution_burstCompute} is invoked with a valid 1038 * {@link ANeuralNetworksExecution} and {@link ANeuralNetworksBurst}. 1039 * 1040 * <p>The provided compilation must outlive the burst object.</p> 1041 * 1042 * Available since API level 29. 1043 * 1044 * @param compilation The {@link ANeuralNetworksCompilation} to be evaluated. 1045 * @param burst The newly created object or NULL if unsuccessful. 1046 * 1047 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 1048 * if the compilation is invalid. 1049 */ 1050 int (*ANeuralNetworksBurst_create)(ANeuralNetworksCompilation* compilation, 1051 ANeuralNetworksBurst** burst); 1052 1053 /** 1054 * Destroys the burst object. 1055 * 1056 * Available since API level 29. 1057 * 1058 * @param burst The burst object to be destroyed. Passing NULL is acceptable 1059 * and results in no operation. 1060 */ 1061 void (*ANeuralNetworksBurst_free)(ANeuralNetworksBurst* burst); 1062 1063 /** 1064 * Schedule synchronous evaluation of the execution on a burst object. 1065 * 1066 * <p>Schedules synchronous evaluation of the execution. Returns once the 1067 * execution has completed and the outputs are ready to be consumed.</p> 1068 * 1069 * <p>There must be at most one {@link ANeuralNetworksExecution} processing at 1070 * any given time for any given burst object. Any 1071 * {@link ANeuralNetworksExecution} launched before the previous has finished 1072 * will result in ANEURALNETWORKS_BAD_STATE.</p> 1073 * 1074 * Available since API level 29. 1075 * 1076 * @param burst The burst object to execute on. 1077 * @param execution The execution to be scheduled and executed. The execution 1078 * must be created from the same {@link 1079 * ANeuralNetworksCompilation} as the burst object. 1080 * 1081 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 1082 */ 1083 int (*ANeuralNetworksExecution_burstCompute)( 1084 ANeuralNetworksExecution* execution, ANeuralNetworksBurst* burst); 1085 1086 /** 1087 * Creates a shared memory object from an AHardwareBuffer handle. 1088 * 1089 * If the shared memory is backed by an AHardwareBuffer of 1090 * AHARDWAREBUFFER_FORMAT_BLOB format, it can be used the same way as 1091 * shared memory created from a file handle. See 1092 * {@link ANeuralNetworksMemory} for a description on how to use this 1093 * shared memory. 1094 * 1095 * If the shared memory is backed by an AHardwareBuffer of a format other 1096 * than AHARDWAREBUFFER_FORMAT_BLOB, it can only be used for Model inputs 1097 * and outputs. When calling 1098 * {@link ANeuralNetworksExecution_setInputFromMemory} or 1099 * {@link ANeuralNetworksExecution_setOutputFromMemory} with the shared 1100 * memory, both offset and length must be set to zero and the entire 1101 * memory region will be associated with the specified input or output 1102 * operand. There is no guarantee that an arbitrary AHardwareBuffer_Format 1103 * and AHardwareBuffer_UsageFlags combination can be used by arbitrary 1104 * devices. The execution will fail if selected set of devices cannot 1105 * consume the buffer. 1106 * 1107 * Calling {@link ANeuralNetworksModel_setOperandValueFromMemory} with 1108 * shared memory backed by an AHardwareBuffer of a format other than 1109 * AHARDWAREBUFFER_FORMAT_BLOB is disallowed. 1110 * 1111 * TODO(miaowang): add documentation about intended usage with 1112 * introspection API. 1113 * 1114 * Available since API level 29. 1115 * 1116 * @param ahwb The AHardwareBuffer handle. 1117 * @param memory The memory object to be created. 1118 * Set to NULL if unsuccessful. 1119 * 1120 * @return ANEURALNETWORKS_NO_ERROR if the request completed normally. 1121 * 1122 * @see AHardwareBuffer 1123 */ 1124 int (*ANeuralNetworksMemory_createFromAHardwareBuffer)( 1125 const AHardwareBuffer* ahwb, ANeuralNetworksMemory** memory); 1126 1127 /** 1128 * Specifies whether duration of the {@link ANeuralNetworksExecution} is to be 1129 * measured. By default, duration is not measured. 1130 * 1131 * The {@link ANeuralNetworksExecution} must have been created with 1132 * {@link ANeuralNetworksCompilation_createForDevices} with numDevices = 1. 1133 * 1134 * See {@link ANeuralNetworksExecution} for information on multithreaded 1135 * usage. 1136 * 1137 * Available since API level 29. 1138 * 1139 * @param execution The execution to be modified. 1140 * @param measure 'true' if duration is to be measured, 'false' if not. 1141 * 1142 * @return ANEURALNETWORKS_NO_ERROR if successful. 1143 */ 1144 int (*ANeuralNetworksExecution_setMeasureTiming)( 1145 ANeuralNetworksExecution* execution, bool measure); 1146 1147 /** 1148 * Get the time spent in the specified {@link ANeuralNetworksExecution}, in 1149 * nanoseconds. The execution must have completed. 1150 * 1151 * @param execution The execution to be queried. 1152 * @param durationCode The measurement to be queried, specified by {@link 1153 * DurationCode}. 1154 * @param duration The returned duration. If no measurement was requested by 1155 * {@link ANeuralNetworksExecution_setMeasureTiming}, or for 1156 * some other reason the duration is not available, UINT64_MAX will be 1157 * returned. A particular device need not support any given measurement. 1158 * 1159 * @return ANEURALNETWORKS_NO_ERROR if successful. 1160 */ 1161 int (*ANeuralNetworksExecution_getDuration)( 1162 const ANeuralNetworksExecution* execution, int32_t durationCode, 1163 uint64_t* duration); 1164 1165 /** 1166 * Queries whether an extension is supported by the driver implementation of 1167 * the specified device. 1168 * 1169 * @param device The representation of the specified device. 1170 * @param extension The extension name. 1171 * @param isExtensionSupported The boolean value indicating whether the 1172 * extension is supported. 1173 * 1174 * @return ANEURALNETWORKS_NO_ERROR if successful. 1175 * 1176 * Available since API level 29. 1177 */ 1178 int (*ANeuralNetworksDevice_getExtensionSupport)( 1179 const ANeuralNetworksDevice* device, const char* extensionName, 1180 bool* isExtensionSupported); 1181 1182 /** 1183 * Creates an operand type from an extension name and an extension operand 1184 * code. 1185 * 1186 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 1187 * 1188 * Available since API level 29. 1189 * 1190 * @param model The model to contain the operand. 1191 * @param extensionName The extension name. 1192 * @param operandCodeWithinExtension The extension operand code. 1193 * @param type The operand type. 1194 * 1195 * @return ANEURALNETWORKS_NO_ERROR if successful. 1196 */ 1197 int (*ANeuralNetworksModel_getExtensionOperandType)( 1198 ANeuralNetworksModel* model, const char* extensionName, 1199 uint16_t operandCodeWithinExtension, int32_t* type); 1200 1201 /** 1202 * Creates an operation type from an extension name and an extension operation 1203 * code. 1204 * 1205 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 1206 * 1207 * Available since API level 29. 1208 * 1209 * @param model The model to contain the operation. 1210 * @param extensionName The extension name. 1211 * @param operationCodeWithinExtension The extension operation code. 1212 * @param type The operation type. 1213 * 1214 * @return ANEURALNETWORKS_NO_ERROR if successful. 1215 */ 1216 int (*ANeuralNetworksModel_getExtensionOperationType)( 1217 ANeuralNetworksModel* model, const char* extensionName, 1218 uint16_t operationCodeWithinExtension, 1219 ANeuralNetworksOperationType* type); 1220 1221 /** 1222 * Sets extension operand parameters. 1223 * 1224 * Available since API level 29. 1225 * 1226 * @param model The model to be modified. 1227 * @param index The index of the model operand we're setting. 1228 * @param data A pointer to the extension operand data. 1229 * The data does not have to outlive the call to this function. 1230 * @param length The size in bytes of the data value. 1231 * 1232 * @return ANEURALNETWORKS_NO_ERROR if successful. 1233 */ 1234 int (*ANeuralNetworksModel_setOperandExtensionData)( 1235 ANeuralNetworksModel* model, int32_t index, const void* data, 1236 size_t length); 1237 1238 /** 1239 * Create a {@link ANeuralNetworksMemoryDesc} with no properties. 1240 * 1241 * This only creates the memory descriptor. Its properties should be set with 1242 * calls to 1243 * {@link ANeuralNetworksMemoryDesc_addInputRole}, 1244 * {@link ANeuralNetworksMemoryDesc_addOutputRole}, and 1245 * {@link ANeuralNetworksMemoryDesc_setDimensions}. 1246 * 1247 * {@link ANeuralNetworksMemoryDesc_finish} must be called once all properties 1248 * have been set. 1249 * 1250 * {@link ANeuralNetworksMemoryDesc_free} must be called once the memory 1251 * descriptor is no longer needed. 1252 * 1253 * Available since API level 30. 1254 * 1255 * @param desc The {@link ANeuralNetworksMemoryDesc} to be created. 1256 * Set to NULL if unsuccessful. 1257 * 1258 * @return ANEURALNETWORKS_NO_ERROR if successful. 1259 */ 1260 int (*ANeuralNetworksMemoryDesc_create)(ANeuralNetworksMemoryDesc** desc); 1261 1262 /** 1263 * Destroy a memory descriptor. 1264 * 1265 * The memory descriptor need not have been finished by a call to 1266 * {@link ANeuralNetworksMemoryDesc_finish}. 1267 * 1268 * See {@link ANeuralNetworksMemoryDesc} for information on multithreaded 1269 * usage. 1270 * 1271 * Available since API level 30. 1272 * 1273 * @param desc The memory descriptor to be destroyed. Passing NULL is 1274 * acceptable and results in no operation. 1275 */ 1276 void (*ANeuralNetworksMemoryDesc_free)(ANeuralNetworksMemoryDesc* desc); 1277 1278 /** 1279 * Specify that a memory object will be playing the role of an input to an 1280 * execution created from a particular compilation. 1281 * 1282 * The compilation and the input index fully specify an input operand. This 1283 * function may be invoked multiple times on the same memory descriptor with 1284 * different input operands, and the same input operand may be specified on 1285 * multiple memory descriptors. However, specifying the same input operand on 1286 * the same memory descriptor more than once will return an error. 1287 * 1288 * The dimensions of the corresponding model operands of all the roles 1289 * specified by 1290 * {@link ANeuralNetworksMemoryDesc_addInputRole} and 1291 * {@link ANeuralNetworksMemoryDesc_addOutputRole} must be compatible with 1292 * each other. Two dimensions are incompatible if both ranks are fully 1293 * specified but have different values, or if there is at least one axis that 1294 * is fully specified in both but has different values. 1295 * 1296 * At least one of {@link ANeuralNetworksMemoryDesc_addInputRole} and 1297 * {@link ANeuralNetworksMemoryDesc_addOutputRole} must be called on a memory 1298 * descriptor before invoking {@link ANeuralNetworksMemoryDesc_finish}. 1299 * 1300 * Attempting to modify a memory descriptor once 1301 * {@link ANeuralNetworksMemoryDesc_finish} has been called will return an 1302 * error. 1303 * 1304 * See {@link ANeuralNetworksMemoryDesc} for information on multithreaded 1305 * usage. 1306 * 1307 * Available since API level 30. 1308 * 1309 * @param desc The memory descriptor to be modified. 1310 * @param compilation The compilation object. It must already have been 1311 * finished by calling {@link ANeuralNetworksCompilation_finish}, and must 1312 * outlive the memory descriptor. 1313 * @param index The index of the input argument we are referencing from the 1314 * compilation. It is an index into the inputs list passed to 1315 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 1316 * not the index associated with {@link ANeuralNetworksModel_addOperand}. 1317 * @param frequency A floating-point value within the range (0.0, 1.0]. 1318 * Describes how likely the memory is to be used in the specified role. This 1319 * is provided as a hint to optimize the case when different roles prefer 1320 * different memory locations or data layouts. 1321 * 1322 * @return ANEURALNETWORKS_NO_ERROR if successful. 1323 */ 1324 int (*ANeuralNetworksMemoryDesc_addInputRole)( 1325 ANeuralNetworksMemoryDesc* desc, 1326 const ANeuralNetworksCompilation* compilation, uint32_t index, 1327 float frequency); 1328 1329 /** 1330 * Specify that a memory object will be playing the role of an output to an 1331 * execution created from a particular compilation. 1332 * 1333 * The compilation and the output index fully specify an output operand. This 1334 * function may be invoked multiple times on the same memory descriptor with 1335 * different output operands, and the same output operand may be specified on 1336 * multiple memory descriptors. However, specifying the same output operand on 1337 * the same memory descriptor object more than once will return an error. 1338 * 1339 * The dimensions of the corresponding model operands of all the roles 1340 * specified by 1341 * {@link ANeuralNetworksMemoryDesc_addInputRole} and 1342 * {@link ANeuralNetworksMemoryDesc_addOutputRole} must be compatible with 1343 * each other. Two dimensions are incompatible if both ranks are fully 1344 * specified but have different values, or if there is at least one axis that 1345 * is fully specified in both but has different values. 1346 * 1347 * At least one of {@link ANeuralNetworksMemoryDesc_addInputRole} and 1348 * {@link ANeuralNetworksMemoryDesc_addOutputRole} must be called on the 1349 * memory descriptor before invoking {@link ANeuralNetworksMemoryDesc_finish}. 1350 * 1351 * Attempting to modify a memory descriptor once 1352 * {@link ANeuralNetworksMemoryDesc_finish} has been called will return an 1353 * error. 1354 * 1355 * See {@link ANeuralNetworksMemoryDesc} for information on multithreaded 1356 * usage. 1357 * 1358 * Available since API level 30. 1359 * 1360 * @param desc The memory descriptor to be modified. 1361 * @param compilation The compilation object. It must already have been 1362 * finished by calling {@link ANeuralNetworksCompilation_finish}, and must 1363 * outlive the memory descriptor. 1364 * @param index The index of the output argument we are referencing from the 1365 * compilation. It is an index into the outputs list passed to 1366 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 1367 * not the index associated with {@link ANeuralNetworksModel_addOperand}. 1368 * @param frequency A floating-point value within the range (0.0, 1.0]. 1369 * Describes how likely the memory is to be used in the specified role. This 1370 * is provided as a hint to optimize the case when multiple roles prefer 1371 * different memory locations or data layouts. 1372 * 1373 * @return ANEURALNETWORKS_NO_ERROR if successful. 1374 */ 1375 int (*ANeuralNetworksMemoryDesc_addOutputRole)( 1376 ANeuralNetworksMemoryDesc* desc, 1377 const ANeuralNetworksCompilation* compilation, uint32_t index, 1378 float frequency); 1379 1380 /** 1381 * Set the dimensional information of the memory descriptor. 1382 * 1383 * The specified dimensions must be compatible with the dimensions of the 1384 * corresponding model operands of all the roles specified by 1385 * {@link ANeuralNetworksMemoryDesc_addInputRole} and 1386 * {@link ANeuralNetworksMemoryDesc_addOutputRole}. Two dimensions are 1387 * incompatible if both ranks are fully specified but have different values, 1388 * or if there is at least one axis that is fully specified in both but has 1389 * different values. 1390 * 1391 * Attempting to modify a memory descriptor once 1392 * {@link ANeuralNetworksMemoryDesc_finish} has been called will return an 1393 * error. 1394 * 1395 * See {@link ANeuralNetworksMemoryDesc} for information on multithreaded 1396 * usage. 1397 * 1398 * Available since API level 30. 1399 * 1400 * @param desc The memory descriptor to be modified. 1401 * @param rank The number of dimensions. Must be 0 for scalars. 1402 * @param dimensions An array of dimensions. An entry with the value 0 1403 * indicates that the corresponding axis has an unknown size. 1404 * 1405 * @return ANEURALNETWORKS_NO_ERROR if successful. 1406 */ 1407 int (*ANeuralNetworksMemoryDesc_setDimensions)( 1408 ANeuralNetworksMemoryDesc* desc, uint32_t rank, 1409 const uint32_t* dimensions); 1410 1411 /** 1412 * Indicate that we have finished modifying a memory descriptor. Required 1413 * before calling 1414 * {@link ANeuralNetworksMemory_createFromDesc}. 1415 * 1416 * This function must only be called once for a given memory descriptor. 1417 * 1418 * See {@link ANeuralNetworksMemoryDesc} for information on multithreaded 1419 * usage. 1420 * 1421 * Available since API level 30. 1422 * 1423 * @param desc The memory descriptor to be finished. 1424 * 1425 * @return ANEURALNETWORKS_NO_ERROR if successful. 1426 */ 1427 int (*ANeuralNetworksMemoryDesc_finish)(ANeuralNetworksMemoryDesc* desc); 1428 1429 /** 1430 * Creates a memory object from a memory descriptor. 1431 * 1432 * The memory object is created with an uninitialized buffer. A memory object 1433 * with an uninitialized buffer may only be used according to the roles 1434 * specified by 1435 * {@link ANeuralNetworksMemoryDesc_addOutputRole}, or as the destination 1436 * memory in 1437 * {@link ANeuralNetworksMemory_copy}. The buffer of a memory object is 1438 * initialized after the memory object is used as an output in a successful 1439 * execution, or used as the destination memory in a successful {@link 1440 * ANeuralNetworksMemory_copy}. A memory object with an initialized buffer may 1441 * be used according to all roles specified in 1442 * {@link ANeuralNetworksMemoryDesc}, or as the source or destination memory 1443 * in 1444 * {@link ANeuralNetworksMemory_copy}. The buffer of a memory object will 1445 * return to the uninitialized state if the memory object is used as an output 1446 * in a failed execution, or used as the destination memory in a failed {@link 1447 * ANeuralNetworksMemory_copy}. 1448 * 1449 * The dimensions of the memory descriptor are deduced from the dimensions of 1450 * the corresponding model operands of all the roles specified by 1451 * {@link ANeuralNetworksMemoryDesc_addInputRole} and 1452 * {@link ANeuralNetworksMemoryDesc_addOutputRole}, as well as the dimensions 1453 * set by the call to {@link ANeuralNetworksMemoryDesc_setDimensions}, if any. 1454 * The memory descriptor may have unspecified dimensions or rank. In such a 1455 * case, the same memory object may be used with different shapes of outputs 1456 * in different executions. When the memory is used as an input, the input 1457 * shape must be the same as the output shape from the last execution using 1458 * this memory object as an output, or the last 1459 * {@link ANeuralNetworkMemory_copy} using this memory object as the 1460 * destination memory. Creating a memory object with unspecified dimensions or 1461 * rank may fail for certain sets of roles. 1462 * 1463 * Using the memory in roles or shapes that are not compatible with the rules 1464 * specified above will return an error. 1465 * 1466 * When calling {@link ANeuralNetworksExecution_setInputFromMemory} or 1467 * {@link ANeuralNetworksExecution_setOutputFromMemory} with the memory 1468 * object, both offset and length must be set to zero and the entire memory 1469 * region will be associated with the specified input or output operand. 1470 * 1471 * Calling {@link ANeuralNetworksModel_setOperandValueFromMemory} with the 1472 * memory created from this function will return an error. 1473 * 1474 * {@link ANeuralNetworksMemory_free} must be called once the memory is no 1475 * longer needed. 1476 * 1477 * Attempting to create memory from an unfinished memory descriptor will 1478 * return an error. 1479 * 1480 * The provided {@link ANeuralNetworksMemoryDesc} need not outlive the 1481 * {@link ANeuralNetworksMemory} object. 1482 * 1483 * Available since API level 30. 1484 * 1485 * @param desc The memory descriptor. 1486 * @param memory The memory object to be created. 1487 * Set to NULL if unsuccessful. 1488 * 1489 * @return ANEURALNETWORKS_NO_ERROR if successful; ANEURALNETWORKS_OP_FAILED 1490 * if the memory is created with unspecified dimensions or rank and it is not 1491 * supported for this set of roles. 1492 */ 1493 int (*ANeuralNetworksMemory_createFromDesc)( 1494 const ANeuralNetworksMemoryDesc* desc, ANeuralNetworksMemory** memory); 1495 1496 /** 1497 * Copies data from one memory object to another. 1498 * 1499 * If at most one of the src and dst is created from 1500 * {@link ANeuralNetworksMemory_createFromDesc}, the src and dst must have the 1501 * same logical size: 1502 * - If the memory is created from {@link ANeuralNetworksMemory_createFromFd}, 1503 * or if it is created from {@link 1504 * ANeuralNetworksMemory_createFromAHardwareBuffer} with format of 1505 * AHARDWAREBUFFER_FORMAT_BLOB, the logical size equals the size of the 1506 * memory. 1507 * - If the memory is created from 1508 * {@link ANeuralNetworksMemory_createFromAHardwareBuffer} with a format 1509 * other than AHARDWAREBUFFER_FORMAT_BLOB, the logical size equals the size 1510 * when there is no padding and the data is tightly packed. This function may 1511 * fail if the AHardwareBuffer cannot be accessed. 1512 * - If the memory is created from {@link 1513 * ANeuralNetworksMemory_createFromDesc}, the logical size equals the size 1514 * indicated by the {@link OperandCode} multiplied by the number of elements. 1515 * This function will fail if the number of elements is unknown. 1516 * 1517 * If both src and dst are created from {@link 1518 * ANeuralNetworksMemory_createFromDesc}, they must have compatible 1519 * dimensions. Two dimensions are incompatible if both ranks are fully 1520 * specified but have different values, or if there is at least one axis that 1521 * is fully specified in both but has different values. The dst may have 1522 * unspecified dimensions or rank. In such a case, the dimensions of dst will 1523 * get updated according to the dimensions of the src. 1524 * 1525 * In both cases, if the src is created from 1526 * {@link ANeuralNetworksMemory_createFromDesc}, it must have been used as an 1527 * output in a successful execution, or used as the destination memory in a 1528 * successful 1529 * {@link ANeuralNetworksMemory_copy}. 1530 * 1531 * The src and dst may have different data layout, in which case the data 1532 * copying is performed logically with data layout transformation. 1533 * 1534 * Available since API level 30. 1535 * 1536 * @param src The source memory object. 1537 * @param dst The destination memory object. 1538 * 1539 * @return ANEURALNETWORKS_NO_ERROR if successful. 1540 */ 1541 int (*ANeuralNetworksMemory_copy)(const ANeuralNetworksMemory* src, 1542 const ANeuralNetworksMemory* dst); 1543 1544 /** 1545 * Create a {@link ANeuralNetworksEvent} from a sync_fence file descriptor. 1546 * 1547 * The newly created ANeuralNetworksEvent does not take ownership of the 1548 * provided sync_fence_fd, it will instead dup the provided sync_fence_fd and 1549 * own the duplicate. 1550 * 1551 * @param sync_fence_fd The sync_fence file descriptor. 1552 * @param event The newly created object or NULL if unsuccessful. 1553 * 1554 * @return ANEURALNETWORKS_NO_ERROR if successful. 1555 * 1556 * Available since API level 30. 1557 */ 1558 int (*ANeuralNetworksEvent_createFromSyncFenceFd)( 1559 int sync_fence_fd, ANeuralNetworksEvent** event); 1560 1561 /** 1562 * Get sync_fence file descriptor from the event. 1563 * 1564 * If the ANeuralNetworksEvent is not backed by a sync fence, the 1565 * sync_fence_fd will be set to -1, and ANEURALNETWORKS_BAD_DATA will be 1566 * returned. 1567 * 1568 * See {@link ANeuralNetworksEvent_createFromSyncFenceFd} and 1569 * {@link ANeuralNetworksExecution_startComputeWithDependencies} to see how to 1570 * create an event backed by a sync fence. 1571 * 1572 * The user takes ownership of the returned fd, and must close the returned 1573 * file descriptor when it is no longer needed. 1574 * 1575 * @param event An event that is backed by a sync fence. 1576 * @param sync_fence_fd The sync_fence file descriptor. The file descriptor 1577 * will be set to -1 if there is an error. 1578 * 1579 * @return ANEURALNETWORKS_NO_ERROR if successful. 1580 * 1581 * Available since API level 30. 1582 */ 1583 int (*ANeuralNetworksEvent_getSyncFenceFd)(const ANeuralNetworksEvent* event, 1584 int* sync_fence_fd); 1585 1586 /** 1587 * Schedule asynchronous evaluation of the execution with dependencies. 1588 * 1589 * The execution will wait for all the depending events to be signaled before 1590 * starting the evaluation. Once the execution has completed and the outputs 1591 * are ready to be consumed, the returned event will be signaled. Depending on 1592 * which devices are handling the execution, the event could be backed by a 1593 * sync fence. Use {@link ANeuralNetworksEvent_wait} to wait for that event. 1594 * 1595 * ANeuralNetworksEvent_wait must be called to recurperate the resources used 1596 * by the execution. 1597 * 1598 * If parts of the execution are scheduled on devices that do not support 1599 * fenced execution, the function call may wait for such parts to finish 1600 * before returning. 1601 * 1602 * The function will return an error if any of the events in dependencies is 1603 * already in a bad state. After the execution is scheduled, if any of the 1604 * events in dependencies does not complete normally, the execution will fail, 1605 * and {@link ANeuralNetworksEvent_wait} on the returned event will return an 1606 * error. 1607 * 1608 * The function will return an error if any of the execution outputs has a 1609 * tensor operand type that is not fully specified. 1610 * 1611 * The function can be passed a timeout duration in nanoseconds. This timeout 1612 * duration acts as a hint to drivers in the same way that the timeout 1613 * durations in {@link ANeuralNetworksCompilation_setTimeout} and {@link 1614 * ANeuralNetworksExecution_setTimeout} act as hints to drivers. The duration 1615 * begins when all waitFor sync fences have been signaled, and can be used 1616 * together with {@link ANeuralNetworksExecution_setTimeout} which specifies 1617 * the maximum timeout duration beginning at the call to 1618 * {@link ANeuralNetworksExecution_startComputeWithDependencies}. 1619 * If the duration is non-zero, the {@link ANeuralNetworksExecution} must have 1620 * been created from an {@link ANeuralNetworksCompilation} which in turn was 1621 * created from 1622 * {@link ANeuralNetworksCompilation_createForDevices} with numDevices = 1, 1623 * otherwise this function will fail with ANEURALNETWORKS_BAD_DATA. If either 1624 * the timeout duration from {@link ANeuralNetworksExecution_setTimeout} or 1625 * the timeout duration passed to this call is exceeded, the execution may be 1626 * aborted, in which case {@link ANEURALNETWORKS_MISSED_DEADLINE_*} will be 1627 * returned through {@link 1628 * ANeuralNetworksExecution_startComputeWithDependencies} or {@link 1629 * ANeuralNetworksEvent_wait} on the event object. If the device has a feature 1630 * level reported by {@link ANeuralNetworksDevice_getFeatureLevel} that is 1631 * lower than 30, then the timeout duration hints will be ignored. 1632 * 1633 * If this execution contains a {@link ANEURALNETWORKS_WHILE} operation, and 1634 * the condition model does not output false within the loop timeout duration, 1635 * then execution will be aborted and {@link 1636 * ANEURALNETWORKS_MISSED_DEADLINE_*} will be returned through {@link 1637 * ANeuralNetworksEvent_wait} on the event object. 1638 * 1639 * See {@link ANeuralNetworksExecution} for information on multithreaded 1640 * usage. 1641 * 1642 * See {@link ANeuralNetworksExecution_compute} for synchronous execution. 1643 * See {@link ANeuralNetworksExecution_burstCompute} for burst synchronous 1644 * execution. See {@link ANeuralNetworksExecution_startCompute} for regular 1645 * asynchronous execution. 1646 * 1647 * @param execution The execution to be scheduled and executed. 1648 * @param dependencies A set of depending events. The actual evaluation will 1649 * not start until all the events are signaled. 1650 * @param num_dependencies The number of events in the dependencies set. 1651 * @param duration The maximum amount of time in nanoseconds that is expected 1652 * to be spent executing the model after all dependencies are signaled. If set 1653 * to 0, the timeout duration is considered infinite. 1654 * @param event The event that will be signaled on completion. event is set to 1655 * NULL if there's an error. 1656 * 1657 * @return ANEURALNETWORKS_NO_ERROR if the evaluation is successfully 1658 * scheduled. 1659 * 1660 * Available since API level 30. 1661 */ 1662 int (*ANeuralNetworksExecution_startComputeWithDependencies)( 1663 ANeuralNetworksExecution* execution, 1664 const ANeuralNetworksEvent* const* dependencies, 1665 uint32_t num_dependencies, uint64_t duration, 1666 ANeuralNetworksEvent** event); 1667 1668 /** 1669 * Specifies whether the {@link ANeuralNetworksExecution} is able to accept 1670 * padded input and output buffers and memory objects. 1671 * 1672 * By default, the input and output buffers and memory objects of {@link 1673 * ANeuralNetworksExecution} do not allow padding. 1674 * 1675 * Setting the execution to accept padded input and output buffers and memory 1676 * objects enables the length argument of {@link 1677 * ANeuralNetworksExecution_setInput}, 1678 * {@link ANeuralNetworksExecution_setInputFromMemory}, {@link 1679 * ANeuralNetworksExecution_setOutput}, and {@link 1680 * ANeuralNetworksExecution_setOutputFromMemory} to be greater than the raw 1681 * size of the operand (i.e. the size of an element multiplied by the number 1682 * of elements). The extra bytes at the end of the buffer or memory region may 1683 * be used by the driver to access data in chunks, for efficiency. 1684 * 1685 * This method must not be called after {@link 1686 * ANeuralNetworksExecution_setInput}, 1687 * {@link ANeuralNetworksExecution_setInputFromMemory}, {@link 1688 * ANeuralNetworksExecution_setOutput}, or {@link 1689 * ANeuralNetworksExecution_setOutputFromMemory}. 1690 * 1691 * See {@link ANeuralNetworksExecution} for information on multithreaded 1692 * usage. 1693 * 1694 * @param execution The execution to be modified. 1695 * @param enable 'true' if the execution is to be able to accept padded input 1696 * and output buffers and memory objects, 'false' if not. 1697 * 1698 * @return ANEURALNETWORKS_NO_ERROR if successful. 1699 * ANEURALNETWORKS_UNEXPECTED_NULL if execution is NULL. 1700 * ANEURALNETWORKS_BAD_STATE if {@link 1701 * ANeuralNetworksExecution_setInput}, 1702 * {@link ANeuralNetworksExecution_setInputFromMemory}, 1703 * {@link ANeuralNetworksExecution_setOutput}, or 1704 * {@link ANeuralNetworksExecution_setOutputFromMemory} has been 1705 * called on the execution. 1706 * 1707 * Available since API level 31. 1708 */ 1709 int (*ANeuralNetworksExecution_enableInputAndOutputPadding)( 1710 ANeuralNetworksExecution* execution, bool enable); 1711 1712 /** 1713 * Specifies whether the {@link ANeuralNetworksExecution} can be reused for 1714 * multiple computations. 1715 * 1716 * By default, the {@link ANeuralNetworksExecution} is not reusable. 1717 * 1718 * Setting the execution to be reusable enables multiple computations to be 1719 * scheduled and evaluated on the same execution sequentially, either by means 1720 * of 1721 * {@link ANeuralNetworksExecution_burstCompute}, {@link 1722 * ANeuralNetworksExecution_compute}, 1723 * {@link ANeuralNetworksExecution_startCompute} or 1724 * {@link ANeuralNetworksExecution_startComputeWithDependencies}. 1725 * 1726 * This function may only be invoked when the execution is in the preparation 1727 * state. 1728 * 1729 * See {@link ANeuralNetworksExecution} for information on execution states 1730 * and multithreaded usage. 1731 * 1732 * @param execution The execution to be modified. 1733 * @param reusable 'true' if the execution is to be reusable, 'false' if not. 1734 * 1735 * @return ANEURALNETWORKS_NO_ERROR if successful. 1736 * ANEURALNETWORKS_UNEXPECTED_NULL if execution is NULL. 1737 * ANEURALNETWORKS_BAD_STATE if the execution is not in the 1738 * preparation state. 1739 * 1740 * Available since API level 31. 1741 */ 1742 int (*ANeuralNetworksExecution_setReusable)( 1743 ANeuralNetworksExecution* execution, bool reusable); 1744 1745 /** 1746 * Get the NNAPI runtime feature level. 1747 * 1748 * Since API level 31 (NNAPI feature level 5), the NNAPI runtime 1749 * (libneuralnetworks.so) and its API specification can be updated between 1750 * Android API releases. 1751 * 1752 * On Android devices with API level 31 and newer, for NNAPI runtime feature 1753 * discovery, the NNAPI runtime feature level must be used instead of the 1754 * Android device API level. 1755 * 1756 * On Android devices with API level 30 and older, the Android API level of 1757 * the Android device must be used for NNAPI runtime feature discovery. Enum 1758 * values in 1759 * {@link FeatureLevelCode} from feature level 1 to 5 have their corresponding 1760 * Android API levels listed in their documentation, and each such enum value 1761 * equals the corresponding API level. This allows using the Android API level 1762 * as the feature level. This mapping between enum value and Android API level 1763 * does not exist for feature levels after NNAPI feature level 5 and API 1764 * levels after S (31). 1765 * 1766 * Example usage: 1767 * int device_api_level = android_get_device_api_level(); 1768 * int64_t runtime_feature_level = (device_api_level < __ANDROID_API_S__) ? 1769 * device_api_level : 1770 * ANeuralNetworks_getRuntimeFeatureLevel(); 1771 * 1772 * Runtime feature level is closely related to NNAPI device feature level 1773 * ({@link ANeuralNetworksDevice_getFeatureLevel}), which indicates an NNAPI 1774 * device feature level (the most advanced NNAPI specification and features 1775 * that the driver implements). This function expresses NNAPI runtime feature 1776 * level, which indicates the most advanced NNAPI specification and features 1777 * the runtime implements. An NNAPI device feature level is always less than 1778 * or equal to the runtime feature level. 1779 * 1780 * This function returns a {@link FeatureLevelCode} enum value, 1781 * which is the NNAPI specification version that this NNAPI runtime 1782 * implements. It is NOT an Android API level. 1783 * 1784 * Available since NNAPI feature level 5. 1785 */ 1786 int64_t (*ANeuralNetworks_getRuntimeFeatureLevel)(); 1787 1788 /** 1789 * Gets the ID that identifies a single session of client interacting with 1790 * NNAPI runtime. 1791 * 1792 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1793 * object. 1794 * @return Session info id. 1795 */ 1796 int32_t (*SL_ANeuralNetworksDiagnosticCompilationInfo_getSessionId)( 1797 const ANeuralNetworksDiagnosticCompilationInfo* 1798 diagnosticCompilationInfo); 1799 1800 /** 1801 * Gets NNAPI version. 1802 * 1803 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1804 * object. 1805 * @return NNAPI version. 1806 */ 1807 int64_t (*SL_ANeuralNetworksDiagnosticCompilationInfo_getNnApiVersion)( 1808 const ANeuralNetworksDiagnosticCompilationInfo* 1809 diagnosticCompilationInfo); 1810 1811 /** 1812 * Gets the hash of the model architecture (without weights). 1813 * 1814 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1815 * object. 1816 * @return Model hash. 1817 */ 1818 const uint8_t* ( 1819 *SL_ANeuralNetworksDiagnosticCompilationInfo_getModelArchHash)( 1820 const ANeuralNetworksDiagnosticCompilationInfo* 1821 diagnosticCompilationInfo); 1822 1823 /** 1824 * Gets the device IDs as a comma-concatenated string. 1825 * 1826 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1827 * object. 1828 * @return Device ID. 1829 */ 1830 const char* (*SL_ANeuralNetworksDiagnosticCompilationInfo_getDeviceIds)( 1831 const ANeuralNetworksDiagnosticCompilationInfo* 1832 diagnosticCompilationInfo); 1833 1834 /** 1835 * Gets the error code. 1836 * 1837 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1838 * object. 1839 * @return Error code. 1840 */ 1841 int32_t (*SL_ANeuralNetworksDiagnosticCompilationInfo_getErrorCode)( 1842 const ANeuralNetworksDiagnosticCompilationInfo* 1843 diagnosticCompilationInfo); 1844 1845 /** 1846 * Gets the type of tensors used for inputs. 1847 * 1848 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1849 * object. 1850 * @return Input data class. 1851 */ 1852 ANeuralNetworksDiagnosticDataClass ( 1853 *SL_ANeuralNetworksDiagnosticCompilationInfo_getInputDataClass)( 1854 const ANeuralNetworksDiagnosticCompilationInfo* 1855 diagnosticCompilationInfo); 1856 1857 /** 1858 * Gets the type of tensors used for outputs. 1859 * 1860 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1861 * object. 1862 * @return Output data class. 1863 */ 1864 ANeuralNetworksDiagnosticDataClass ( 1865 *SL_ANeuralNetworksDiagnosticCompilationInfo_getOutputDataClass)( 1866 const ANeuralNetworksDiagnosticCompilationInfo* 1867 diagnosticCompilationInfo); 1868 1869 /** 1870 * Gets how many nanoseconds elapsed when compiling the model. 1871 * 1872 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1873 * object. 1874 * @return Time to compile the model in nanoseconds. UINT64_MAX indicates that 1875 * timing information is not available. 1876 */ 1877 uint64_t ( 1878 *SL_ANeuralNetworksDiagnosticCompilationInfo_getCompilationTimeNanos)( 1879 const ANeuralNetworksDiagnosticCompilationInfo* 1880 diagnosticCompilationInfo); 1881 1882 /** 1883 * Is caching enabled? 1884 * 1885 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1886 * object. 1887 * @return Whether caching is enabled. 1888 */ 1889 bool (*SL_ANeuralNetworksDiagnosticCompilationInfo_isCachingEnabled)( 1890 const ANeuralNetworksDiagnosticCompilationInfo* 1891 diagnosticCompilationInfo); 1892 1893 /** 1894 * Is control flow used? 1895 * 1896 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1897 * object. 1898 * @return Whether control flow was used. 1899 */ 1900 bool (*SL_ANeuralNetworksDiagnosticCompilationInfo_isControlFlowUsed)( 1901 const ANeuralNetworksDiagnosticCompilationInfo* 1902 diagnosticCompilationInfo); 1903 1904 /** 1905 * Are dynamic tensors used? 1906 * 1907 * @param diagnosticCompilationInfo The NNAPI diagnostic compilation info 1908 * object. 1909 * @return Whether dynamic tensors were used. 1910 */ 1911 bool (*SL_ANeuralNetworksDiagnosticCompilationInfo_areDynamicTensorsUsed)( 1912 const ANeuralNetworksDiagnosticCompilationInfo* 1913 diagnosticCompilationInfo); 1914 1915 /** 1916 * Gets the ID that identifies a single session of client interacting with 1917 * NNAPI runtime. 1918 * 1919 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1920 * object. 1921 * @return Session info id. 1922 */ 1923 int32_t (*SL_ANeuralNetworksDiagnosticExecutionInfo_getSessionId)( 1924 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1925 1926 /** 1927 * Gets NNAPI version. 1928 * 1929 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1930 * object. 1931 * @return NNAPI version. 1932 */ 1933 int64_t (*SL_ANeuralNetworksDiagnosticExecutionInfo_getNnApiVersion)( 1934 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1935 1936 /** 1937 * Gets the hash of the model architecture (without weights). 1938 * 1939 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1940 * object. 1941 * @return Model hash. 1942 */ 1943 const uint8_t* (*SL_ANeuralNetworksDiagnosticExecutionInfo_getModelArchHash)( 1944 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1945 1946 /** 1947 * Gets the device IDs as a comma-concatenated string. 1948 * 1949 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1950 * object. 1951 * @return Device ID. 1952 */ 1953 const char* (*SL_ANeuralNetworksDiagnosticExecutionInfo_getDeviceIds)( 1954 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1955 1956 /** 1957 * Gets the execution mode. 1958 * 1959 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1960 * object. 1961 * @return Execution mode. 1962 */ 1963 ANeuralNetworksDiagnosticExecutionMode ( 1964 *SL_ANeuralNetworksDiagnosticExecutionInfo_getExecutionMode)( 1965 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1966 1967 /** 1968 * Gets the input data class. 1969 * 1970 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1971 * object. 1972 * @return Input data class. 1973 */ 1974 ANeuralNetworksDiagnosticDataClass ( 1975 *SL_ANeuralNetworksDiagnosticExecutionInfo_getInputDataClass)( 1976 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1977 1978 /** 1979 * Gets the output data class. 1980 * 1981 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1982 * object. 1983 * @return Output data class. 1984 */ 1985 ANeuralNetworksDiagnosticDataClass ( 1986 *SL_ANeuralNetworksDiagnosticExecutionInfo_getOutputDataClass)( 1987 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1988 1989 /** 1990 * Gets the error code. 1991 * 1992 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 1993 * object. 1994 * @return Error code. 1995 */ 1996 uint32_t (*SL_ANeuralNetworksDiagnosticExecutionInfo_getErrorCode)( 1997 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 1998 1999 /** 2000 * Gets the time taken to execute from runtime, including runtime/ipc 2001 * overhead. 2002 * 2003 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2004 * object. 2005 * @return Time taken to execute as measured by the runtime in nanoseconds. 2006 * UINT64_MAX indicates that timing information is not available. 2007 */ 2008 uint64_t ( 2009 *SL_ANeuralNetworksDiagnosticExecutionInfo_getRuntimeExecutionTimeNanos)( 2010 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2011 2012 /** 2013 * Gets the time taken to execute in the driver, excluding runtime/ipc 2014 * overhead. 2015 * 2016 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2017 * object. 2018 * @return Time taken to execute on the driver in nanoseconds. UINT64_MAX 2019 * indicates that timing information is not available. 2020 */ 2021 uint64_t ( 2022 *SL_ANeuralNetworksDiagnosticExecutionInfo_getDriverExecutionTimeNanos)( 2023 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2024 2025 /** 2026 * Gets the time taken to execute on the hardware, excluding driver overhead. 2027 * 2028 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2029 * object. 2030 * @return Time taken to execute on the hardware in nanoseconds. UINT64_MAX 2031 * indicates that timing information is not available. 2032 */ 2033 uint64_t ( 2034 *SL_ANeuralNetworksDiagnosticExecutionInfo_getHardwareExecutionTimeNanos)( 2035 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2036 2037 /** 2038 * Is caching enabled? 2039 * 2040 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2041 * object. 2042 * @return Whether caching is enabled. 2043 */ 2044 bool (*SL_ANeuralNetworksDiagnosticExecutionInfo_isCachingEnabled)( 2045 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2046 2047 /** 2048 * Is control flow used? 2049 * 2050 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2051 * object. 2052 * @return Whether control flow was used. 2053 */ 2054 bool (*SL_ANeuralNetworksDiagnosticExecutionInfo_isControlFlowUsed)( 2055 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2056 2057 /** 2058 * Are dynamic tensors used? 2059 * 2060 * @param diagnosticExecutionInfo The NNAPI diagnostic compilation info 2061 * object. 2062 * @return Whether dynamic tensors were used. 2063 */ 2064 bool (*SL_ANeuralNetworksDiagnosticExecutionInfo_areDynamicTensorsUsed)( 2065 const ANeuralNetworksDiagnosticExecutionInfo* diagnosticExecutionInfo); 2066 2067 /** 2068 * Sets the callbacks to be called when compilations or executions finish. 2069 * 2070 * Example usage: 2071 * 2072 * // Callback to be invoked whenever a compilation has completed. 2073 * void compilationCallback(void* context, 2074 * ANeuralNetworksDiagnosticCompilationInfo* info) { 2075 * // The context object can be used to store state without the use of a 2076 * global variable. ExampleLoggerObject* logger = 2077 * static_cast<ExampleLoggerObject*>(context); 2078 * 2079 * // Calls to getters to get the details... 2080 * const int32_t sessionId = 2081 * ANeuralNetworksDiagnosticCompilationInfo_getSessionId(info); 2082 * 2083 * ... 2084 * 2085 * logger->write(...); 2086 * } 2087 * 2088 * void executionCallback(void* context, 2089 * ANeuralNetworksDiagnosticExecutionInfo* info) { 2090 * ... 2091 * } 2092 * 2093 * ExampleLoggerObject exampleLoggerObject; 2094 * ANeuralNetworksDiagnostic_registerCallbacks(&compilationCallback, 2095 * &executionCallback, static_cast<void*>(&exampleLoggerObject)); 2096 * 2097 * @param compilationCallback The compilation callback to set. 2098 * @param executionCallback The execution callback to set. 2099 * @param callbackContext The context to be passed to the callbacks when they 2100 * are invoked. The context object may be used by multiple threads 2101 * simulatenously, so it must be thread-safe. 2102 */ 2103 void (*SL_ANeuralNetworksDiagnostic_registerCallbacks)( 2104 ANeuralNetworksDiagnosticCompilationFinishedCallback compilationCallback, 2105 ANeuralNetworksDiagnosticExecutionFinishedCallback executionCallback, 2106 void* callbackContext); 2107 }; 2108 2109 /** 2110 * Load the NNAPI implementation from the shared libraries. 2111 * The NnApi structure is filled with all the pointers. If one function doesn't 2112 * exist, a null pointer is stored. 2113 */ 2114 const NnApi* NnApiImplementation(); 2115 2116 // Forward declaration for CreateNnApiFromSupportLibrary below. 2117 struct NnApiSLDriverImplFL5; 2118 2119 /** 2120 * Allocate a new NnApi structure instance and fill it with function pointers 2121 * from NnApiSLDriverImplFL5 instance. Functions that are not present in the 2122 * support library are assigned null pointers. 2123 * 2124 * The NN API Support Library Driver must support at least NNAPI Feature Level 5 2125 * (introduced in SDK level 31), but this might point to a compatible struct 2126 * that also supports a higher NNAPI Feature Level. These cases can be 2127 * distinguished by examining the base.implFeatureLevel field, which should be 2128 * set to the supported feature level (which must be >= 2129 * ANEURALNETWORKS_FEATURE_LEVEL_5). 2130 */ 2131 std::unique_ptr<const NnApi> CreateNnApiFromSupportLibrary( 2132 const NnApiSLDriverImplFL5* nnapi_support_library_driver); 2133 2134 #endif // TENSORFLOW_LITE_NNAPI_NNAPI_IMPLEMENTATION_H_ 2135