1/* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.neuralnetworks@1.2; 18 19import @1.0::ErrorStatus; 20import @1.0::IPreparedModel; 21import @1.0::Request; 22import IBurstCallback; 23import IBurstContext; 24import IExecutionCallback; 25 26/** 27 * IPreparedModel describes a model that has been prepared for execution and 28 * is used to launch executions. 29 */ 30interface IPreparedModel extends @1.0::IPreparedModel { 31 /** 32 * Launches an asynchronous execution on a prepared model. 33 * 34 * The execution is performed asynchronously with respect to the caller. 35 * execute_1_2 must verify the inputs to the function are correct. If there is 36 * an error, execute_1_2 must immediately invoke the callback with the 37 * appropriate ErrorStatus value, then return with the same ErrorStatus. If 38 * the inputs to the function are valid and there is no error, execute_1_2 must 39 * launch an asynchronous task to perform the execution in the background, 40 * and immediately return with ErrorStatus::NONE. If the asynchronous task 41 * fails to launch, execute_1_2 must immediately invoke the callback with 42 * ErrorStatus::GENERAL_FAILURE, then return with 43 * ErrorStatus::GENERAL_FAILURE. 44 * 45 * When the asynchronous task has finished its execution, it must 46 * immediately invoke the callback object provided as an input to the 47 * execute_1_2 function. This callback must be provided with the ErrorStatus of 48 * the execution. 49 * 50 * If the prepared model was prepared from a model wherein all 51 * tensor operands have fully specified dimensions, and the inputs 52 * to the function are valid, then the execution should launch 53 * and complete successfully (ErrorStatus::NONE). There must be 54 * no failure unless the device itself is in a bad state. 55 * 56 * Any number of calls to the execute, execute_1_2, and executeSynchronously 57 * functions, in any combination, may be made concurrently, even on the same 58 * IPreparedModel object. 59 * 60 * @param request The input and output information on which the prepared 61 * model is to be executed. 62 * @param measure Specifies whether or not to measure duration of the execution. 63 * The duration runs from the time the driver sees the call 64 * to the execute_1_2 function to the time the driver invokes 65 * the callback. 66 * @param callback A callback object used to return the error status of 67 * the execution. The callback object's notify function must 68 * be called exactly once, even if the execution was 69 * unsuccessful. 70 * @return status Error status of the call, must be: 71 * - NONE if task is successfully launched 72 * - DEVICE_UNAVAILABLE if driver is offline or busy 73 * - GENERAL_FAILURE if there is an unspecified error 74 * - OUTPUT_INSUFFICIENT_SIZE if provided output buffer is 75 * not large enough to store the resultant values 76 * - INVALID_ARGUMENT if one of the input arguments is 77 * invalid 78 */ 79 execute_1_2(Request request, MeasureTiming measure, IExecutionCallback callback) 80 generates (ErrorStatus status); 81 82 /** 83 * Performs a synchronous execution on a prepared model. 84 * 85 * The execution is performed synchronously with respect to the caller. 86 * executeSynchronously must verify the inputs to the function are 87 * correct. If there is an error, executeSynchronously must immediately 88 * return with the appropriate ErrorStatus value. If the inputs to the 89 * function are valid and there is no error, executeSynchronously must 90 * perform the execution, and must not return until the execution is 91 * complete. 92 * 93 * If the prepared model was prepared from a model wherein all tensor 94 * operands have fully specified dimensions, and the inputs to the function 95 * are valid, then the execution should complete successfully 96 * (ErrorStatus::NONE). There must be no failure unless the device itself is 97 * in a bad state. 98 * 99 * Any number of calls to the execute, execute_1_2, and executeSynchronously 100 * functions, in any combination, may be made concurrently, even on the same 101 * IPreparedModel object. 102 * 103 * @param request The input and output information on which the prepared 104 * model is to be executed. 105 * @param measure Specifies whether or not to measure duration of the execution. 106 * The duration runs from the time the driver sees the call 107 * to the executeSynchronously function to the time the driver 108 * returns from the function. 109 * @return status Error status of the execution, must be: 110 * - NONE if execution is performed successfully 111 * - DEVICE_UNAVAILABLE if driver is offline or busy 112 * - GENERAL_FAILURE if there is an unspecified error 113 * - OUTPUT_INSUFFICIENT_SIZE if at least one output 114 * operand buffer is not large enough to store the 115 * corresponding output 116 * - INVALID_ARGUMENT if one of the input arguments is 117 * invalid 118 * @return outputShapes A list of shape information of model output operands. 119 * The index into "outputShapes" corresponds to the index 120 * of the output operand in the Request outputs vector. 121 * outputShapes must be empty unless the status is either 122 * NONE or OUTPUT_INSUFFICIENT_SIZE. 123 * @return Timing Duration of execution. Unless measure is YES and status is 124 * NONE, all times must be reported as UINT64_MAX. A driver may 125 * choose to report any time as UINT64_MAX, indicating that 126 * measurement is not available. 127 */ 128 executeSynchronously(Request request, MeasureTiming measure) 129 generates (ErrorStatus status, vec<OutputShape> outputShapes, Timing timing); 130 131 /** 132 * Configure a Burst object used to execute multiple inferences on a 133 * prepared model in rapid succession. 134 * 135 * @param callback A callback object used to retrieve memory resources 136 * corresponding to a unique identifiers ("slots"). 137 * @param requestChannel Used by the client to send a serialized Request to 138 * the Burst for execution. requestChannel must not be 139 * used to pass a second Request object until a result 140 * has been received from resultChannel. 141 * @param resultChannel Used by the service to return the results of an 142 * execution to the client: the status of the execution 143 * and OutputShape of all output tensors. resultChannel 144 * must be used to return the results if a Request was 145 * sent through the requestChannel. 146 * @return status Error status of configuring the execution burst, must be: 147 * - NONE if the burst is successfully configured 148 * - DEVICE_UNAVAILABLE if driver is offline or busy 149 * - GENERAL_FAILURE if there is an unspecified error 150 * - INVALID_ARGUMENT if one of the input arguments is 151 * invalid 152 * @return context Object containing all resources (such as cached 153 * hidl_memory) related to a Burst if successful, otherwise 154 * nullptr. 155 */ 156 configureExecutionBurst(IBurstCallback callback, 157 fmq_sync<FmqRequestDatum> requestChannel, 158 fmq_sync<FmqResultDatum> resultChannel) 159 generates (ErrorStatus status, IBurstContext context); 160}; 161