diff options
6 files changed, 237 insertions, 10 deletions
diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml index 6879a95dad..db99423428 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 0000000000..ab5275e582 --- /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 fccb5dc98e..f89956719e 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 @@ 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; } diff --git a/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl b/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl index decdc481f1..b089c499c6 100644 --- a/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl +++ b/neuralnetworks/aidl/android/hardware/neuralnetworks/IBurst.aidl @@ -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 diff --git a/neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl b/neuralnetworks/aidl/android/hardware/neuralnetworks/IExecution.aidl new file mode 100644 index 0000000000..3cb9c1a592 --- /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 956b626dd9..79053e527f 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.ErrorStatus; 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 @@ interface IPreparedModel { * 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 @@ interface IPreparedModel { * - 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); } |