NNAPI HAL: Change IEvent to explicit callbacks
IEvent was a synchronization primitive which caused some confusion
in the interface. Originally the event object was paired with an
asynchronous task, and the asynchronous task would signal this event
when the corresponding output was ready to be used.
In the case of IDevice::prepareModel, the function call would return an
IPreparedModel object that was not guaranteed to be prepared until the
runtime had returned from waiting on the corresponding event object.
The event object has been changed to two explicit callbacks--
IPreparedModelCallback and IExecutionCallback. Now,
IDevice::prepareModel no longer returns an unfinished IPreparedModel;
instead, it will pass the IPreparedModel object to the runtime through
IPreparedModelCallback::notify. When the runtime retreives the
IPreparedModel object, the asynchronous task has already finished
preparing the model.
The two callbacks are used for different purposes. Each has its own
version of notify to pass the data back to the runtime:
* IPreparedModelCallback::notify(ErrorStatus, IPreparedModel)
* IExecutionCallback::notify(ErrorStatus)
Bug: 63905942
Test: mm, vts, ml/nn/runtime/tests
Change-Id: I0c88cd262ba762e0af15e9da31ebe813a5d150b2
diff --git a/neuralnetworks/1.0/IPreparedModel.hal b/neuralnetworks/1.0/IPreparedModel.hal
index 5df883e..ee406fb 100644
--- a/neuralnetworks/1.0/IPreparedModel.hal
+++ b/neuralnetworks/1.0/IPreparedModel.hal
@@ -16,7 +16,7 @@
package android.hardware.neuralnetworks@1.0;
-import IEvent;
+import IExecutionCallback;
/**
* IPreparedModel describes a model that has been prepared for execution and
@@ -24,28 +24,42 @@
*/
interface IPreparedModel {
/**
- * Spawns an asynchronous execution on a prepared model.
+ * Launches 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.
+ * The execution is performed asynchronously with respect to the caller.
+ * execute must verify the inputs to the function are correct. If there is
+ * an error, execute 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 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 must immediately invoke the callback with
+ * ErrorStatus::GENERAL_FAILURE, then return with
+ * ErrorStatus::GENERAL_FAILURE.
*
- * Multiple threads can call this execute function concurrently.
+ * When the asynchronous task has finished its execution, it must
+ * immediately invoke the callback object provided as an input to the
+ * execute function. This callback must be provided with the ErrorStatus of
+ * the execution.
+ *
+ * Multiple threads can call the execute function on the same IPreparedModel
+ * object concurrently with different requests.
*
* @param request The input and output information on which the prepared
* model is to be executed.
- * @param event A callback used for synchronization that must be signaled
- * once the execution has finished.
+ * @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 when one of the input arguments is
+ * - INVALID_ARGUMENT if one of the input arguments is
* invalid
*/
- execute(Request request, IEvent event) generates (ErrorStatus status);
+ execute(Request request, IExecutionCallback callback)
+ generates (ErrorStatus status);
};