Merge "Add documentation to the Neuralnetworks HIDL HAL." into oc-mr1-dev

import IEvent;

import IPreparedModel;

/**

 * This interface represents a device driver.

 */

interface IDevice {

    /**

     * Gets the capabilities of a driver.

     *

     * @return status ErrorStatus::NONE if successful.

     * @return capabilities Capabilities of the driver.

     */

    getCapabilities() generates (ErrorStatus status, Capabilities capabilities);

    /**

     * Gets the supported operations in a model.

     *

     * getSupportedSubgraph provides a more nuanced indication on whether a

     * model is able to be compiled by the driver. Having the entire model

     * allows for additional information such as tensor shapes to inputs or

     * tensor strides, information which is not known in "initialize".

     *

     * @param model A model whose operations--and their corresponding

     *              operands--are to be verified by the driver.

     * @return status ErrorStatus::NONE if successful.

     * @return supportedOperations A list of supported operations, where true

     *                             indicates the operation is supported and

     *                             false indicates the operation is not

     *                             supported. The index of "supported"

     *                             corresponds with the index of the operation

     *                             it is describing.

     */

    getSupportedOperations(Model model)

            generates (ErrorStatus status, vec<bool> supportedOperations);

    /**

     * Prepares a model for execution.

     *

     * prepareModel is used to make any necessary transformations or alternative

     * representations to a model for execution, possible including

     * transformations on the constant data, optimization on the model's graph,

     * or compilation into the device's native binary.

     *

     * The only information that may be unknown to the model at this stage is

     * the shape of the tensors, which may only be known at execution time.

     *

     * @param model The model to be prepared for execution.

     * @param event A synchronization callback that must be signaled once the

     *              execution has finished.

     * @return status ErrorStatus::NONE if successful.

     * @return preparedModel A handle to the resultant prepared model.

     */

    prepareModel(Model model, IEvent event)

            generates (ErrorStatus status, IPreparedModel preparedModel);

    /**

     * Returns the current status of a driver.

     *

     * @return status Status of the driver.

     */

    getStatus() generates (DeviceStatus status);

};

 * indicate to the Neuralnetworks runtime whether the computation was

 * successful or not, and that the corresponding output is ready to be

 * consumed if the execution was successful.

 *

 * TODO: Mention that "notify" is also called by a runtime thread

 * during CPU fallback execution? Depends on whether the HIDL comments

 * are strictly for vendors or not.

 */

interface IEvent {

    /**

     * IEvent::notify is called by the server thread (i.e. the thread doing the

     * work) to mark the event as completed so that any threads requiring the

     * corresponding resources can continue executing.

     * IEvent::notify is called by the server thread (i.e., the thread doing

     * the work) to mark the event as completed so that any threads requiring

     * the corresponding output can continue executing.

     *

     * @param status Status of the execution associated with the Event.

     *               Should be SUCCESS or ERROR.

     * @param status ErrorStatus::NONE if successful.

     */

    oneway notify(ErrorStatus status);

};

 * limitations under the License.

 */

/* This HAL is a work in progress */

package android.hardware.neuralnetworks@1.0;

import IEvent;

/**

 * IPreparedModel describes a model that has been prepared for execution and

 * is used to launch executions.

 */

interface IPreparedModel {

    // Multiple threads can call this execute function concurrently.

    /**

     * Spawns an asynchronous execution on a prepared model.

     *

     * Executions are asynchronous with respect to the Neuralnetworks runtime.

     * To support this, IPreparedModel::execute must spawn a new task and return

     * whether the task was successfully launched. The asynchronous task which

     * performs the execution must call event's IEvent::notify with the status

     * of the execution immediately after the execution has finished.

     *

     * Multiple threads can call this execute function concurrently.

     *

     * @param request The input and output information on which the prepared

     *                model is to be executed.

     *                prepared model.

     * @param event A callback used for synchronization that must be signaled

     *              once the execution has finished.

     * @return status ErrorStatus::NONE if the asynchronous task was

     *                successfully launched.

     */

    execute(Request request, IEvent event) generates (ErrorStatus status);

};