blob: 6c3b4839e1ea30f44014819575e24f832267c82f [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 Shklyaev060a9ac2018-09-07 15:27:24 +010079 * Gets the supported operations in a model.
80 *
81 * getSupportedOperations indicates which operations of a model are fully
82 * supported by the vendor driver. If an operation may not be supported for
83 * any reason, getSupportedOperations must return false for that operation.
84 *
85 * @param model A model whose operations--and their corresponding operands--
86 * are to be verified by the driver.
87 * @return status Error status of the call, must be:
88 * - NONE if successful
89 * - DEVICE_UNAVAILABLE if driver is offline or busy
90 * - GENERAL_FAILURE if there is an unspecified error
91 * - INVALID_ARGUMENT if provided model is invalid
92 * @return supportedOperations A list of supported operations, where true
93 * indicates the operation is supported and false indicates the
94 * operation is not supported. The index of "supported" corresponds with
95 * the index of the operation it is describing.
96 */
97 getSupportedOperations_1_2(Model model)
98 generates (ErrorStatus status, vec<bool> supportedOperations);
99
100 /**
101 * Creates a prepared model for execution.
102 *
103 * prepareModel is used to make any necessary transformations or alternative
104 * representations to a model for execution, possibly including
105 * transformations on the constant data, optimization on the model's graph,
106 * or compilation into the device's native binary format. The model itself
107 * is not changed.
108 *
109 * The model is prepared asynchronously with respect to the caller. The
110 * prepareModel function must verify the inputs to the prepareModel function
111 * are correct. If there is an error, prepareModel must immediately invoke
112 * the callback with the appropriate ErrorStatus value and nullptr for the
113 * IPreparedModel, then return with the same ErrorStatus. If the inputs to
114 * the prepareModel function are valid and there is no error, prepareModel
115 * must launch an asynchronous task to prepare the model in the background,
116 * and immediately return from prepareModel with ErrorStatus::NONE. If the
117 * asynchronous task fails to launch, prepareModel must immediately invoke
118 * the callback with ErrorStatus::GENERAL_FAILURE and nullptr for the
119 * IPreparedModel, then return with ErrorStatus::GENERAL_FAILURE.
120 *
121 * When the asynchronous task has finished preparing the model, it must
122 * immediately invoke the callback function provided as an input to
123 * prepareModel. If the model was prepared successfully, the callback object
124 * must be invoked with an error status of ErrorStatus::NONE and the
125 * produced IPreparedModel object. If an error occurred preparing the model,
126 * the callback object must be invoked with the appropriate ErrorStatus
127 * value and nullptr for the IPreparedModel.
128 *
129 * The only information that may be unknown to the model at this stage is
130 * the shape of the tensors, which may only be known at execution time. As
131 * such, some driver services may return partially prepared models, where
132 * the prepared model may only be finished when it is paired with a set of
133 * inputs to the model. Note that the same prepared model object may be
134 * used with different shapes of inputs on different (possibly concurrent)
135 * executions.
136 *
137 * Multiple threads may call prepareModel on the same model concurrently.
138 *
139 * @param model The model to be prepared for execution.
140 * @param preference Indicates the intended execution behavior of a prepared
141 * model.
142 * @param callback A callback object used to return the error status of
143 * preparing the model for execution and the prepared model if
144 * successful, nullptr otherwise. The callback object's notify function
145 * must be called exactly once, even if the model could not be prepared.
146 * @return status Error status of launching a task which prepares the model
147 * in the background; must be:
148 * - NONE if preparation task is successfully launched
149 * - DEVICE_UNAVAILABLE if driver is offline or busy
150 * - GENERAL_FAILURE if there is an unspecified error
151 * - INVALID_ARGUMENT if one of the input arguments is invalid
152 */
153 prepareModel_1_2(Model model, ExecutionPreference preference,
154 IPreparedModelCallback callback)
155 generates (ErrorStatus status);
156};