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