Define AIDL reusable execution interface. am: 018fc3cac8 (96b1e35e) · Commits · e / os / android_hardware_interfaces

compatibility_matrices/compatibility_matrix.current.xml

+1 −1

Original line number	Diff line number	Diff line
		@@ -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>

neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IExecution.aidl

0 → 100644

+39 −0

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

neuralnetworks/aidl/aidl_api/android.hardware.neuralnetworks/current/android/hardware/neuralnetworks/IPreparedModel.aidl

+1 −0

Original line number	Diff line number	Diff line
		@@ -37,6 +37,7 @@ interface IPreparedModel {
		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;
		}

neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl

+4 −4

Original line number	Diff line number	Diff line
		@@ -78,10 +78,10 @@ interface IBurst {
		* 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

neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl

0 → 100644

+153 −0

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