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 "tensorflow/lite/nnapi/NeuralNetworksTypes.h" 23 24 struct NnApi { 25 bool nnapi_exists; 26 int32_t android_sdk_version; 27 28 /** 29 * Creates a shared memory object from a file descriptor. 30 * 31 * The shared memory is backed by a file descriptor via mmap. 32 * See {@link ANeuralNetworksMemory} for a description on how to use 33 * this shared memory. 34 * 35 * @param size The requested size in bytes. 36 * Must not be larger than the file size. 37 * @param prot The desired memory protection for the mapping. 38 * It is either PROT_NONE or the bitwise OR of one or 39 * more of the following flags: PROT_READ, PROT_WRITE. 40 * @param fd The requested file descriptor. 41 * The file descriptor has to be mmap-able. The file 42 * descriptor will be duplicated. 43 * @param offset The offset to the beginning of the file of the area to map. 44 * The offset has to be aligned to a page size. 45 * @param memory The memory object to be created. 46 * Set to NULL if unsuccessful. 47 * 48 * @return ANEURALNETWORKS_NO_ERROR if the request completed normally. 49 */ 50 int (*ANeuralNetworksMemory_createFromFd)(size_t size, int protect, int fd, 51 size_t offset, 52 ANeuralNetworksMemory** memory); 53 54 /** 55 * Delete a memory object. 56 * 57 * Destroys the object used by the run time to keep track of the memory. 58 * This will free the underlying actual memory if no other code has open 59 * handles to this memory. 60 * 61 * @param memory The memory object to be freed. 62 */ 63 void (*ANeuralNetworksMemory_free)(ANeuralNetworksMemory* memory); 64 65 /** 66 * Create an empty {@link ANeuralNetworksModel}. 67 * 68 * <p>This only creates the object. Computation is performed once 69 * {@link ANeuralNetworksExecution_startCompute} is invoked. 70 * 71 * The model should be constructed with calls to 72 * {@link ANeuralNetworksModel_addOperation} and 73 * {@link ANeuralNetworksModel_addOperand} 74 * 75 * <p>{@link ANeuralNetworksModel_finish} should be called once the model 76 * has been fully constructed.</p> 77 * 78 * <p>{@link ANeuralNetworksModel_free} should be called once the model 79 * is no longer needed.</p> 80 * 81 * @param model The {@link ANeuralNetworksModel} to be created. 82 * Set to NULL if unsuccessful. 83 * 84 * @return ANEURALNETWORKS_NO_ERROR if successful. 85 */ 86 int (*ANeuralNetworksModel_create)(ANeuralNetworksModel** model); 87 88 /** 89 * Destroy a model. 90 * 91 * The model need not have been finished by a call to 92 * {@link ANeuralNetworksModel_finish}. 93 * 94 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 95 * 96 * @param model The model to be destroyed. Passing NULL is acceptable and 97 * results in no operation. 98 */ 99 void (*ANeuralNetworksModel_free)(ANeuralNetworksModel* model); 100 101 /** 102 * Indicate that we have finished modifying a model. Required before 103 * calling {@link ANeuralNetworksCompilation_compile}. 104 * 105 * An application is responsible to make sure that no other thread uses 106 * the model at the same time. 107 * 108 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 109 * 110 * @param model The model to be finished. 111 * 112 * @return ANEURALNETWORKS_NO_ERROR if successful. 113 */ 114 int (*ANeuralNetworksModel_finish)(ANeuralNetworksModel* model); 115 116 /** 117 * Add an operand to a model. 118 * 119 * The order in which the operands are added is important. The first one added 120 * to a model will have the index value 0, the second 1, etc. These indexes 121 * are used as operand identifiers in 122 * {@link ANeuralNetworksModel_addOperation}, 123 * {@link ANeuralNetworksExecution_setInput}, 124 * {@link ANeuralNetworksExecution_setInputFromMemory}, 125 * {@link ANeuralNetworksExecution_setOutput}, 126 * {@link ANeuralNetworksExecution_setOutputFromMemory} and 127 * {@link ANeuralNetworksExecution_setOperandValue}. 128 * 129 * To build a model that can accommodate inputs of various sizes, as you may 130 * want to do for a CNN, set the size of the dimensions that will vary at run 131 * time to 0. If you do so, provide the full dimensions when calling 132 * {@link ANeuralNetworksExecution_setInput} or {@link 133 * ANeuralNetworksExecution_setInputFromMemory}. 134 * 135 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 136 * been called will return an error. 137 * 138 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 139 * 140 * @param model The model to be modified. 141 * @param type The {@link ANeuralNetworksOperandType} that describes the shape 142 * of the operand. 143 * 144 * @return ANEURALNETWORKS_NO_ERROR if successful. 145 */ 146 int (*ANeuralNetworksModel_addOperand)( 147 ANeuralNetworksModel* model, const ANeuralNetworksOperandType* type); 148 149 /** 150 * Sets an operand to a constant value. 151 * 152 * For scalar values, the content of buffer is copied into the model. 153 * 154 * For tensor values, a pointer to the buffer is stored within the model. 155 * The application is responsible for not changing the content of this region 156 * until all executions using this model have completed. As the data may 157 * be copied during processing, modifying the data after this call yields 158 * undefined results. 159 * 160 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 161 * been called will return an error. 162 * 163 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 164 * 165 * @param model The model to be modified. 166 * @param index The index of the model operand we're setting. 167 * @param buffer A pointer to the data to use. 168 * @param length The size in bytes of the data value. 169 * 170 * @return ANEURALNETWORKS_NO_ERROR if successful. 171 */ 172 int (*ANeuralNetworksModel_setOperandValue)(ANeuralNetworksModel* model, 173 int32_t index, const void* buffer, 174 size_t length); 175 176 /** 177 * Sets an operand's per channel quantization parameters. 178 * 179 * Sets parameters required by a tensor of type 180 * {@link ANEURALNETWORKS_TENSOR_QUANT8_SYMM_PER_CHANNEL}. 181 * This function must be called for every tensor of type 182 * {@link ANEURALNETWORKS_TENSOR_QUANT8_SYMM_PER_CHANNEL} before 183 * calling {@link ANeuralNetworksModel_finish}. 184 * 185 * Available since API level 29. 186 * 187 * @param model The model to be modified. 188 * @param index The index of the model operand we're setting. 189 * @param channelQuant The per channel quantization parameters for the 190 * operand. No memory in this struct needs to outlive the 191 * call to this function. 192 * 193 * @return ANEURALNETWORKS_NO_ERROR if successful. 194 */ 195 int (*ANeuralNetworksModel_setOperandSymmPerChannelQuantParams)( 196 ANeuralNetworksModel* model, int32_t index, 197 const ANeuralNetworksSymmPerChannelQuantParams* channelQuant); 198 199 /** 200 * Sets an operand to a value stored in a memory object. 201 * 202 * The content of the memory is not copied. A reference to that memory is 203 * stored inside the model. The application is responsible for not changing 204 * the content of the memory region until all executions using this model have 205 * completed. 206 * As the data may be copied during processing, modifying the data after this 207 * call yields undefined results. 208 * 209 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 210 * been called will return an error. 211 * 212 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 213 * 214 * @param model The model to be modified. 215 * @param index The index of the model operand we're setting. 216 * @param buffer A pointer to the data to use. 217 * @param memory The memory containing the data. 218 * @param offset This specifies the location of the data within the memory. 219 * The offset is in bytes from the start of memory. 220 * @param length The size in bytes of the data value. 221 * 222 * @return ANEURALNETWORKS_NO_ERROR if successful. 223 */ 224 int (*ANeuralNetworksModel_setOperandValueFromMemory)( 225 ANeuralNetworksModel* model, int32_t index, 226 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 227 228 /** 229 * Add an operation to a model. 230 * 231 * @param model The model to be modified. 232 * @param type The type of the operation. 233 * @param inputCount The number of entries in the inputs array. 234 * @param inputs An array of indexes identifying each operand. 235 * @param outputCount The number of entries in the outputs array. 236 * @param outputs An array of indexes identifying each operand. 237 * 238 * The operands specified by inputs and outputs must have been 239 * previously added by calls to {@link ANeuralNetworksModel_addOperand}. 240 * 241 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 242 * been called will return an error. 243 * 244 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 245 * 246 * @return ANEURALNETWORKS_NO_ERROR if successful. 247 */ 248 int (*ANeuralNetworksModel_addOperation)(ANeuralNetworksModel* model, 249 ANeuralNetworksOperationType type, 250 uint32_t inputCount, 251 const uint32_t* inputs, 252 uint32_t outputCount, 253 const uint32_t* outputs); 254 255 /** 256 * Specifies which operands will be the model's inputs and outputs. 257 * 258 * An operand cannot be used for both input and output. Doing so will 259 * return an error. 260 * 261 * @param model The model to be modified. 262 * @param inputCount The number of entries in the inputs array. 263 * @param inputs An array of indexes identifying the input operands. 264 * @param outputCount The number of entries in the outputs array. 265 * @param outputs An array of indexes identifying the output operands. 266 * 267 * The operands specified by inputs and outputs must have been 268 * previously added by calls to {@link ANeuralNetworksModel_addOperand}. 269 * 270 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 271 * been called will return an error. 272 * 273 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 274 * 275 */ 276 int (*ANeuralNetworksModel_identifyInputsAndOutputs)( 277 ANeuralNetworksModel* model, uint32_t inputCount, const uint32_t* inputs, 278 uint32_t outputCount, const uint32_t* outputs); 279 280 /** 281 * Specifies whether {@link ANEURALNETWORKS_TENSOR_FLOAT32} is allowed to be 282 * calculated with range and/or precision as low as that of the 283 * IEEE 754 16-bit floating-point format. By default, 284 * {@link ANEURALNETWORKS_TENSOR_FLOAT32} must be calculated using at least 285 * the range and precision of the IEEE 754 32-bit floating-point format. 286 * 287 * @param model The model to be modified. 288 * @param allow 'true' indicates {@link ANEURALNETWORKS_TENSOR_FLOAT32} may be 289 * calculated with range and/or precision as low as that of the 290 * IEEE 754 16-bit floating point format. 'false' indicates 291 * {@link ANEURALNETWORKS_TENSOR_FLOAT32} must be calculated 292 * using at least the range and precision of the IEEE 754 32-bit 293 * floating point format. 294 * 295 * Attempting to modify a model once {@link ANeuralNetworksModel_finish} has 296 * been called will return an error. 297 * 298 * Available since API level 28. 299 * 300 * See {@link ANeuralNetworksModel} for information on multithreaded usage. 301 */ 302 int (*ANeuralNetworksModel_relaxComputationFloat32toFloat16)( 303 ANeuralNetworksModel* model, bool allow); 304 305 /** 306 * Create a {@link ANeuralNetworksCompilation} to compile the given model. 307 * This only creates the object. Compilation is only performed once 308 * {@link ANeuralNetworksCompilation_start} is invoked. 309 * 310 * <p>The provided model must outlive the compilation.</p> 311 * 312 * The model must already have been finished by a call to 313 * {@link ANeuralNetworksModel_finish}. 314 * 315 * See {@link ANeuralNetworksCompilation} for information on multithreaded 316 * usage. 317 * 318 * @param model The {@link ANeuralNetworksModel} to be compiled. 319 * @param compilation The newly created object or NULL if unsuccessful. 320 * 321 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 322 * if the model is invalid. 323 */ 324 int (*ANeuralNetworksCompilation_create)( 325 ANeuralNetworksModel* model, ANeuralNetworksCompilation** compilation); 326 327 /** 328 * Destroy a compilation. 329 * 330 * <p>If called on a compilation for which 331 * {@link ANeuralNetworksCompilation_start} has been called, the 332 * function will return immediately but will mark the compilation to be 333 * deleted once the compilation completes. The 334 * {@link ANeuralNetworksCompilation_wait} will return ERROR_DELETED. 335 * 336 * See {@link ANeuralNetworksCompilation} for information on multithreaded 337 * usage. 338 * 339 * @param compilation The compilation to be destroyed. Passing NULL is 340 * acceptable and results in no operation. 341 */ 342 void (*ANeuralNetworksCompilation_free)( 343 ANeuralNetworksCompilation* compilation); 344 345 /** 346 * Sets the execution preference. 347 * 348 * <p>Provides guidance to the runtime when trade-offs are possible.</p> 349 * 350 * See {@link ANeuralNetworksCompilation} for information on multithreaded 351 * usage. 352 * 353 * @param compilation The compilation to be modified. 354 * @param preference Either {@link PREFER_LOW_POWER}, 355 * {@link PREFER_SINGLE_FAST_ANSWER}, or 356 * {@link PREFER_SUSTAINED_SPEED}. 357 * 358 * @return ANEURALNETWORKS_NO_ERROR if successful. 359 */ 360 int (*ANeuralNetworksCompilation_setPreference)( 361 ANeuralNetworksCompilation* compilation, int32_t preference); 362 363 /** 364 * Waits until the compilation completes. 365 * 366 * More than one thread can wait on a compilation. When the compilation 367 * completes, all threads will be released. 368 * 369 * See {@link ANeuralNetworksCompilation} for information on multithreaded 370 * usage. 371 * 372 * @return ANEURALNETWORKS_NO_ERROR if the compilation completed normally. 373 */ 374 int (*ANeuralNetworksCompilation_finish)( 375 ANeuralNetworksCompilation* compilation); 376 377 /** 378 * Create a {@link ANeuralNetworksExecution} to apply the given compilation. 379 * This only creates the object. Computation is only performed once 380 * {@link ANeuralNetworksExecution_startCompute} is invoked. 381 * 382 * <p>The provided compilation must outlive the execution.</p> 383 * 384 * See {@link ANeuralNetworksExecution} for information on multithreaded 385 * usage. 386 * 387 * @param compilation The {@link ANeuralNetworksCompilation} to be evaluated. 388 * @param execution The newly created object or NULL if unsuccessful. 389 * 390 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 391 * if the compilation is invalid. 392 */ 393 int (*ANeuralNetworksExecution_create)( 394 ANeuralNetworksCompilation* compilation, 395 ANeuralNetworksExecution** execution); 396 397 /** 398 * Destroy an execution. 399 * 400 * <p>If called on an execution for which 401 * {@link ANeuralNetworksExecution_startCompute} has been called, the 402 * function will return immediately but will mark the execution to be deleted 403 * once the computation completes. The {link ANeuralNetworksExecution_wait} 404 * will return ANEURALNETWORKS_ERROR_DELETED. 405 * 406 * See {@link ANeuralNetworksExecution} for information on multithreaded 407 * usage. 408 * 409 * @param execution The execution to be destroyed. Passing NULL is acceptable 410 * and results in no operation. 411 */ 412 void (*ANeuralNetworksExecution_free)(ANeuralNetworksExecution* execution); 413 414 /** 415 * Associate a user buffer with an input of the model of the 416 * {@link ANeuralNetworksExecution}. 417 * 418 * <p>The provided buffer must outlive the execution.</p> 419 * 420 * See {@link ANeuralNetworksExecution} for information on multithreaded 421 * usage. 422 * 423 * @param execution The execution to be modified. 424 * @param index The index of the input argument we are setting. It is 425 * an index into the lists passed to 426 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 427 * not the index associated with {@link 428 * ANeuralNetworksModel_addOperand}. 429 * @param type The type of the operand. This should be used to specify the 430 * dimensions that were set to 0 when the operand was added to the 431 * model. All other properties of the type must be the same as 432 * specified in the model. If the type is the same as specified 433 * when the model was built, NULL can be passed. 434 * @param buffer The buffer containing the data. 435 * @param length The length in bytes of the buffer. 436 * 437 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 438 * the name is not recognized or the buffer is too small for the input. 439 */ 440 int (*ANeuralNetworksExecution_setInput)( 441 ANeuralNetworksExecution* execution, int32_t index, 442 const ANeuralNetworksOperandType* type, const void* buffer, 443 size_t length); 444 445 /** 446 * Associate part of a memory object with an input of the model of the 447 * {@link ANeuralNetworksExecution}. 448 * 449 * <p>The provided memory must outlive the execution.</p> 450 * 451 * See {@link ANeuralNetworksExecution} for information on multithreaded 452 * usage. 453 * 454 * @param execution The execution to be modified. 455 * @param index The index of the input argument we are setting. It is 456 * an index into the lists passed to 457 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 458 * not the index associated with {@link 459 * ANeuralNetworksModel_addOperand}. 460 * @param type The type of the operand. This can be used to specify the 461 * dimensions that were set to 0 when the operand was added to the 462 * model. All other values must be the same as specified in the 463 * model. If the type is the same as specified when the model 464 * was built, NULL can be passed. 465 * @param memory The memory containing the data. 466 * @param offset This specifies the location of the data within the memory. 467 * The offset is in bytes from the start of memory. 468 * @param length The size in bytes of the data value. 469 * 470 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 471 * the name is not recognized or the buffer is too small for the input. 472 */ 473 int (*ANeuralNetworksExecution_setInputFromMemory)( 474 ANeuralNetworksExecution* execution, int32_t index, 475 const ANeuralNetworksOperandType* type, 476 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 477 478 /** 479 * Associate a user buffer with an output of the model of the 480 * {@link ANeuralNetworksExecution}. 481 * 482 * <p>The provided buffer must outlive the execution.</p> 483 * 484 * See {@link ANeuralNetworksExecution} for information on multithreaded 485 * usage. 486 * 487 * @param execution The execution to be modified. 488 * @param index The index of the output argument we are setting. It is 489 * an index into the lists passed to 490 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 491 * not the index associated with {@link 492 * ANeuralNetworksModel_addOperand}. 493 * @param type The type of the operand. This can be used to specify the 494 * dimensions that were set to 0 when the operand was added to the 495 * model. All other values must be the same as specified in the 496 * model. If the type is the same as specified when the model 497 * was built, NULL can be passed. 498 * @param buffer The buffer where the data is to be written. 499 * @param length The length in bytes of the buffer. 500 * 501 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 502 * the name is not recognized or the buffer is too small for the output. 503 */ 504 int (*ANeuralNetworksExecution_setOutput)( 505 ANeuralNetworksExecution* execution, int32_t index, 506 const ANeuralNetworksOperandType* type, void* buffer, size_t length); 507 508 /** 509 * Associate part of a memory object with an output of the model of the 510 * {@link ANeuralNetworksExecution}. 511 * 512 * <p>The provided memory must outlive the execution.</p> 513 * 514 * See {@link ANeuralNetworksExecution} for information on multithreaded 515 * usage. 516 * 517 * @param execution The execution to be modified. 518 * @param index The index of the output argument we are setting. It is 519 * an index into the lists passed to 520 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 521 * not the index associated with {@link 522 * ANeuralNetworksModel_addOperand}. 523 * @param type The type of the operand. This can be used to specify the 524 * dimensions that were set to 0 when the operand was added to the 525 * model. All other values must be the same as specified in the 526 * model. If the type is the same as specified when the model 527 * was built, NULL can be passed. 528 * @param memory The memory where the data is to be stored. 529 * @param offset This specifies the location of the data within the memory. 530 * The offset is in bytes from the start of memory. 531 * @param length The length in bytes of the data value. 532 * 533 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA if 534 * the name is not recognized or the buffer is too small for the output. 535 */ 536 int (*ANeuralNetworksExecution_setOutputFromMemory)( 537 ANeuralNetworksExecution* execution, int32_t index, 538 const ANeuralNetworksOperandType* type, 539 const ANeuralNetworksMemory* memory, size_t offset, size_t length); 540 541 /** 542 * Schedule evaluation of the execution. 543 * 544 * <p>Schedules evaluation of the execution. Once the model has been 545 * applied and the outputs are ready to be consumed, the execution will be 546 * signaled. Use {@link ANeuralNetworksExecution_wait} to wait for that 547 * signal. 548 * </p> 549 * 550 * Multiple executions can be scheduled and evaluated concurrently, and 551 * compilations can be performed concurrently with executions. The runtime 552 * makes no guarantee on the ordering of the completion of compilations and 553 * executions. If it's important to the application, the application should 554 * enforce the ordering by using {@link ANeuralNetworksCompilation_wait} and 555 * {@link ANeuralNetworksExecution_wait}. 556 * 557 * ANeuralNetworksExecution_wait must be called to recuperate the resources 558 * used by the execution. 559 * 560 * See {@link ANeuralNetworksExecution} for information on multithreaded 561 * usage. 562 * 563 * @param execution The execution to be scheduled and executed. 564 * 565 * @return ANEURALNETWORKS_NO_ERROR if successful. 566 */ 567 int (*ANeuralNetworksExecution_startCompute)( 568 ANeuralNetworksExecution* execution, ANeuralNetworksEvent** event); 569 570 /** 571 * Waits until the execution completes. 572 * 573 * More than one thread can wait on an event. When the execution completes, 574 * all threads will be released. 575 * 576 * See {@link ANeuralNetworksExecution} for information on multithreaded 577 * usage. 578 * 579 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 580 */ 581 int (*ANeuralNetworksEvent_wait)(ANeuralNetworksEvent* event); 582 583 /** 584 * Destroys the event. 585 * 586 * See {@link ANeuralNetworksExecution} for information on multithreaded 587 * usage. 588 */ 589 void (*ANeuralNetworksEvent_free)(ANeuralNetworksEvent* event); 590 591 // ASharedMemory_create was added in Android 8.0, so safe to use with NNAPI 592 // which was added in 8.1. 593 int (*ASharedMemory_create)(const char* name, size_t size); 594 595 /** 596 * Get the number of available devices. 597 * 598 * @param numDevices Used to return the number of devices. 599 * 600 * @return ANEURALNETWORKS_NO_ERROR if successful. 601 * 602 * Available since API level 29. 603 */ 604 int (*ANeuralNetworks_getDeviceCount)(uint32_t* numDevices); 605 606 /** 607 * Get the representation of the specified device. 608 * 609 * @param devIndex The index of the specified device. Must be less than the 610 * number of available devices. 611 * @param device The representation of the specified device. 612 * The same representation will always be returned for the 613 * specified device. 614 * 615 * @return ANEURALNETWORKS_NO_ERROR if successful. 616 * 617 * Available since API level 29. 618 */ 619 620 int (*ANeuralNetworks_getDevice)(uint32_t devIndex, 621 ANeuralNetworksDevice** device); 622 623 /** 624 * Get the name of the specified device. 625 * 626 * @param device The representation of the specified device. 627 * @param name The returned name of the specified device. The name will be 628 * in UTF-8 and will be null-terminated. It will be recognizable 629 * as a known device name rather than a cryptic string. For 630 * devices with API level 29 and above, the format of the name is 631 * {VENDOR}-{DEVICE}, e.g. “google-ipu”. For devices with feature 632 * level 28 or lower, the name will always be “unknown-device”. 633 * The name will remain valid for the duration of the application. 634 * 635 * @return ANEURALNETWORKS_NO_ERROR if successful. 636 * 637 * Available since API level 29. 638 */ 639 int (*ANeuralNetworksDevice_getName)(const ANeuralNetworksDevice* device, 640 const char** name); 641 642 /** 643 * Get the version of the driver implementation of the specified device. 644 * 645 * It’s the responsibility of the driver implementor to insure that this 646 * version string uniquely distinguishes this implementation from all previous 647 * implementations. 648 * 649 * This version string must not be confused with the feature level which is 650 * solely defined by {@link ANeuralNetworksDevice_getFeatureLevel}. There is 651 * no implicit ordering of the versions. For example, it is not possible to 652 * filter all drivers older than a certain version. 653 * 654 * Application developers may use this version string to avoid or prefer 655 * specific driver implementations. For example, an application may want to do 656 * so because: 657 * - A specific version of the driver does not provide the required 658 * performance, perhaps because of a performance regression. 659 * - A specific version of the driver has a bug or returns results that 660 * don’t match the minimum precision requirement for the application. 661 * 662 * @param device The representation of the specified device. 663 * @param version The returned version string of the driver for the specified 664 * device. The string will be in UTF-8 and will be 665 * null-terminated. For devices with feature level 28 or lower, 666 * "UNKNOWN" will be returned. The version string will remain 667 * valid for the duration of the application. 668 * 669 * @return ANEURALNETWORKS_NO_ERROR if successful. 670 * 671 * Available since API level 29. 672 */ 673 int (*ANeuralNetworksDevice_getVersion)(const ANeuralNetworksDevice* device, 674 const char** version); 675 676 /** 677 * Get the supported NNAPI version of the specified device. 678 * 679 * Each device has a supported feature level, which is the most advanced 680 * feature this driver implements. For example, if the driver implements the 681 * features introduced in Android P, but does not implement the features 682 * introduced after Android P, the value would be 28. Developers could decide 683 * whether or not the specified device should be used for a Model that has 684 * certain feature requirements. 685 * 686 * @param device The representation of the specified device. 687 * @param featureLevel The API level of the most advanced feature this driver 688 * implements. 689 * 690 * @return ANEURALNETWORKS_NO_ERROR if successful. 691 * 692 * Available since API level 29. 693 */ 694 int (*ANeuralNetworksDevice_getFeatureLevel)( 695 const ANeuralNetworksDevice* device, int64_t* featureLevel); 696 697 /** 698 * Get the type of a given device. 699 * 700 * The device type can be used to help application developers to distribute 701 * Machine Learning workloads and other workloads such as graphical rendering. 702 * E.g., for an app which renders AR scenes based on real time object 703 * detection results, the developer could choose an ACCELERATOR type device 704 * for ML workloads, and reserve GPU for graphical rendering. 705 * 706 * @param device The representation of the specified device. 707 * @param type The returned {@link DeviceTypeCode} of the specified device. 708 * 709 * @return ANEURALNETWORKS_NO_ERROR if successful. 710 * 711 * Available since API level 29. 712 */ 713 int (*ANeuralNetworksDevice_getType)(const ANeuralNetworksDevice* device, 714 int32_t* type); 715 716 /** 717 * Get the supported operations for a specified set of devices. If multiple 718 * devices are selected, the supported operation list is a union of supported 719 * operations of all selected devices. 720 * 721 * @param model The model to be queried. 722 * @param devices The set of devices. Must not contain duplicates. 723 * @param numDevices The number of devices in the set. 724 * @param supportedOps The boolean array to be filled. True means supported. 725 * The size of the boolean array must be at least as large 726 * as the number of operations in the model. The order of 727 * elements in the supportedOps array matches the order in 728 * which the corresponding operations were added to the 729 * model. 730 * 731 * @return ANEURALNETWORKS_NO_ERROR if successful. 732 * 733 * Available since API level 29. 734 */ 735 int (*ANeuralNetworksModel_getSupportedOperationsForDevices)( 736 const ANeuralNetworksModel* model, 737 const ANeuralNetworksDevice* const* devices, uint32_t numDevices, 738 bool* supportedOps); 739 740 /** 741 * Create a {@link ANeuralNetworksCompilation} to compile the given model for 742 * a specified set of devices. If more than one device is specified, the 743 * compilation will distribute the workload automatically across the devices. 744 * The model must be fully supported by the specified set of devices. This 745 * means that ANeuralNetworksModel_getSupportedOperationsForDevices() must 746 * have returned true for every operation for that model/devices pair. 747 * 748 * @param model The {@link ANeuralNetworksModel} to be compiled. 749 * @param devices The set of devices. Must not contain duplicates. 750 * @param numDevices The number of devices in the set. 751 * @param compilation The newly created object or NULL if unsuccessful. 752 * 753 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 754 * if the model is invalid. 755 * 756 * Available since API level 29. 757 */ 758 int (*ANeuralNetworksCompilation_createForDevices)( 759 ANeuralNetworksModel* model, const ANeuralNetworksDevice* const* devices, 760 uint32_t numDevices, ANeuralNetworksCompilation** compilation); 761 762 /** 763 * Sets the compilation caching signature and the cache directory. 764 * 765 * Provides optional caching information to the runtime for faster repeated 766 * compilation. 767 * 768 * See {@link ANeuralNetworksCompilation} for information on multithreaded 769 * usage. 770 * 771 * @param compilation The compilation to be modified. 772 * @param cacheDir The cache directory to store and retrieve caching data. It 773 * is recommended to use the code_cache provided by the 774 * Android runtime. If not using the code_cache, the user 775 * should choose a directory local to the application, and is 776 * responsible to manage and clean the cache entries. 777 * @param token The token provided by the user to specify a model, must be of 778 * length ANEURALNETWORKS_BYTE_SIZE_OF_CACHE_TOKEN. The user 779 * should ensure that the token is unique to a model within the 780 * application. The NNAPI runtime will not detected token 781 * collisions. If there is a collision, the compilation outcome 782 * may be incorrect without notifying with error. 783 * 784 * @return ANEURALNETWORKS_NO_ERROR if successful. 785 * 786 * Available since API level 29. 787 */ 788 int (*ANeuralNetworksCompilation_setCaching)( 789 ANeuralNetworksCompilation* compilation, const char* cacheDir, 790 const uint8_t* token); 791 792 /** 793 * Schedule synchronous evaluation of the execution. 794 * 795 * <p>Schedules synchronous evaluation of the execution. Returns once the 796 * execution has completed and the outputs are ready to be consumed. 797 * </p> 798 * 799 * See {@link ANeuralNetworksExecution} for information on multithreaded 800 * usage. 801 * 802 * See {@link ANeuralNetworksExecution_startCompute} for asynchronous 803 * execution. Synchronous execution incurs lower overhead than asynchronous 804 * execution. 805 * 806 * Available since API level 29. 807 * 808 * @param execution The execution to be scheduled and executed. 809 * 810 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 811 * ANEURALNETWORKS_UNMAPPABLE if the execution input or output memory 812 * cannot be properly mapped. 813 */ 814 int (*ANeuralNetworksExecution_compute)(ANeuralNetworksExecution* execution); 815 816 /** 817 * Get the dimensional information of the specified output operand of the 818 * model of the 819 * {@link ANeuralNetworksExecution}. 820 * 821 * On asynchronous execution initiated by {@link 822 * ANeuralNetworksExecution_startCompute}, 823 * {@link ANeuralNetworksEvent_wait} must be called prior to this function to 824 * recuperate the resources used by the execution. 825 * 826 * @param execution The execution to be queried. 827 * @param index The index of the output argument we are querying. It is 828 * an index into the lists passed to 829 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 830 * not the index associated with 831 * {@link ANeuralNetworksModel_addOperand}. 832 * @param rank The rank of the output operand. 833 * 834 * @return ANEURALNETWORKS_NO_ERROR if successful, 835 * ANEURALNETWORKS_OUTPUT_INSUFFICIENT_SIZE if the target output is 836 * provided an insufficient buffer at execution time, 837 * ANEURALNETWORKS_BAD_DATA if the index is invalid. 838 * 839 * Available since API level 29. 840 */ 841 int (*ANeuralNetworksExecution_getOutputOperandRank)( 842 ANeuralNetworksExecution* execution, int32_t index, uint32_t* rank); 843 844 /** 845 * Get the dimensional information of the specified output operand of the 846 * model of the 847 * {@link ANeuralNetworksExecution}. The target output operand cannot be a 848 * scalar. 849 * 850 * On asynchronous execution initiated by {@link 851 * ANeuralNetworksExecution_startCompute}, 852 * {@link ANeuralNetworksEvent_wait} must be called prior to this function to 853 * recuperate the resources used by the execution. 854 * 855 * @param execution The execution to be queried. 856 * @param index The index of the output argument we are querying. It is an 857 * index into the lists passed to 858 * {@link ANeuralNetworksModel_identifyInputsAndOutputs}. It is 859 * not the index associated with 860 * {@link ANeuralNetworksModel_addOperand}. 861 * @param dimensions The dimension array to be filled. The size of the array 862 * must be exactly as large as the rank of the output 863 * operand to be queried in the model. 864 * 865 * @return ANEURALNETWORKS_NO_ERROR if successful, 866 * ANEURALNETWORKS_OUTPUT_INSUFFICIENT_SIZE if the target output is 867 * provided an insufficient buffer at execution time, 868 * ANEURALNETWORKS_BAD_DATA if the index is invalid or if the target 869 * is a scalar. 870 * 871 * Available since API level 29. 872 */ 873 int (*ANeuralNetworksExecution_getOutputOperandDimensions)( 874 ANeuralNetworksExecution* execution, int32_t index, uint32_t* dimensions); 875 876 /** 877 * Create a {@link ANeuralNetworksBurst} to apply the given compilation. 878 * This only creates the burst object. Computation is only performed once 879 * {@link ANeuralNetworksExecution_burstCompute} is invoked with a valid 880 * {@link ANeuralNetworksExecution} and {@link ANeuralNetworksBurst}. 881 * 882 * <p>The provided compilation must outlive the burst object.</p> 883 * 884 * Available since API level 29. 885 * 886 * @param compilation The {@link ANeuralNetworksCompilation} to be evaluated. 887 * @param burst The newly created object or NULL if unsuccessful. 888 * 889 * @return ANEURALNETWORKS_NO_ERROR if successful, ANEURALNETWORKS_BAD_DATA 890 * if the compilation is invalid. 891 */ 892 int (*ANeuralNetworksBurst_create)(ANeuralNetworksCompilation* compilation, 893 ANeuralNetworksBurst** burst); 894 895 /** 896 * Destroys the burst object. 897 * 898 * Available since API level 29. 899 * 900 * @param burst The burst object to be destroyed. Passing NULL is acceptable 901 * and results in no operation. 902 */ 903 void (*ANeuralNetworksBurst_free)(ANeuralNetworksBurst* burst); 904 905 /** 906 * Schedule synchronous evaluation of the execution on a burst object. 907 * 908 * <p>Schedules synchronous evaluation of the execution. Returns once the 909 * execution has completed and the outputs are ready to be consumed.</p> 910 * 911 * <p>There must be at most one {@link ANeuralNetworksExecution} processing at 912 * any given time for any given burst object. Any 913 * {@link ANeuralNetworksExecution} launched before the previous has finished 914 * will result in ANEURALNETWORKS_BAD_STATE.</p> 915 * 916 * Available since API level 29. 917 * 918 * @param burst The burst object to execute on. 919 * @param execution The execution to be scheduled and executed. The execution 920 * must be created from the same {@link 921 * ANeuralNetworksCompilation} as the burst object. 922 * 923 * @return ANEURALNETWORKS_NO_ERROR if the execution completed normally. 924 */ 925 int (*ANeuralNetworksExecution_burstCompute)( 926 ANeuralNetworksExecution* execution, ANeuralNetworksBurst* burst); 927 928 /** 929 * Creates a shared memory object from an AHardwareBuffer handle. 930 * 931 * If the shared memory is backed by an AHardwareBuffer of 932 * AHARDWAREBUFFER_FORMAT_BLOB format, it can be used the same way as 933 * shared memory created from a file handle. See 934 * {@link ANeuralNetworksMemory} for a description on how to use this 935 * shared memory. 936 * 937 * If the shared memory is backed by an AHardwareBuffer of a format other 938 * than AHARDWAREBUFFER_FORMAT_BLOB, it can only be used for Model inputs 939 * and outputs. When calling 940 * {@link ANeuralNetworksExecution_setInputFromMemory} or 941 * {@link ANeuralNetworksExecution_setOutputFromMemory} with the shared 942 * memory, both offset and length must be set to zero and the entire 943 * memory region will be associated with the specified input or output 944 * operand. There is no guarantee that an arbitrary AHardwareBuffer_Format 945 * and AHardwareBuffer_UsageFlags combination can be used by arbitrary 946 * devices. The execution will fail if selected set of devices cannot 947 * consume the buffer. 948 * 949 * Calling {@link ANeuralNetworksModel_setOperandValueFromMemory} with 950 * shared memory backed by an AHardwareBuffer of a format other than 951 * AHARDWAREBUFFER_FORMAT_BLOB is disallowed. 952 * 953 * TODO(miaowang): add documentation about intended usage with 954 * introspection API. 955 * 956 * Available since API level 29. 957 * 958 * @param ahwb The AHardwareBuffer handle. 959 * @param memory The memory object to be created. 960 * Set to NULL if unsuccessful. 961 * 962 * @return ANEURALNETWORKS_NO_ERROR if the request completed normally. 963 * 964 * @see AHardwareBuffer 965 */ 966 int (*ANeuralNetworksMemory_createFromAHardwareBuffer)( 967 const AHardwareBuffer* ahwb, ANeuralNetworksMemory** memory); 968 969 /** 970 * Specifies whether duration of the {@link ANeuralNetworksExecution} is to be 971 * measured. By default, duration is not measured. 972 * 973 * The {@link ANeuralNetworksExecution} must have been created with 974 * {@link ANeuralNetworksCompilation_createForDevices} with numDevices = 1. 975 * 976 * See {@link ANeuralNetworksExecution} for information on multithreaded 977 * usage. 978 * 979 * Available since API level 29. 980 * 981 * @param execution The execution to be modified. 982 * @param measure 'true' if duration is to be measured, 'false' if not. 983 * 984 * @return ANEURALNETWORKS_NO_ERROR if successful. 985 */ 986 int (*ANeuralNetworksExecution_setMeasureTiming)( 987 ANeuralNetworksExecution* execution, bool measure); 988 989 /** 990 * Get the time spent in the specified {@link ANeuralNetworksExecution}, in 991 * nanoseconds. The execution must have completed. 992 * 993 * @param execution The execution to be queried. 994 * @param durationCode The measurement to be queried, specified by {@link 995 * DurationCode}. 996 * @param duration The returned duration. If no measurement was requested by 997 * {@link ANeuralNetworksExecution_setMeasureTiming}, or for 998 * some other reason the duration is not available, UINT64_MAX will be 999 * returned. A particular device need not support any given measurement. 1000 * 1001 * @return ANEURALNETWORKS_NO_ERROR if successful. 1002 */ 1003 int (*ANeuralNetworksExecution_getDuration)( 1004 const ANeuralNetworksExecution* execution, int32_t durationCode, 1005 uint64_t* duration); 1006 1007 /**/ 1008 }; 1009 1010 /** 1011 * Load the NNAPI implementation from the shared libraries. 1012 * The NnApi structure is filled with all the pointers. If one function doesn't 1013 * exist, a null pointer is stored. 1014 */ 1015 const NnApi* NnApiImplementation(); 1016 1017 #endif // TENSORFLOW_LITE_NNAPI_NNAPI_IMPLEMENTATION_H_ 1018