| /* |
| * Copyright (C) 2018 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.hardware.neuralnetworks@1.2; |
| |
| import @1.0::ErrorStatus; |
| import @1.0::IPreparedModel; |
| import @1.0::Request; |
| import IBurstCallback; |
| import IBurstContext; |
| import IExecutionCallback; |
| |
| /** |
| * IPreparedModel describes a model that has been prepared for execution and |
| * is used to launch executions. |
| */ |
| interface IPreparedModel extends @1.0::IPreparedModel { |
| /** |
| * Launches an asynchronous execution on a prepared model. |
| * |
| * The execution is performed asynchronously with respect to the caller. |
| * execute_1_2 must verify the inputs to the function are correct. If there is |
| * an error, execute_1_2 must immediately invoke the callback with the |
| * appropriate ErrorStatus value, then return with the same ErrorStatus. If |
| * the inputs to the function are valid and there is no error, execute_1_2 must |
| * launch an asynchronous task to perform the execution in the background, |
| * and immediately return with ErrorStatus::NONE. If the asynchronous task |
| * fails to launch, execute_1_2 must immediately invoke the callback with |
| * ErrorStatus::GENERAL_FAILURE, then return with |
| * ErrorStatus::GENERAL_FAILURE. |
| * |
| * When the asynchronous task has finished its execution, it must |
| * immediately invoke the callback object provided as an input to the |
| * execute_1_2 function. This callback must be provided with the ErrorStatus of |
| * the execution. |
| * |
| * If the launch is successful, the caller must not change the content of |
| * any data object referenced by 'request' (described by the |
| * {@link @1.0::DataLocation} of a {@link @1.0::RequestArgument}) until the |
| * asynchronous task has invoked the callback object. The asynchronous task |
| * must not change the content of any of the data objects corresponding to |
| * 'request' inputs. |
| * |
| * If the prepared model was prepared from a model wherein all tensor |
| * operands have fully specified dimensions, and the inputs to the function |
| * are valid, then: |
| * - the execution should launch successfully (ErrorStatus::NONE): There |
| * must be no failure unless the device itself is in a bad state. |
| * - if at execution time every operation's input operands have legal |
| * values, the execution should complete successfully (ErrorStatus::NONE): |
| * There must be no failure unless the device itself is in a bad state. |
| * |
| * Any number of calls to the execute, execute_1_2, and executeSynchronously |
| * functions, in any combination, may be made concurrently, even on the same |
| * IPreparedModel object. |
| * |
| * @param request The input and output information on which the prepared |
| * model is to be executed. |
| * @param measure Specifies whether or not to measure duration of the execution. |
| * The duration runs from the time the driver sees the call |
| * to the execute_1_2 function to the time the driver invokes |
| * the callback. |
| * @param callback A callback object used to return the error status of |
| * the execution. The callback object's notify function must |
| * be called exactly once, even if the execution was |
| * unsuccessful. |
| * @return status Error status of the call, must be: |
| * - NONE if task is successfully launched |
| * - DEVICE_UNAVAILABLE if driver is offline or busy |
| * - GENERAL_FAILURE if there is an unspecified error |
| * - OUTPUT_INSUFFICIENT_SIZE if provided output buffer is |
| * not large enough to store the resultant values |
| * - INVALID_ARGUMENT if one of the input arguments is |
| * invalid |
| */ |
| execute_1_2(Request request, MeasureTiming measure, IExecutionCallback callback) |
| generates (ErrorStatus status); |
| |
| /** |
| * Performs a synchronous execution on a prepared model. |
| * |
| * The execution is performed synchronously with respect to the caller. |
| * executeSynchronously must verify the inputs to the function are |
| * correct. If there is an error, executeSynchronously must immediately |
| * return with the appropriate ErrorStatus value. If the inputs to the |
| * function are valid and there is no error, executeSynchronously must |
| * perform the execution, and must not return until the execution is |
| * complete. |
| * |
| * The caller must not change the content of any data object referenced by |
| * 'request' (described by the {@link @1.0::DataLocation} of a |
| * {@link @1.0::RequestArgument}) until executeSynchronously |
| * returns. executeSynchronously must not change the content of any of the |
| * data objects corresponding to 'request' inputs. |
| * |
| * If the prepared model was prepared from a model wherein all tensor |
| * operands have fully specified dimensions, and the inputs to the function |
| * are valid, and at execution time every operation's input operands have |
| * legal values, then the execution should complete successfully |
| * (ErrorStatus::NONE): There must be no failure unless the device itself is |
| * in a bad state. |
| * |
| * Any number of calls to the execute, execute_1_2, and executeSynchronously |
| * functions, in any combination, may be made concurrently, even on the same |
| * IPreparedModel object. |
| * |
| * @param request The input and output information on which the prepared |
| * model is to be executed. |
| * @param measure Specifies whether or not to measure duration of the execution. |
| * The duration runs from the time the driver sees the call |
| * to the executeSynchronously function to the time the driver |
| * returns from the function. |
| * @return status Error status of the execution, must be: |
| * - NONE if execution is performed successfully |
| * - DEVICE_UNAVAILABLE if driver is offline or busy |
| * - GENERAL_FAILURE if there is an unspecified error |
| * - OUTPUT_INSUFFICIENT_SIZE if at least one output |
| * operand buffer is not large enough to store the |
| * corresponding output |
| * - INVALID_ARGUMENT if one of the input arguments is |
| * invalid |
| * @return outputShapes A list of shape information of model output operands. |
| * The index into "outputShapes" corresponds to the index |
| * of the output operand in the Request outputs vector. |
| * outputShapes must be empty unless the status is either |
| * NONE or OUTPUT_INSUFFICIENT_SIZE. |
| * @return Timing Duration of execution. Unless measure is YES and status is |
| * NONE, all times must be reported as UINT64_MAX. A driver may |
| * choose to report any time as UINT64_MAX, indicating that |
| * measurement is not available. |
| */ |
| executeSynchronously(Request request, MeasureTiming measure) |
| generates (ErrorStatus status, vec<OutputShape> outputShapes, Timing timing); |
| |
| /** |
| * Configure a Burst object used to execute multiple inferences on a |
| * prepared model in rapid succession. |
| * |
| * If the prepared model was prepared from a model wherein all tensor |
| * operands have fully specified dimensions, and a valid serialized Request |
| * is sent to the Burst for execution, and at execution time every |
| * operation's input operands have legal values, then the execution should |
| * complete successfully (ErrorStatus::NONE): There must be no failure |
| * unless the device itself is in a bad state. |
| * |
| * @param callback A callback object used to retrieve memory resources |
| * corresponding to unique identifiers ("slots"). |
| * @param requestChannel FMQ used by the client to send a serialized Request |
| * to the Burst for execution. The client must not |
| * change the content of any data object referenced by |
| * the Request (described by the |
| * {@link @1.0::DataLocation} of an |
| * {@link OperandInformation}) until a result has been |
| * received from resultChannel. Execution must not |
| * change the content of any of the data objects |
| * corresponding to Request inputs. requestChannel |
| * must not be used to pass a second Request object |
| * until a result has been received from |
| * resultChannel. The client must send the request |
| * messages to the consumer atomically by using |
| * MessageQueue::writeBlocking if the queue is |
| * blocking, or by using MessageQueue::write if the |
| * queue is non-blocking. When the service receives a |
| * packet, it must dequeue the entire packet from the |
| * requestChannel. The client must not send a request |
| * packet that exceeds the length of the FMQ. |
| * @param resultChannel FMQ used by the service to return the results of an |
| * execution to the client: the status of the |
| * execution, OutputShape of all output tensors, and |
| * timing information. resultChannel must be used to |
| * return the results if a Request was sent through the |
| * requestChannel. The service must send the result |
| * messages to the consumer atomically by using |
| * MessageQueue::writeBlocking if the queue is |
| * blocking, or by using MessageQueue::write if the |
| * queue is non-blocking. When the client receives a |
| * packet, it must dequeue the entire packet from the |
| * resultChannel. If the packet's length exceeds the |
| * size of the FMQ, the service must not send this |
| * result packet; instead, the service must send a |
| * packet consisting of the error code |
| * ErrorStatus::GENERAL_FAILURE, no information for the |
| * outputShapes, and an indication that timing |
| * information is unavailable. |
| * @return status Error status of configuring the execution burst, must be: |
| * - NONE if the burst is successfully configured |
| * - DEVICE_UNAVAILABLE if driver is offline or busy |
| * - GENERAL_FAILURE if there is an unspecified error |
| * - INVALID_ARGUMENT if one of the input arguments is |
| * invalid |
| * @return context Object containing all resources (such as cached |
| * hidl_memory) related to a Burst if successful, otherwise |
| * nullptr. |
| */ |
| configureExecutionBurst(IBurstCallback callback, |
| fmq_sync<FmqRequestDatum> requestChannel, |
| fmq_sync<FmqResultDatum> resultChannel) |
| generates (ErrorStatus status, IBurstContext context); |
| }; |
