/*
 * 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);
};