Define AIDL reusable execution interface.
This CL defines the AIDL interface for reusable execution.
This CL also fixes a stale statement in IBurst about deadlineNs:
boot_clock should be used rather than steady_clock.
Bug: 202405342
Bug: 202431255
Test: NNT_static
Test: VtsHalNeuralnetworksTargetTest
Change-Id: I07d26909081018ffd92264d76109a66d4a0de3bd
Merged-In: I07d26909081018ffd92264d76109a66d4a0de3bd
(cherry picked from commit 0d9b1a9d287d3751c305742af81850b7ceea0c6b)
diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml
index 6879a95..db99423 100644
--- a/compatibility_matrices/compatibility_matrix.current.xml
+++ b/compatibility_matrices/compatibility_matrix.current.xml
@@ -411,7 +411,7 @@
</hal>
<hal format="aidl" optional="true">
<name>android.hardware.neuralnetworks</name>
- <version>1-3</version>
+ <version>1-4</version>
<interface>
<name>IDevice</name>
<regex-instance>.*</regex-instance>
diff --git a/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IExecution.aidl b/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IExecution.aidl
new file mode 100644
index 0000000..ab5275e
--- /dev/null
+++ b/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IExecution.aidl
@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2021 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.
+ */
+///////////////////////////////////////////////////////////////////////////////
+// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
+///////////////////////////////////////////////////////////////////////////////
+
+// This file is a snapshot of an AIDL file. Do not edit it manually. There are
+// two cases:
+// 1). this is a frozen version file - do not edit this in any case.
+// 2). this is a 'current' file. If you make a backwards compatible change to
+// the interface (from the latest frozen version), the build system will
+// prompt you to update this file with `m <name>-update-api`.
+//
+// You must not make a backward incompatible change to any AIDL file built
+// with the aidl_interface module type with versions property set. The module
+// type is used to build AIDL files in a way that they can be used across
+// independently updatable components of the system. If a device is shipped
+// with such a backward incompatible change, it has a high risk of breaking
+// later when a module using the interface is updated, e.g., Mainline modules.
+
+package android.hardware.neuralnetworks;
+@VintfStability
+interface IExecution {
+ android.hardware.neuralnetworks.ExecutionResult executeSynchronously(in long deadlineNs);
+ android.hardware.neuralnetworks.FencedExecutionResult executeFenced(in ParcelFileDescriptor[] waitFor, in long deadlineNs, in long durationNs);
+}
diff --git a/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IPreparedModel.aidl b/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IPreparedModel.aidl
index fccb5dc..f899567 100644
--- a/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IPreparedModel.aidl
+++ b/neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IPreparedModel.aidl
@@ -37,6 +37,7 @@
android.hardware.neuralnetworks.ExecutionResult executeSynchronously(in android.hardware.neuralnetworks.Request request, in boolean measureTiming, in long deadlineNs, in long loopTimeoutDurationNs);
android.hardware.neuralnetworks.FencedExecutionResult executeFenced(in android.hardware.neuralnetworks.Request request, in ParcelFileDescriptor[] waitFor, in boolean measureTiming, in long deadlineNs, in long loopTimeoutDurationNs, in long durationNs);
android.hardware.neuralnetworks.IBurst configureExecutionBurst();
+ android.hardware.neuralnetworks.IExecution createReusableExecution(in android.hardware.neuralnetworks.Request request, in boolean measureTiming, in long loopTimeoutDurationNs);
const long DEFAULT_LOOP_TIMEOUT_DURATION_NS = 2000000000;
const long MAXIMUM_LOOP_TIMEOUT_DURATION_NS = 15000000000;
}
diff --git a/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl b/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl
index decdc48..b089c49 100644
--- a/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl
+++ b/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl
@@ -78,10 +78,10 @@
* runs from the time the driver sees the call to the executeSynchronously
* function to the time the driver returns from the function.
* @param deadlineNs The time by which the execution is expected to complete. The time is
- * measured in nanoseconds since epoch of the steady clock (as from
- * std::chrono::steady_clock). If the execution cannot be finished by the
- * deadline, the execution may be aborted. Passing -1 means the deadline is
- * omitted. Other negative values are invalid.
+ * measured in nanoseconds since boot (as from clock_gettime(CLOCK_BOOTTIME,
+ * &ts) or ::android::base::boot_clock). If the execution cannot be finished
+ * by the deadline, the execution may be aborted. Passing -1 means the
+ * deadline is omitted. Other negative values are invalid.
* @param loopTimeoutDurationNs The maximum amount of time in nanoseconds that should be spent
* executing a {@link OperationType::WHILE} operation. If a loop
* condition model does not output false within this duration, the
diff --git a/neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl b/neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl
new file mode 100644
index 0000000..3cb9c1a
--- /dev/null
+++ b/neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl
@@ -0,0 +1,153 @@
+/*
+ * Copyright (C) 2021 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;
+
+import android.hardware.neuralnetworks.ExecutionResult;
+import android.hardware.neuralnetworks.FencedExecutionResult;
+
+/**
+ * IExecution represents a reusable execution object with request and most other execution
+ * properties fixed. It is used to launch executions.
+ *
+ * At most one execution may occur on a reusable execution object at any given time, either by
+ * means of executeSynchronously or executeFenced.
+ *
+ * An IExecution object is used to control a set of executions on the same prepared model with
+ * the same request and properties. IExecution objects enable some optimizations:
+ * (1) An IExecution object can preserve resources between executions. For example, a driver can
+ * map a memory object when the IExecution object is created and cache the mapping for reuse in
+ * subsequent executions. Any cached resource can be released when the IExecution object is
+ * destroyed.
+ * (2) Because an IExecution object may be used for at most one execution at a time, any transient
+ * execution resources such as intermediate tensors can be allocated once when the IExecution
+ * object is created and freed when the IExecution object is destroyed.
+ * (3) An IExecution object is created for a fixed request. This enables the implementation to apply
+ * request-specific optimizations. For example, an implementation can avoid request validation
+ * and conversions when the IExecution object is reused. An implementation may also choose to
+ * specialize the dynamic tensor shapes in the IExecution object according to the request.
+ */
+@VintfStability
+interface IExecution {
+ /**
+ * Performs a synchronous execution on the reusable execution object.
+ *
+ * The execution is performed synchronously with respect to the caller. executeSynchronously
+ * must verify the inputs to the function are correct, and the usages of memory pools allocated
+ * by IDevice::allocate are valid. If there is an error, executeSynchronously must immediately
+ * return a service specific exception 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 the 'request'
+ * provided in {@link IPreparedModel::createReusableExecution} (described by the
+ * {@link DataLocation} of a {@link RequestArgument}) until executeSynchronously returns.
+ * executeSynchronously must not change the content of any of the data objects corresponding to
+ * 'request' inputs.
+ *
+ * If the execution object was configured from a prepared 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: there must be no failure unless the device itself is in a bad state.
+ *
+ * If the execution object was created with measureTiming being true and the execution is
+ * successful, the driver may report the timing information in the returning
+ * {@link ExecutionResult}. The duration runs from the time the driver sees the call to the time
+ * the driver returns from the function.
+ *
+ * executeSynchronously may be called with an optional deadline. If the execution is not able to
+ * be completed before the provided deadline, the execution may be aborted, and either
+ * {@link ErrorStatus::MISSED_DEADLINE_TRANSIENT} or {@link
+ * ErrorStatus::MISSED_DEADLINE_PERSISTENT} may be returned. The error due to an abort must be
+ * sent the same way as other errors, described above.
+ *
+ * @param deadlineNs The time by which the execution is expected to complete. The time is
+ * measured in nanoseconds since boot (as from clock_gettime(CLOCK_BOOTTIME,
+ * &ts) or ::android::base::boot_clock). If the execution cannot be finished
+ * by the deadline, the execution may be aborted. Passing -1 means the
+ * deadline is omitted. Other negative values are invalid.
+ * @return ExecutionResult parcelable, containing the status of the execution, output shapes
+ * and timing information.
+ * @throws ServiceSpecificException with one of the following ErrorStatus values:
+ * - 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
+ * - MISSED_DEADLINE_* if the execution is aborted because it cannot be completed by the
+ * deadline
+ * - RESOURCE_EXHAUSTED_* if the task was aborted by the driver
+ */
+ ExecutionResult executeSynchronously(in long deadlineNs);
+
+ /**
+ * Launch a fenced asynchronous execution on the reusable execution object.
+ *
+ * The execution is performed asynchronously with respect to the caller. executeFenced must
+ * verify the inputs to the function are correct, and the usages of memory pools allocated by
+ * IDevice::allocate are valid. If there is an error, executeFenced must immediately return a
+ * service specific exception with the corresponding ErrorStatus. If the inputs to the function
+ * are valid and there is no error, executeFenced must dispatch an asynchronous task to perform
+ * the execution in the background, and immediately return a {@link FencedExecutionResult}
+ * containing two fields: a callback (which can be used by the client to query the duration and
+ * runtime error status) and a sync fence (which will be signaled once the execution is
+ * completed). If the task has finished before the call returns, syncFence file descriptor may
+ * be set to -1. The execution must wait for all the sync fences (if any) in waitFor to be
+ * signaled before starting the actual execution.
+ *
+ * When the asynchronous task has finished its execution, it must immediately signal the
+ * syncFence returned from the executeFenced call. After the syncFence is signaled, the task
+ * must not modify the content of any data object referenced by the 'request' provided in
+ * IPreparedModel::createReusableExecution (described by the {@link DataLocation} of a
+ * {@link RequestArgument}).
+ *
+ * executeFenced may be called with an optional deadline and an optional duration. If the
+ * execution is not able to be completed before the provided deadline or within the timeout
+ * duration (measured from when all sync fences in waitFor are signaled), whichever comes
+ * earlier, the execution may be aborted, and either
+ * {@link ErrorStatus::MISSED_DEADLINE_TRANSIENT} or {@link
+ * ErrorStatus::MISSED_DEADLINE_PERSISTENT} may be returned. The error due to an abort must be
+ * sent the same way as other errors, described above.
+ *
+ * If any of the sync fences in waitFor changes to error status after the executeFenced call
+ * succeeds, or the execution is aborted because it cannot finish before the deadline has been
+ * reached or the duration has elapsed, the driver must immediately set the returned syncFence
+ * to error status.
+ *
+ * @param waitFor A vector of sync fence file descriptors. Execution must not start until all
+ * sync fences have been signaled.
+ * @param deadlineNs The time by which the execution is expected to complete. The time is
+ * measured in nanoseconds since boot (as from clock_gettime(CLOCK_BOOTTIME,
+ * &ts) or ::android::base::boot_clock). If the execution cannot be finished
+ * by the deadline, the execution may be aborted. Passing -1 means the
+ * deadline is omitted. Other negative values are invalid.
+ * @param durationNs The length of time in nanoseconds within which the execution is expected
+ * to complete after all sync fences in waitFor are signaled. If the
+ * execution cannot be finished within the duration, the execution may be
+ * aborted. Passing -1 means the duration is omitted. Other negative values
+ * are invalid.
+ * @return The FencedExecutionResult parcelable, containing IFencedExecutionCallback and the
+ * sync fence.
+ * @throws ServiceSpecificException with one of the following ErrorStatus values:
+ * - 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, including fences in error
+ * states.
+ * - MISSED_DEADLINE_* if the execution is aborted because it cannot be completed by the
+ * deadline
+ * - RESOURCE_EXHAUSTED_* if the task was aborted by the driver
+ */
+ FencedExecutionResult executeFenced(
+ in ParcelFileDescriptor[] waitFor, in long deadlineNs, in long durationNs);
+}
diff --git a/neuralnetworks/aidl/android/hardware/neuralnetworks/IPreparedModel.aidl b/neuralnetworks/aidl/android/hardware/neuralnetworks/IPreparedModel.aidl
index 956b626..79053e5 100644
--- a/neuralnetworks/aidl/android/hardware/neuralnetworks/IPreparedModel.aidl
+++ b/neuralnetworks/aidl/android/hardware/neuralnetworks/IPreparedModel.aidl
@@ -21,6 +21,7 @@
import android.hardware.neuralnetworks.ExecutionResult;
import android.hardware.neuralnetworks.FencedExecutionResult;
import android.hardware.neuralnetworks.IBurst;
+import android.hardware.neuralnetworks.IExecution;
import android.hardware.neuralnetworks.Request;
/**
@@ -105,11 +106,12 @@
* IDevice::allocate are valid. If there is an error, executeFenced must immediately return a
* service specific exception with the corresponding ErrorStatus. If the inputs to the function
* are valid and there is no error, executeFenced must dispatch an asynchronous task to perform
- * the execution in the background, assign a sync fence that will be signaled once the execution
- * is completed and immediately return a callback that can be used by the client to query the
- * duration and runtime error status. If the task has finished before the call returns,
- * syncFence file descriptor may be set to -1. The execution must wait for all the sync fences
- * (if any) in waitFor to be signaled before starting the actual execution.
+ * the execution in the background, and immediately return a {@link FencedExecutionResult}
+ * containing two fields: a callback (which can be used by the client to query the duration and
+ * runtime error status) and a sync fence (which will be signaled once the execution is
+ * completed). If the task has finished before the call returns, syncFence file descriptor may
+ * be set to -1. The execution must wait for all the sync fences (if any) in waitFor to be
+ * signaled before starting the actual execution.
*
* When the asynchronous task has finished its execution, it must immediately signal the
* syncFence returned from the executeFenced call. After the syncFence is signaled, the task
@@ -186,4 +188,36 @@
* - RESOURCE_EXHAUSTED_* if the task was aborted by the driver
*/
IBurst configureExecutionBurst();
+
+ /**
+ * Create a reusable execution object to launch multiple executions with the same request and
+ * properties.
+ *
+ * createReusableExecution must verify the inputs to the function are correct, and the usages of
+ * memory pools allocated by IDevice::allocate are valid. If there is an error,
+ * createReusableExecution must immediately return a service specific exception with the
+ * appropriate ErrorStatus value. If the inputs to the function are valid and there is no error,
+ * createReusableExecution must construct a reusable execution.
+ *
+ * @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.
+ * @param loopTimeoutDurationNs The maximum amount of time in nanoseconds that should be spent
+ * executing a {@link OperationType::WHILE} operation. If a loop
+ * condition model does not output false within this duration, the
+ * computation performed on the returned reusable execution object
+ * must be aborted. If -1 is provided, the maximum amount
+ * of time is {@link DEFAULT_LOOP_TIMEOUT_DURATION_NS}. Other
+ * negative values are invalid. When provided, the duration must
+ * not exceed {@link MAXIMUM_LOOP_TIMEOUT_DURATION_NS}.
+ * @return execution An IExecution object representing a reusable execution that has been
+ * specialized for a fixed request.
+ * @throws ServiceSpecificException with one of the following ErrorStatus values:
+ * - 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
+ * - RESOURCE_EXHAUSTED_* if the task was aborted by the driver
+ */
+ IExecution createReusableExecution(
+ in Request request, in boolean measureTiming, in long loopTimeoutDurationNs);
}