Merge "run vts build rule updater when hal make files are updated"
[android/platform-hardware-interfaces.git] / neuralnetworks / 1.2 / IDevice.hal
1 /*
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  */
17 package android.hardware.neuralnetworks@1.2;
19 import @1.0::ErrorStatus;
20 import @1.0::IPreparedModelCallback;
21 import @1.1::ExecutionPreference;
22 import @1.1::IDevice;
24 /**
25  * This interface represents a device driver.
26  */
27 interface IDevice extends @1.1::IDevice {
28     /**
29      * 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);
58     /**
59      * Gets the supported operations in a model.
60      *
61      * getSupportedOperations indicates which operations of a model are fully
62      * supported by the vendor driver. If an operation may not be supported for
63      * any reason, getSupportedOperations must return false for that operation.
64      *
65      * @param model A model whose operations--and their corresponding operands--
66      *     are to be verified by the driver.
67      * @return status Error status of the call, must be:
68      *     - NONE if successful
69      *     - DEVICE_UNAVAILABLE if driver is offline or busy
70      *     - GENERAL_FAILURE if there is an unspecified error
71      *     - INVALID_ARGUMENT if provided model is invalid
72      * @return supportedOperations A list of supported operations, where true
73      *     indicates the operation is supported and false indicates the
74      *     operation is not supported. The index of "supported" corresponds with
75      *     the index of the operation it is describing.
76      */
77     getSupportedOperations_1_2(Model model)
78             generates (ErrorStatus status, vec<bool> supportedOperations);
80     /**
81      * Creates a prepared model for execution.
82      *
83      * prepareModel is used to make any necessary transformations or alternative
84      * representations to a model for execution, possibly including
85      * transformations on the constant data, optimization on the model's graph,
86      * or compilation into the device's native binary format. The model itself
87      * is not changed.
88      *
89      * The model is prepared asynchronously with respect to the caller. The
90      * prepareModel function must verify the inputs to the prepareModel function
91      * are correct. If there is an error, prepareModel must immediately invoke
92      * the callback with the appropriate ErrorStatus value and nullptr for the
93      * IPreparedModel, then return with the same ErrorStatus. If the inputs to
94      * the prepareModel function are valid and there is no error, prepareModel
95      * must launch an asynchronous task to prepare the model in the background,
96      * and immediately return from prepareModel with ErrorStatus::NONE. If the
97      * asynchronous task fails to launch, prepareModel must immediately invoke
98      * the callback with ErrorStatus::GENERAL_FAILURE and nullptr for the
99      * IPreparedModel, then return with ErrorStatus::GENERAL_FAILURE.
100      *
101      * When the asynchronous task has finished preparing the model, it must
102      * immediately invoke the callback function provided as an input to
103      * prepareModel. If the model was prepared successfully, the callback object
104      * must be invoked with an error status of ErrorStatus::NONE and the
105      * produced IPreparedModel object. If an error occurred preparing the model,
106      * the callback object must be invoked with the appropriate ErrorStatus
107      * value and nullptr for the IPreparedModel.
108      *
109      * The only information that may be unknown to the model at this stage is
110      * the shape of the tensors, which may only be known at execution time. As
111      * such, some driver services may return partially prepared models, where
112      * the prepared model may only be finished when it is paired with a set of
113      * inputs to the model. Note that the same prepared model object may be
114      * used with different shapes of inputs on different (possibly concurrent)
115      * executions.
116      *
117      * Multiple threads may call prepareModel on the same model concurrently.
118      *
119      * @param model The model to be prepared for execution.
120      * @param preference Indicates the intended execution behavior of a prepared
121      *     model.
122      * @param callback A callback object used to return the error status of
123      *     preparing the model for execution and the prepared model if
124      *     successful, nullptr otherwise. The callback object's notify function
125      *     must be called exactly once, even if the model could not be prepared.
126      * @return status Error status of launching a task which prepares the model
127      *     in the background; must be:
128      *     - NONE if preparation task is successfully launched
129      *     - DEVICE_UNAVAILABLE if driver is offline or busy
130      *     - GENERAL_FAILURE if there is an unspecified error
131      *     - INVALID_ARGUMENT if one of the input arguments is invalid
132      */
133     prepareModel_1_2(Model model, ExecutionPreference preference,
134                      IPreparedModelCallback callback)
135           generates (ErrorStatus status);
136 };