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 17 package android.hardware.contexthub@1.0; 18 19 import 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 */ 28 interface 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
