platform_hardware_interfaces/neuralnetworks/1.2/IPreparedModel.hal

/*
 * 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 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
     * and 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.
     *
     * 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 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.
     *
     * @param callback A callback object used to retrieve memory resources
     *                 corresponding to a unique identifiers ("slots").
     * @param requestChannel Used by the client to send a serialized Request to
     *                       the Burst for execution. requestChannel must not be
     *                       used to pass a second Request object until a result
     *                       has been received from resultChannel.
     * @param resultChannel Used by the service to return the results of an
     *                      execution to the client: the status of the execution
     *                      and OutputShape of all output tensors. resultChannel
     *                      must be used to return the results if a Request was
     *                      sent through the requestChannel.
     * @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);

    /*
     * Saves the prepared model to cache files.
     *
     * saveToCache is used to save a prepared model to cache files for faster
     * model compilation time when the same model preparation is requested in
     * the future. There are exactly two cache file descriptors provided to the
     * driver: modelCache and dataCache.
     *
     * The dataCache is for caching constant data, possibly including preprocessed
     * and transformed tensor buffers. Any modification to the dataCache should
     * have no worse effect than generating bad output values at execution time.
     *
     * The modelCache is for caching security-sensitive data such as compiled
     * executable machine code in the device's native binary format. A modification
     * to the modelCache may affect the driver's execution behavior, and a malicious
     * client could make use of this to execute beyond the granted permission. Thus,
     * the driver must always check whether the modelCache is corrupted before preparing
     * the model from cache.
     *
     * The two file descriptors must point to two zero-length files with offset
     * positioned at the beginning of the file. The file descriptors may be closed
     * by the client once the method has returned.
     *
     * If the driver decides not to save the prepared model without looking at the
     * input arguments to the saveToCache function, saveToCache must return with
     * ErrorStatus::GENERAL_FAILURE. Otherwise, the saveToCache function must verify
     * the input arguments to the saveToCache function are valid, and return with
     * ErrorStatus::INVALID_ARGUMENT if not. If the inputs are valid but the driver
     * could not save the prepared model, saveToCache must return with the appropriate
     * ErrorStatus. Otherwise, it must write the cache files and return
     * ErrorStatus::NONE. Unless saveToCache returns ErrorStatus::NONE, the contents
     * of the cache files are undefined.
     *
     * @param modelCache A handle holding exactly one cache file descriptor for the
     *                   security-sensitive cache.
     * @param dataCache A handle holding exactly one cache file descriptor for the
     *                  constants' cache.
     * @param token A caching token of length Constant::BYTE_SIZE_OF_CACHE_TOKEN
     *              identifying the prepared model. The same token will be provided
     *              when retrieving the prepared model from cache files with
     *              IDevice::prepareModelFromCache. Tokens should be chosen to have
     *              a low rate of collision for a particular application. The driver
     *              cannot detect a collision; a collision will result in a failed
     *              execution or in a successful execution that produces incorrect
     *              output values.
     * @return status Error status of saveToCache, must be:
     *                - NONE if saveToCache is performed successfully
     *                - DEVICE_UNAVAILABLE if driver is offline or busy
     *                - GENERAL_FAILURE if the driver could not save the
     *                  prepared model or if there is an unspecified error
     *                - INVALID_ARGUMENT if one of the input arguments is invalid,
     *                  unless the driver decides not to save the prepared model
     *                  without looking at the input arguments
     */
    saveToCache(handle modelCache, handle dataCache,
                uint8_t[Constant:BYTE_SIZE_OF_CACHE_TOKEN] token)
        generates (ErrorStatus status);
};