blob: da9a966ba1af0f665eab952768748fa5d28c59da [file] [log] [blame]
Slava Shklyaev060a9ac2018-09-07 15:27:24 +01001/*
2 * Copyright (C) 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.neuralnetworks@1.2;
18
19import @1.0::ErrorStatus;
Slava Shklyaev060a9ac2018-09-07 15:27:24 +010020import @1.1::ExecutionPreference;
21import @1.1::IDevice;
Xusong Wangb5cb8f72018-10-31 08:43:12 -070022import IPreparedModelCallback;
Slava Shklyaev060a9ac2018-09-07 15:27:24 +010023
24/**
25 * This interface represents a device driver.
26 */
27interface IDevice extends @1.1::IDevice {
28 /**
Miao Wang44b029b2018-09-20 11:35:42 -070029 * Get the version string of the driver implementation.
30 *
31 * The version string must be a unique token among the set of version strings of
32 * drivers of a specific device. The token identifies the device driver's
33 * implementation. The token must not be confused with the feature level which is solely
34 * defined by the interface version. This API is opaque to the Android framework, but the
35 * Android framework may use the information for debugging or to pass on to NNAPI applications.
36 *
37 * Application developers sometimes have specific requirements to ensure good user experiences,
38 * and they need more information to make intelligent decisions when the Android framework cannot.
39 * For example, combined with the device name and other information, the token can help
40 * NNAPI applications filter devices based on their needs:
41 * - An application demands a certain level of performance, but a specific version of
42 * the driver cannot meet that requirement because of a performance regression.
43 * The application can blacklist the driver based on the version provided.
44 * - An application has a minimum precision requirement, but certain versions of
45 * the driver cannot meet that requirement because of bugs or certain optimizations.
46 * The application can filter out versions of these drivers.
47 *
48 * @return status Error status returned from querying the version string. Must be:
49 * - NONE if the query was successful
50 * - DEVICE_UNAVAILABLE if driver is offline or busy
51 * - GENERAL_FAILURE if the query resulted in an
52 * unspecified error
53 * @return version The version string of the device implementation.
54 * Must have nonzero length
55 */
56 getVersionString() generates (ErrorStatus status, string version);
57
58 /**
Miao Wange3b93532018-09-20 13:30:31 -070059 * Get the type of a given device.
60 *
61 * The device type can be used to help application developers to distribute
62 * Machine Learning workloads and other workloads such as graphical rendering.
63 * E.g., for an app which renders AR scenes based on real time object detection
64 * results, the developer could choose an ACCELERATOR type device for ML
65 * workloads, and reserve GPU for graphical rendering.
66 *
67 * @param status Error status returned from querying the device type. Must be:
68 * - NONE if the query was successful
69 * - DEVICE_UNAVAILABLE if driver is offline or busy
70 * - GENERAL_FAILURE if the query resulted in an
71 * unspecified error
72 * @param type The DeviceType of the device. Please note, this is not a
73 * bitfield of DeviceTypes. Each device must only be of a
74 * single DeviceType.
75 */
76 getType() generates (ErrorStatus status, DeviceType type);
77
78 /**
Slava Shklyaev6148d0f2018-11-20 15:29:01 +000079 * Gets information about extensions supported by the driver implementation.
80 *
81 * All extension operations and operands must be fully supported for the
82 * extension to appear in the list of supported extensions.
83 *
84 * @return status Error status of the call, must be:
85 * - NONE if successful
86 * - DEVICE_UNAVAILABLE if driver is offline or busy
87 * - GENERAL_FAILURE if there is an unspecified error
88 * @return extensions A list of supported extensions.
89 */
90 getSupportedExtensions()
91 generates (ErrorStatus status, vec<Extension> extensions);
92
93 /**
Slava Shklyaev060a9ac2018-09-07 15:27:24 +010094 * Gets the supported operations in a model.
95 *
96 * getSupportedOperations indicates which operations of a model are fully
97 * supported by the vendor driver. If an operation may not be supported for
98 * any reason, getSupportedOperations must return false for that operation.
99 *
100 * @param model A model whose operations--and their corresponding operands--
101 * are to be verified by the driver.
102 * @return status Error status of the call, must be:
103 * - NONE if successful
104 * - DEVICE_UNAVAILABLE if driver is offline or busy
105 * - GENERAL_FAILURE if there is an unspecified error
106 * - INVALID_ARGUMENT if provided model is invalid
107 * @return supportedOperations A list of supported operations, where true
108 * indicates the operation is supported and false indicates the
109 * operation is not supported. The index of "supported" corresponds with
110 * the index of the operation it is describing.
111 */
112 getSupportedOperations_1_2(Model model)
113 generates (ErrorStatus status, vec<bool> supportedOperations);
114
115 /**
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800116 * Gets the caching requirements of the driver implementation.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800117 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800118 * There are two types of cache file descriptors provided to the driver: model cache
119 * and data cache.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800120 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800121 * The data cache is for caching constant data, possibly including preprocessed
122 * and transformed tensor buffers. Any modification to the data cache should
123 * have no worse effect than generating bad output values at execution time.
124 *
125 * The model cache is for caching security-sensitive data such as compiled
126 * executable machine code in the device's native binary format. A modification
127 * to the model cache may affect the driver's execution behavior, and a malicious
128 * client could make use of this to execute beyond the granted permission. Thus,
129 * the driver must always check whether the model cache is corrupted before
130 * preparing the model from cache.
131 *
132 * getNumberOfCacheFilesNeeded returns how many of each type of cache files the driver
133 * implementation needs to cache a single prepared model. Returning 0 for both types
134 * indicates compilation caching is not supported by this driver. The driver may
135 * still choose not to cache certain compiled models even if it reports that caching
136 * is supported.
137 *
138 * If the device reports that caching is not supported, the user may avoid calling
139 * IDevice::prepareModelFromCache or providing cache file descriptors to
140 * IDevice::prepareModel_1_2.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800141 *
142 * @return status Error status of the call, must be:
143 * - NONE if successful
144 * - DEVICE_UNAVAILABLE if driver is offline or busy
145 * - GENERAL_FAILURE if there is an unspecified error
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800146 * @return numModelCache An unsigned integer indicating how many files for model cache
147 * the driver needs to cache a single prepared model. It must
148 * be less than or equal to Constant::MAX_NUMBER_OF_CACHE_FILES.
149 * @return numDataCache An unsigned integer indicating how many files for data cache
150 * the driver needs to cache a single prepared model. It must
151 * be less than or equal to Constant::MAX_NUMBER_OF_CACHE_FILES.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800152 */
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800153 getNumberOfCacheFilesNeeded()
154 generates (ErrorStatus status, uint32_t numModelCache, uint32_t numDataCache);
Xusong Wang89dfafb2019-01-11 17:41:11 -0800155
156 /**
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800157 * Asynchronously creates a prepared model for execution and optionally saves it
158 * into cache files.
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100159 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800160 * prepareModel is used to make any necessary transformations to or alternative
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100161 * representations to a model for execution, possibly including
162 * transformations on the constant data, optimization on the model's graph,
163 * or compilation into the device's native binary format. The model itself
164 * is not changed.
165 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800166 * Optionally, caching information may be provided for the driver to save
167 * the prepared model to cache files for faster model compilation time
168 * when the same model preparation is requested in the future. There are
169 * two types of cache file handles provided to the driver: model cache
170 * and data cache. For more information on the two types of cache handles,
171 * refer to getNumberOfCacheFilesNeeded.
172 *
173 * The file descriptors must be opened with read and write permission. A file may
174 * have any size, and the corresponding file descriptor may have any offset. The
175 * driver must truncate a file to zero size before writing to that file. The file
176 * descriptors may be closed by the client once the asynchronous preparation has
177 * finished. The driver must dup a file descriptor if it wants to get access to
178 * the cache file later.
179 *
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100180 * The model is prepared asynchronously with respect to the caller. The
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800181 * prepareModel function must verify the inputs to the preparedModel function
182 * related to preparing the model (as opposed to saving the prepared model to
183 * cache) are correct. If there is an error, prepareModel must immediately invoke
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100184 * the callback with the appropriate ErrorStatus value and nullptr for the
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800185 * IPreparedModel, then return with the same ErrorStatus. If the inputs to the
186 * prepareModel function that are related to preparing the model are valid and
187 * there is no error, prepareModel must launch an asynchronous task
188 * to prepare the model in the background, and immediately return from
189 * prepareModel with ErrorStatus::NONE. If the asynchronous task fails to launch,
190 * prepareModel must immediately invoke the callback with
191 * ErrorStatus::GENERAL_FAILURE and nullptr for the IPreparedModel, then return
192 * with ErrorStatus::GENERAL_FAILURE.
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100193 *
194 * When the asynchronous task has finished preparing the model, it must
195 * immediately invoke the callback function provided as an input to
196 * prepareModel. If the model was prepared successfully, the callback object
197 * must be invoked with an error status of ErrorStatus::NONE and the
198 * produced IPreparedModel object. If an error occurred preparing the model,
199 * the callback object must be invoked with the appropriate ErrorStatus
200 * value and nullptr for the IPreparedModel.
201 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800202 * Optionally, the driver may save the prepared model to cache during the
203 * asynchronous preparation. Any error that occurs when saving to cache must
204 * not affect the status of preparing the model. Even if the input arguments
205 * related to the cache may be invalid, or the driver may fail to save to cache,
206 * the prepareModel function must finish preparing the model. The driver
207 * may choose not to save to cache even if the caching information is
208 * provided and valid.
209 *
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100210 * The only information that may be unknown to the model at this stage is
211 * the shape of the tensors, which may only be known at execution time. As
212 * such, some driver services may return partially prepared models, where
213 * the prepared model may only be finished when it is paired with a set of
214 * inputs to the model. Note that the same prepared model object may be
215 * used with different shapes of inputs on different (possibly concurrent)
216 * executions.
217 *
218 * Multiple threads may call prepareModel on the same model concurrently.
219 *
220 * @param model The model to be prepared for execution.
221 * @param preference Indicates the intended execution behavior of a prepared
222 * model.
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800223 * @param modelCache A vector of handles with each entry holding exactly one
224 * cache file descriptor for the security-sensitive cache. The length of
225 * the vector must either be 0 indicating that caching information is not provided,
226 * or match the numModelCache returned from getNumberOfCacheFilesNeeded. The cache
227 * handles will be provided in the same order when retrieving the
228 * preparedModel from cache files with prepareModelFromCache.
229 * @param dataCache A vector of handles with each entry holding exactly one
230 * cache file descriptor for the constants' cache. The length of
231 * the vector must either be 0 indicating that caching information is not provided,
232 * or match the numDataCache returned from getNumberOfCacheFilesNeeded. The cache
233 * handles will be provided in the same order when retrieving the
234 * preparedModel from cache files with prepareModelFromCache.
235 * @param token A caching token of length Constant::BYTE_SIZE_OF_CACHE_TOKEN
236 * identifying the prepared model. The same token will be provided when retrieving
237 * the prepared model from the cache files with prepareModelFromCache.
238 * Tokens should be chosen to have a low rate of collision for a particular
239 * application. The driver cannot detect a collision; a collision will result
240 * in a failed execution or in a successful execution that produces incorrect
241 * output values. If both modelCache and dataCache are empty indicating that
242 * caching information is not provided, this token must be ignored.
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100243 * @param callback A callback object used to return the error status of
244 * preparing the model for execution and the prepared model if
245 * successful, nullptr otherwise. The callback object's notify function
246 * must be called exactly once, even if the model could not be prepared.
247 * @return status Error status of launching a task which prepares the model
248 * in the background; must be:
249 * - NONE if preparation task is successfully launched
250 * - DEVICE_UNAVAILABLE if driver is offline or busy
251 * - GENERAL_FAILURE if there is an unspecified error
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800252 * - INVALID_ARGUMENT if one of the input arguments related to preparing the
253 * model is invalid
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100254 */
255 prepareModel_1_2(Model model, ExecutionPreference preference,
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800256 vec<handle> modelCache, vec<handle> dataCache,
257 uint8_t[Constant:BYTE_SIZE_OF_CACHE_TOKEN] token,
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100258 IPreparedModelCallback callback)
259 generates (ErrorStatus status);
Xusong Wang89dfafb2019-01-11 17:41:11 -0800260
261 /**
262 * Creates a prepared model from cache files for execution.
263 *
264 * prepareModelFromCache is used to retrieve a prepared model directly from
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800265 * cache files to avoid slow model compilation time. There are
266 * two types of cache file handles provided to the driver: model cache
267 * and data cache. For more information on the two types of cache handles,
268 * refer to getNumberOfCacheFilesNeeded.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800269 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800270 * The file descriptors must be opened with read and write permission. A file may
271 * have any size, and the corresponding file descriptor may have any offset. The
272 * driver must truncate a file to zero size before writing to that file. The file
273 * descriptors may be closed by the client once the asynchronous preparation has
274 * finished. The driver must dup a file descriptor if it wants to get access to
275 * the cache file later.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800276 *
277 * The model is prepared asynchronously with respect to the caller. The
278 * prepareModelFromCache function must verify the inputs to the
279 * prepareModelFromCache function are correct, and that the security-sensitive
280 * cache has not been modified since it was last written by the driver.
281 * If there is an error, or if compilation caching is not supported, or if the
282 * security-sensitive cache has been modified, prepareModelFromCache must
283 * immediately invoke the callback with the appropriate ErrorStatus value and
284 * nullptr for the IPreparedModel, then return with the same ErrorStatus. If
285 * the inputs to the prepareModelFromCache function are valid, the security-sensitive
286 * cache is not modified, and there is no error, prepareModelFromCache must launch an
287 * asynchronous task to prepare the model in the background, and immediately return
288 * from prepareModelFromCache with ErrorStatus::NONE. If the asynchronous task
289 * fails to launch, prepareModelFromCache must immediately invoke the callback
290 * with ErrorStatus::GENERAL_FAILURE and nullptr for the IPreparedModel, then
291 * return with ErrorStatus::GENERAL_FAILURE.
292 *
293 * When the asynchronous task has finished preparing the model, it must
294 * immediately invoke the callback function provided as an input to
295 * prepareModelFromCache. If the model was prepared successfully, the
296 * callback object must be invoked with an error status of ErrorStatus::NONE
297 * and the produced IPreparedModel object. If an error occurred preparing
298 * the model, the callback object must be invoked with the appropriate
299 * ErrorStatus value and nullptr for the IPreparedModel.
300 *
301 * The only information that may be unknown to the model at this stage is
302 * the shape of the tensors, which may only be known at execution time. As
303 * such, some driver services may return partially prepared models, where
304 * the prepared model may only be finished when it is paired with a set of
305 * inputs to the model. Note that the same prepared model object may be
306 * used with different shapes of inputs on different (possibly concurrent)
307 * executions.
308 *
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800309 * @param modelCache A vector of handles with each entry holding exactly one
310 * cache file descriptor for the security-sensitive cache. The length of
311 * the vector must match the numModelCache returned from getNumberOfCacheFilesNeeded.
312 * The cache handles will be provided in the same order as with prepareModel_1_2.
313 * @param dataCache A vector of handles with each entry holding exactly one
314 * cache file descriptor for the constants' cache. The length of the vector
315 * must match the numDataCache returned from getNumberOfCacheFilesNeeded.
316 * The cache handles will be provided in the same order as with prepareModel_1_2.
Xusong Wang89dfafb2019-01-11 17:41:11 -0800317 * @param token A caching token of length Constant::BYTE_SIZE_OF_CACHE_TOKEN
318 * identifying the prepared model. It is the same token provided when saving
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800319 * the cache files with prepareModel_1_2. Tokens should be chosen
Xusong Wang89dfafb2019-01-11 17:41:11 -0800320 * to have a low rate of collision for a particular application. The driver
321 * cannot detect a collision; a collision will result in a failed execution
322 * or in a successful execution that produces incorrect output values.
323 * @param callback A callback object used to return the error status of
324 * preparing the model for execution and the prepared model if
325 * successful, nullptr otherwise. The callback object's notify function
326 * must be called exactly once, even if the model could not be prepared.
327 * @return status Error status of launching a task which prepares the model
328 * in the background; must be:
329 * - NONE if preparation task is successfully launched
330 * - DEVICE_UNAVAILABLE if driver is offline or busy
331 * - GENERAL_FAILURE if caching is not supported or if there is an
332 * unspecified error
333 * - INVALID_ARGUMENT if one of the input arguments is invalid
334 */
Xusong Wangb61ba1e2019-02-25 16:58:58 -0800335 prepareModelFromCache(vec<handle> modelCache, vec<handle> dataCache,
Xusong Wang89dfafb2019-01-11 17:41:11 -0800336 uint8_t[Constant:BYTE_SIZE_OF_CACHE_TOKEN] token,
337 IPreparedModelCallback callback)
338 generates (ErrorStatus status);
Slava Shklyaev060a9ac2018-09-07 15:27:24 +0100339};