1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
/*
* Copyright (C) 2020 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.common.NativeHandle;
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;
/**
* IPreparedModel describes a model that has been prepared for execution and is used to launch
* executions.
*/
@VintfStability
interface IPreparedModel {
/**
* Each {@link OperationType::WHILE} operation in the model has an implicit execution timeout
* duration associated with it ("loop timeout duration"). This duration is configurable on a
* per-execution basis and must not exceed 15 seconds. The default value is 2 seconds. The units
* are nanoseconds.
*/
const long DEFAULT_LOOP_TIMEOUT_DURATION_NS = 2000000000;
const long MAXIMUM_LOOP_TIMEOUT_DURATION_NS = 15000000000;
/**
* Performs a synchronous execution on a prepared model.
*
* 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 'request' (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 prepared model was prepared from a 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.
*
* 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.
*
* Any number of calls to the execute* functions, in any combination, may be made concurrently,
* even on the same IPreparedModel object.
*
* @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. The duration
* 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 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
* execution 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 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 Request request, in boolean measureTiming,
in long deadlineNs, in long loopTimeoutDurationNs);
/**
* Launch a fenced asynchronous execution on a prepared model.
*
* 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 'request' (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.
*
* Any number of calls to the execute* functions, in any combination, may be made concurrently,
* even on the same IPreparedModel object.
*
* @param request The input and output information on which the prepared model is to be
* executed. The outputs in the request must have fully specified dimensions.
* @param waitFor A vector of sync fence file descriptors. Execution must not start until all
* sync fences have been signaled.
* @param measure Specifies whether or not to measure duration of the execution.
* @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 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
* execution 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}.
* @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 Request request, in ParcelFileDescriptor[] waitFor,
in boolean measureTiming, in long deadlineNs, in long loopTimeoutDurationNs,
in long durationNs);
/**
* Configure a Burst object used to execute multiple inferences on a prepared model in rapid
* succession.
*
* If the prepared model was prepared from a model wherein all tensor operands have fully
* specified dimensions, and a valid serialized Request is sent to the Burst for execution, and
* at execution time every operation's input operands have legal values, then the execution
* should complete successfully (ErrorStatus::NONE): There must be no failure unless the device
* itself is in a bad state.
*
* @return burst Execution burst controller object.
* @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
* - 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);
}
|
