1/*
2 * Copyright (C) 2016 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.contexthub@1.0;
18
19import IContexthubCallback;
20
21/**
22 * The Context Hub HAL provides an interface to a separate low-power processing
23 * domain that has direct access to contextual information, such as sensors.
24 * Native applications that run within a context hub are known as nanoapps, and
25 * they execute within the Context Hub Runtime Environment (CHRE), which is
26 * standardized via the CHRE API, defined elsewhere.
27 */
28interface IContexthub {
29    /**
30     * Enumerate all available context hubs on the system.
31     *
32     * @return hubs list of hubs on this system.
33     */
34    getHubs() generates (vec<ContextHub> hubs);
35
36    /**
37     * Register a callback for the HAL implementation to send asynchronous
38     * messages to the service from a context hub. There can be a maximum of
39     * one callback registered with the HAL. A call to this function when a
40     * callback has already been registered must override the previous
41     * registration.
42     *
43     * @param hubId    identifier for the hub
44     *        callback an implementation of the IContextHubCallbacks
45     *
46     * @return result OK on success
47     *                BAD_VALUE if parameters are not sane
48     *
49     */
50     registerCallback(uint32_t hubId, IContexthubCallback cb) generates (Result result);
51
52    /**
53     * Send a message to a hub
54     *
55     * @param hubId identifier for hub to send message to
56     *        msg   message to be sent
57     *
58     * @return result OK if successful, error code otherwise
59     *                BAD_VALUE if parameters are not sane
60     *                TRANSACTION_FAILED if message send failed
61     */
62    sendMessageToHub(uint32_t hubId, ContextHubMsg msg)
63            generates (Result result);
64
65    /**
66     * Loads a nanoApp. After loading, the nanoApp's init method must be called.
67     * After the init method for nanoApp returns success, this must be indicated
68     * to the service by an asynchronous call to handleTxnResult.
69     *
70     * Loading a nanoapp must not take more than 30 seconds.
71     *
72     * Depending on the implementation, nanoApps loaded via this API may or may
73     * not persist across reboots of the hub. If they do persist, the
74     * implementation must initially place nanoApps in the disabled state upon a
75     * reboot, and not start them until a call is made to enableNanoApp(). In
76     * this case, the app must also be unloaded upon a factory reset of the
77     * device.
78     *
79     * @param hubId identifer of the contextHub
80     *        appBinary contains the binary representation of the nanoApp, plus
81     *                  metadata
82     *        transactionId transactionId for this call
83     *
84     * @return result OK if transation started
85     *                BAD_VALUE if parameters are not sane
86     *                TRANSACTION_PENDING if hub is busy with another
87     *                                    load/unload transaction
88     *                TRANSACTION_FAILED if load failed synchronously
89     *
90     */
91    loadNanoApp(uint32_t hubId,
92                NanoAppBinary appBinary,
93                uint32_t transactionId)
94            generates (Result result);
95
96    /**
97     * Unloads a nanoApp. Before the unload, the apps deinit method is called.
98     * After this, success must be indicated to the service through an
99     * asynchronous call to handleTxnResult.
100     *
101     * Unloading a nanoapp must not take more than 5 seconds.
102     *
103     * @param hubId identifer of the contextHub
104     *        appId appIdentifier returned by the HAL
105     *        msg   message to be sent
106     *
107     * @return result OK if transation started
108     *                BAD_VALUE if parameters are not sane
109     *                TRANSACTION_PENDING if hub is busy with another
110     *                                    load/unload transaction
111     *                TRANSACTION_FAILED if unload failed synchronously
112     *
113     */
114    unloadNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
115            generates (Result result);
116
117    /**
118     * Enables a nanoApp. The app's init method is called.
119     * After this, success must be indicated to the service through an
120     * asynchronous message.
121     *
122     * Enabling a nanoapp must not take more than 5 seconds.
123     *
124     * @param hubId identifer of the contextHub
125     *        appId appIdentifier returned by the HAL
126     *        msg   message to be sent
127     *
128     * @return result OK if transation started
129     *                BAD_VALUE if parameters are not sane
130     *                TRANSACTION_PENDING if hub is busy with another
131     *                                    load/unload transaction
132     *                FAILED_TRANSACTION if load fails immediately
133     *
134     */
135    enableNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
136            generates (Result result);
137
138    /**
139     * Disables a nanoApp. The app's deinit method is called.
140     * After this, success must be indicated to the service through an
141     * asynchronous message.
142     *
143     * Disabling a nanoapp must not take more than 5 seconds.
144     *
145     * @param hubId identifer of the contextHub
146     *        appId appIdentifier returned by the HAL
147     *        msg   message to be sent
148     *
149     * @return result OK if transation started
150     *                BAD_VALUE if parameters are not sane
151     *                TRANSACTION_PENDING if hub is busy with another
152     *                                    load/unload transaction
153     *                FAILED_TRANSACTION if load fails immediately
154     *
155     */
156    disableNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
157            generates (Result result);
158
159    /**
160     * Queries for Loaded apps on the hub
161     *
162     * @param hubId identifer of the contextHub
163     *
164     * @return apps all nanoApps on the hub.
165     *              All nanoApps that can be modified by the service must
166     *              be returned. A non-modifiable nanoapps must not be
167     *              returned. A modifiable nanoApp is one that can be
168     *              unloaded/disabled/enabled by the service.
169     *
170     */
171    queryApps(uint32_t hubId) generates (Result result);
172};
173