Merge "NNAPI HAL: Change IEvent to explicit callbacks" into oc-mr1-dev (75d2b865) · Commits · e / os / android_hardware_interfaces

neuralnetworks/1.0/Android.bp

+14 −7

Original line number	Diff line number	Diff line
		@@ -5,8 +5,9 @@ filegroup {
		srcs: [
		"types.hal",
		"IDevice.hal",
		"IEvent.hal",
		"IExecutionCallback.hal",
		"IPreparedModel.hal",
		"IPreparedModelCallback.hal",
		],
		}

		@@ -20,8 +21,9 @@ genrule {
		out: [
		"android/hardware/neuralnetworks/1.0/types.cpp",
		"android/hardware/neuralnetworks/1.0/DeviceAll.cpp",
		"android/hardware/neuralnetworks/1.0/EventAll.cpp",
		"android/hardware/neuralnetworks/1.0/ExecutionCallbackAll.cpp",
		"android/hardware/neuralnetworks/1.0/PreparedModelAll.cpp",
		"android/hardware/neuralnetworks/1.0/PreparedModelCallbackAll.cpp",
		],
		}

		@@ -40,16 +42,21 @@ genrule {
		"android/hardware/neuralnetworks/1.0/BnHwDevice.h",
		"android/hardware/neuralnetworks/1.0/BpHwDevice.h",
		"android/hardware/neuralnetworks/1.0/BsDevice.h",
		"android/hardware/neuralnetworks/1.0/IEvent.h",
		"android/hardware/neuralnetworks/1.0/IHwEvent.h",
		"android/hardware/neuralnetworks/1.0/BnHwEvent.h",
		"android/hardware/neuralnetworks/1.0/BpHwEvent.h",
		"android/hardware/neuralnetworks/1.0/BsEvent.h",
		"android/hardware/neuralnetworks/1.0/IExecutionCallback.h",
		"android/hardware/neuralnetworks/1.0/IHwExecutionCallback.h",
		"android/hardware/neuralnetworks/1.0/BnHwExecutionCallback.h",
		"android/hardware/neuralnetworks/1.0/BpHwExecutionCallback.h",
		"android/hardware/neuralnetworks/1.0/BsExecutionCallback.h",
		"android/hardware/neuralnetworks/1.0/IPreparedModel.h",
		"android/hardware/neuralnetworks/1.0/IHwPreparedModel.h",
		"android/hardware/neuralnetworks/1.0/BnHwPreparedModel.h",
		"android/hardware/neuralnetworks/1.0/BpHwPreparedModel.h",
		"android/hardware/neuralnetworks/1.0/BsPreparedModel.h",
		"android/hardware/neuralnetworks/1.0/IPreparedModelCallback.h",
		"android/hardware/neuralnetworks/1.0/IHwPreparedModelCallback.h",
		"android/hardware/neuralnetworks/1.0/BnHwPreparedModelCallback.h",
		"android/hardware/neuralnetworks/1.0/BpHwPreparedModelCallback.h",
		"android/hardware/neuralnetworks/1.0/BsPreparedModelCallback.h",
		],
		}

neuralnetworks/1.0/IDevice.hal

+47 −18

Original line number	Diff line number	Diff line
		@@ -16,8 +16,7 @@

		package android.hardware.neuralnetworks@1.0;

		import IEvent;
		import IPreparedModel;
		import IPreparedModelCallback;

		/**
		* This interface represents a device driver.
		@@ -37,10 +36,9 @@ interface IDevice {
		/**
		* 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".
		* getSupportedSubgraph indicates which operations of a model are fully
		* supported by the vendor driver. If an operation may not be supported for
		* any reason, getSupportedOperations must return false for that operation.
		*
		* @param model A model whose operations--and their corresponding
		* operands--are to be verified by the driver.
		@@ -48,7 +46,7 @@ interface IDevice {
		* - NONE if successful
		* - DEVICE_UNAVAILABLE if driver is offline or busy
		* - GENERAL_FAILURE if there is an unspecified error
		* - INVALID_ARGUMENT when provided model is invalid
		* - INVALID_ARGUMENT if provided model is invalid
		* @return supportedOperations A list of supported operations, where true
		* indicates the operation is supported and
		* false indicates the operation is not
		@@ -60,29 +58,60 @@ interface IDevice {
		generates (ErrorStatus status, vec<bool> supportedOperations);

		/**
		* Prepares a model for execution.
		* Creates a prepared model for execution.
		*
		* prepareModel is used to make any necessary transformations or alternative
		* representations to a model for execution, possible including
		* representations to a model for execution, possiblly including
		* transformations on the constant data, optimization on the model's graph,
		* or compilation into the device's native binary format.
		* or compilation into the device's native binary format. The model itself
		* is not changed.
		*
		* The model is prepared asynchronously with respect to the caller. The
		* prepareModel function must verify the inputs to the prepareModel function
		* are correct. If there is an error, prepareModel must immediately invoke
		* the callback with the appropriate ErrorStatus value and nullptr for the
		* IPreparedModel, then return with the same ErrorStatus. If the inputs to
		* the prepareModel function are valid and there is no error, prepareModel
		* must launch an asynchronous task to prepare the model in the background,
		* and immediately return from prepareModel with ErrorStatus::NONE. If the
		* asynchronous task fails to launch, prepareModel must immediately invoke
		* the callback with ErrorStatus::GENERAL_FAILURE and nullptr for the
		* IPreparedModel, then return with ErrorStatus::GENERAL_FAILURE.
		*
		* When the asynchronous task has finished preparing the model, it must
		* immediately invoke the callback function provided as an input to
		* prepareModel. If the model was prepared successfully, the callback object
		* must be invoked with an error status of ErrorStatus::NONE and the
		* produced IPreparedModel object. If an error occurred preparing the model,
		* the callback object must be invoked with the appropriate ErrorStatus
		* value and nullptr for the IPreparedModel.
		*
		* 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.
		* the shape of the tensors, which may only be known at execution time. As
		* such, some driver services may return partially prepared models, where
		* the prepared model can only be finished when it is paired with a set of
		* inputs to the model. Note that the same prepared model object can be
		* used with different shapes of inputs on different (possibly concurrent)
		* executions.
		*
		* Multiple threads can call prepareModel on the same model concurrently.
		*
		* @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 Error status of the call, must be:
		* @param callback A callback object used to return the error status of
		* preparing the model for execution and the prepared model
		* if successful, nullptr otherwise. The callback object's
		* notify function must be called exactly once, even if the
		* model could not be prepared.
		* @return status Error status of launching a task which prepares the model
		* in the background; must be:
		* - NONE if preparation task is successfully launched
		* - DEVICE_UNAVAILABLE if driver is offline or busy
		* - GENERAL_FAILURE if there is an unspecified error
		* - INVALID_ARGUMENT when one of the input arguments is
		* - INVALID_ARGUMENT if one of the input arguments is
		* invalid
		* @return preparedModel A handle to the resultant prepared model.
		*/
		prepareModel(Model model, IEvent event)
		generates (ErrorStatus status, IPreparedModel preparedModel);
		prepareModel(Model model, IPreparedModelCallback callback)
		generates (ErrorStatus status);

		/**
		* Returns the current status of a driver.

neuralnetworks/1.0/IEvent.hal→neuralnetworks/1.0/IExecutionCallback.hal

+44 −0

Original line number	Diff line number	Diff line
		@@ -17,29 +17,28 @@
		package android.hardware.neuralnetworks@1.0;

		/**
		* The IEvent interface is a callback object passed by the
		* Neuralnetworks runtime to the vendor service. It is used as a
		* synchronization primitive between one or more runtime threads and a
		* single asynchronous vendor thread. An event object is passed as an
		* argument to a HIDL call that is expected to take a non-trivial
		* amount of time. When the asynchronous execution thread has
		* completed its computation, it must call "notify" on the event to
		* 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.
		* IExecutionCallback must be used to return the error status result from an
		* execution asynchronously launched from IPreparedModel::execute.
		*/
		interface IEvent {
		interface IExecutionCallback {

		/**
		* 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.
		* notify must be invoked immediately after the asynchronous task has
		* finished performing the execution. notify must be provided with the
		* ErrorStatus resulting from the execution. If the asynchronous task
		* is not launched, notify must be invoked with the appropriate error.
		*
		* @param status Error status returned from the asynchronous task, must be:
		* - NONE if asynchronous task was successful
		* @return param Error status returned from launching the asynchronous task
		* (if the launch fails) or from the asynchronous task itself
		* (if the launch succeeds). Must be:
		* - NONE if the asynchronous execution was successful
		* - DEVICE_UNAVAILABLE if driver is offline or busy
		* - GENERAL_FAILURE if the asynchronous task resulted in 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 to
		* prepareModel is invalid
		*/
		oneway notify(ErrorStatus status);
		};

neuralnetworks/1.0/IPreparedModel.hal

+26 −12

Original line number	Diff line number	Diff line
		@@ -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 @@ import IEvent;
		*/
		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);
		};

neuralnetworks/1.0/IPreparedModelCallback.hal

0 → 100644

+53 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2017 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.0;

		import IPreparedModel;

		/**
		* IPreparedModelCallback must be used to return a prepared model produced by an
		* asynchronous task launched from IDevice::prepareModel.
		*/
		interface IPreparedModelCallback {

		/**
		* notify must be invoked immediately after the asynchronous task holding
		* this callback has finished preparing the model. If the model was
		* successfully prepared, notify must be invoked with ErrorStatus::NONE and
		* the prepared model. If the model was not able to be successfully
		* prepared, notify must be invoked with the appropriate ErrorStatus and
		* nullptr as the IPreparedModel. If the asynchronous task holding this
		* callback fails to launch or if the model provided to
		* IDevice::prepareModel is invalid, notify must be invoked with the
		* appropriate error as well as nullptr for the IPreparedModel.
		*
		* @param status Error status returned from the asynchronous model
		* preparation task; must be:
		* - NONE if the asynchronous task successfully prepared the
		* model
		* - DEVICE_UNAVAILABLE if driver is offline or busy
		* - GENERAL_FAILURE if the asynchronous task resulted in an
		* unspecified error
		* - INVALID_ARGUMENT if one of the input arguments to
		* prepareModel is invalid
		* @param preparedModel A model that has been asynchronously prepared for
		* execution. If the model was unable to be prepared
		* due to an error, nullptr must be passed in place of
		* the IPreparedModel object.
		*/
		oneway notify(ErrorStatus status, IPreparedModel preparedModel);
		};