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      * Gets the supported operations in a model.
30      *
31      * getSupportedOperations indicates which operations of a model are fully
32      * supported by the vendor driver. If an operation may not be supported for
33      * any reason, getSupportedOperations must return false for that operation.
34      *
35      * @param model A model whose operations--and their corresponding operands--
36      *     are to be verified by the driver.
37      * @return status Error status of the call, must be:
38      *     - NONE if successful
39      *     - DEVICE_UNAVAILABLE if driver is offline or busy
40      *     - GENERAL_FAILURE if there is an unspecified error
41      *     - INVALID_ARGUMENT if provided model is invalid
42      * @return supportedOperations A list of supported operations, where true
43      *     indicates the operation is supported and false indicates the
44      *     operation is not supported. The index of "supported" corresponds with
45      *     the index of the operation it is describing.
46      */
47     getSupportedOperations_1_2(Model model)
48             generates (ErrorStatus status, vec<bool> supportedOperations);
50     /**
51      * Creates a prepared model for execution.
52      *
53      * prepareModel is used to make any necessary transformations or alternative
54      * representations to a model for execution, possibly including
55      * transformations on the constant data, optimization on the model's graph,
56      * or compilation into the device's native binary format. The model itself
57      * is not changed.
58      *
59      * The model is prepared asynchronously with respect to the caller. The
60      * prepareModel function must verify the inputs to the prepareModel function
61      * are correct. If there is an error, prepareModel must immediately invoke
62      * the callback with the appropriate ErrorStatus value and nullptr for the
63      * IPreparedModel, then return with the same ErrorStatus. If the inputs to
64      * the prepareModel function are valid and there is no error, prepareModel
65      * must launch an asynchronous task to prepare the model in the background,
66      * and immediately return from prepareModel with ErrorStatus::NONE. If the
67      * asynchronous task fails to launch, prepareModel must immediately invoke
68      * the callback with ErrorStatus::GENERAL_FAILURE and nullptr for the
69      * IPreparedModel, then return with ErrorStatus::GENERAL_FAILURE.
70      *
71      * When the asynchronous task has finished preparing the model, it must
72      * immediately invoke the callback function provided as an input to
73      * prepareModel. If the model was prepared successfully, the callback object
74      * must be invoked with an error status of ErrorStatus::NONE and the
75      * produced IPreparedModel object. If an error occurred preparing the model,
76      * the callback object must be invoked with the appropriate ErrorStatus
77      * value and nullptr for the IPreparedModel.
78      *
79      * The only information that may be unknown to the model at this stage is
80      * the shape of the tensors, which may only be known at execution time. As
81      * such, some driver services may return partially prepared models, where
82      * the prepared model may only be finished when it is paired with a set of
83      * inputs to the model. Note that the same prepared model object may be
84      * used with different shapes of inputs on different (possibly concurrent)
85      * executions.
86      *
87      * Multiple threads may call prepareModel on the same model concurrently.
88      *
89      * @param model The model to be prepared for execution.
90      * @param preference Indicates the intended execution behavior of a prepared
91      *     model.
92      * @param callback A callback object used to return the error status of
93      *     preparing the model for execution and the prepared model if
94      *     successful, nullptr otherwise. The callback object's notify function
95      *     must be called exactly once, even if the model could not be prepared.
96      * @return status Error status of launching a task which prepares the model
97      *     in the background; must be:
98      *     - NONE if preparation task is successfully launched
99      *     - DEVICE_UNAVAILABLE if driver is offline or busy
100      *     - GENERAL_FAILURE if there is an unspecified error
101      *     - INVALID_ARGUMENT if one of the input arguments is invalid
102      */
103     prepareModel_1_2(Model model, ExecutionPreference preference,
104                      IPreparedModelCallback callback)
105           generates (ErrorStatus status);
106 };