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 launch is successful, the caller must not change the content of 51 * any data object referenced by 'request' (described by the 52 * {@link @1.0::DataLocation} of a {@link @1.0::RequestArgument}) until the 53 * asynchronous task has invoked the callback object. The asynchronous task 54 * must not change the content of any of the data objects corresponding to 55 * 'request' inputs. 56 * 57 * If the prepared model was prepared from a model wherein all tensor 58 * operands have fully specified dimensions, and the inputs to the function 59 * are valid, then: 60 * - the execution should launch successfully (ErrorStatus::NONE): There 61 * must be no failure unless the device itself is in a bad state. 62 * - if at execution time every operation's input operands have legal 63 * values, the execution should complete successfully (ErrorStatus::NONE): 64 * There must be no failure unless the device itself is in a bad state. 65 * 66 * Any number of calls to the execute, execute_1_2, and executeSynchronously 67 * functions, in any combination, may be made concurrently, even on the same 68 * IPreparedModel object. 69 * 70 * @param request The input and output information on which the prepared 71 * model is to be executed. 72 * @param measure Specifies whether or not to measure duration of the execution. 73 * The duration runs from the time the driver sees the call 74 * to the execute_1_2 function to the time the driver invokes 75 * the callback. 76 * @param callback A callback object used to return the error status of 77 * the execution. The callback object's notify function must 78 * be called exactly once, even if the execution was 79 * unsuccessful. 80 * @return status Error status of the call, must be: 81 * - NONE if task is successfully launched 82 * - DEVICE_UNAVAILABLE if driver is offline or busy 83 * - GENERAL_FAILURE if there is an unspecified error 84 * - OUTPUT_INSUFFICIENT_SIZE if provided output buffer is 85 * not large enough to store the resultant values 86 * - INVALID_ARGUMENT if one of the input arguments is 87 * invalid 88 */ 89 execute_1_2(Request request, MeasureTiming measure, IExecutionCallback callback) 90 generates (ErrorStatus status); 91 92 /** 93 * Performs a synchronous execution on a prepared model. 94 * 95 * The execution is performed synchronously with respect to the caller. 96 * executeSynchronously must verify the inputs to the function are 97 * correct. If there is an error, executeSynchronously must immediately 98 * return with the appropriate ErrorStatus value. If the inputs to the 99 * function are valid and there is no error, executeSynchronously must 100 * perform the execution, and must not return until the execution is 101 * complete. 102 * 103 * The caller must not change the content of any data object referenced by 104 * 'request' (described by the {@link @1.0::DataLocation} of a 105 * {@link @1.0::RequestArgument}) until executeSynchronously 106 * returns. executeSynchronously must not change the content of any of the 107 * data objects corresponding to 'request' inputs. 108 * 109 * If the prepared model was prepared from a model wherein all tensor 110 * operands have fully specified dimensions, and the inputs to the function 111 * are valid, and at execution time every operation's input operands have 112 * legal values, then the execution should complete successfully 113 * (ErrorStatus::NONE): There must be no failure unless the device itself is 114 * in a bad state. 115 * 116 * Any number of calls to the execute, execute_1_2, and executeSynchronously 117 * functions, in any combination, may be made concurrently, even on the same 118 * IPreparedModel object. 119 * 120 * @param request The input and output information on which the prepared 121 * model is to be executed. 122 * @param measure Specifies whether or not to measure duration of the execution. 123 * The duration runs from the time the driver sees the call 124 * to the executeSynchronously function to the time the driver 125 * returns from the function. 126 * @return status Error status of the execution, must be: 127 * - NONE if execution is performed successfully 128 * - DEVICE_UNAVAILABLE if driver is offline or busy 129 * - GENERAL_FAILURE if there is an unspecified error 130 * - OUTPUT_INSUFFICIENT_SIZE if at least one output 131 * operand buffer is not large enough to store the 132 * corresponding output 133 * - INVALID_ARGUMENT if one of the input arguments is 134 * invalid 135 * @return outputShapes A list of shape information of model output operands. 136 * The index into "outputShapes" corresponds to the index 137 * of the output operand in the Request outputs vector. 138 * outputShapes must be empty unless the status is either 139 * NONE or OUTPUT_INSUFFICIENT_SIZE. 140 * @return Timing Duration of execution. Unless measure is YES and status is 141 * NONE, all times must be reported as UINT64_MAX. A driver may 142 * choose to report any time as UINT64_MAX, indicating that 143 * measurement is not available. 144 */ 145 executeSynchronously(Request request, MeasureTiming measure) 146 generates (ErrorStatus status, vec<OutputShape> outputShapes, Timing timing); 147 148 /** 149 * Configure a Burst object used to execute multiple inferences on a 150 * prepared model in rapid succession. 151 * 152 * If the prepared model was prepared from a model wherein all tensor 153 * operands have fully specified dimensions, and a valid serialized Request 154 * is sent to the Burst for execution, and at execution time every 155 * operation's input operands have legal values, then the execution should 156 * complete successfully (ErrorStatus::NONE): There must be no failure 157 * unless the device itself is in a bad state. 158 * 159 * @param callback A callback object used to retrieve memory resources 160 * corresponding to unique identifiers ("slots"). 161 * @param requestChannel FMQ used by the client to send a serialized Request 162 * to the Burst for execution. The client must not 163 * change the content of any data object referenced by 164 * the Request (described by the 165 * {@link @1.0::DataLocation} of an 166 * {@link OperandInformation}) until a result has been 167 * received from resultChannel. Execution must not 168 * change the content of any of the data objects 169 * corresponding to Request inputs. requestChannel 170 * must not be used to pass a second Request object 171 * until a result has been received from 172 * resultChannel. The client must send the request 173 * messages to the consumer atomically by using 174 * MessageQueue::writeBlocking if the queue is 175 * blocking, or by using MessageQueue::write if the 176 * queue is non-blocking. When the service receives a 177 * packet, it must dequeue the entire packet from the 178 * requestChannel. The client must not send a request 179 * packet that exceeds the length of the FMQ. 180 * @param resultChannel FMQ used by the service to return the results of an 181 * execution to the client: the status of the 182 * execution, OutputShape of all output tensors, and 183 * timing information. resultChannel must be used to 184 * return the results if a Request was sent through the 185 * requestChannel. The service must send the result 186 * messages to the consumer atomically by using 187 * MessageQueue::writeBlocking if the queue is 188 * blocking, or by using MessageQueue::write if the 189 * queue is non-blocking. When the client receives a 190 * packet, it must dequeue the entire packet from the 191 * resultChannel. If the packet's length exceeds the 192 * size of the FMQ, the service must not send this 193 * result packet; instead, the service must send a 194 * packet consisting of the error code 195 * ErrorStatus::GENERAL_FAILURE, no information for the 196 * outputShapes, and an indication that timing 197 * information is unavailable. 198 * @return status Error status of configuring the execution burst, must be: 199 * - NONE if the burst is successfully configured 200 * - DEVICE_UNAVAILABLE if driver is offline or busy 201 * - GENERAL_FAILURE if there is an unspecified error 202 * - INVALID_ARGUMENT if one of the input arguments is 203 * invalid 204 * @return context Object containing all resources (such as cached 205 * hidl_memory) related to a Burst if successful, otherwise 206 * nullptr. 207 */ 208 configureExecutionBurst(IBurstCallback callback, 209 fmq_sync<FmqRequestDatum> requestChannel, 210 fmq_sync<FmqResultDatum> resultChannel) 211 generates (ErrorStatus status, IBurstContext context); 212}; 213