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 #ifndef _CHRE_H_ 18 #define _CHRE_H_ 19 20 /** 21 * @file 22 * This header file includes all the headers which combine to fully define the 23 * interface for the Context Hub Runtime Environment (CHRE). This interface is 24 * of interest to both implementers of CHREs and authors of nanoapps. The API 25 * documentation attempts to address concerns of both. 26 * 27 * See individual header files for API details, and general comments below 28 * for overall platform information. 29 */ 30 31 #include <chre/audio.h> 32 #include <chre/ble.h> 33 #include <chre/common.h> 34 #include <chre/event.h> 35 #include <chre/gnss.h> 36 #include <chre/nanoapp.h> 37 #include <chre/re.h> 38 #include <chre/sensor.h> 39 #include <chre/toolchain.h> 40 #include <chre/user_settings.h> 41 #include <chre/version.h> 42 #include <chre/wifi.h> 43 #include <chre/wwan.h> 44 45 /** 46 * @mainpage 47 * CHRE is the Context Hub Runtime Environment. CHRE is used in Android to run 48 * contextual applications, called nanoapps, in a low-power processing domain 49 * other than the applications processor that runs Android itself. The CHRE 50 * API, documented herein, is the common interface exposed to nanoapps for any 51 * compatible CHRE implementation. The CHRE API provides the ability for 52 * creating nanoapps that are code-compatible across different CHRE 53 * implementations and underlying platforms. Refer to the following sections for 54 * a discussion on some important details of CHRE that aren't explicitly exposed 55 * in the API itself. 56 * 57 * @section entry_points Entry points 58 * 59 * The following entry points are used to bind a nanoapp to the CHRE system, and 60 * all three must be implemented by any nanoapp (see chre/nanoapp.h): 61 * - nanoappStart: initialization 62 * - nanoappHandleEvent: hook for event-driven processing 63 * - nanoappEnd: graceful teardown 64 * 65 * The CHRE implementation must also ensure that it performs these functions 66 * prior to invoking nanoappStart, or after nanoappEnd returns: 67 * - bss section zeroed out (prior to nanoappStart) 68 * - static variables initialized (prior to nanoappStart) 69 * - global C++ constructors called (prior to nanoappStart) 70 * - global C++ destructors called (after nanoappEnd) 71 * 72 * @section threading Threading model 73 * 74 * A CHRE implementation is free to choose among many different 75 * threading models, including a single-threaded system or a multi-threaded 76 * system with preemption. The current platform definition is agnostic to this 77 * underlying choice. However, the CHRE implementation must ensure that time 78 * spent executing within a nanoapp does not significantly degrade or otherwise 79 * interfere with other functions of the system in which CHRE is implemented, 80 * especially latency-sensitive tasks such as sensor event delivery to the AP. 81 * In other words, it must ensure that these functions can either occur in 82 * parallel or preempt a nanoapp's execution. The current version of the API 83 * does not specify whether the implementation allows for CPU sharing between 84 * nanoapps on a more granular level than the handling of individual events [1]. 85 * In any case, event ordering from the perspective of an individual nanoapp 86 * must be FIFO, but the CHRE implementation may choose to violate total 87 * ordering of events across all nanoapps to achieve more fair resource sharing, 88 * but this is not required. 89 * 90 * This version of the CHRE API does require that all nanoapps are treated as 91 * non-reentrant, meaning that only one instance of program flow can be inside 92 * an individual nanoapp at any given time. That is, any of the functions of 93 * the nanoapp, including the entry points and all other callbacks, cannot be 94 * invoked if a previous invocation to the same or any other function in the 95 * nanoapp has not completed yet. 96 * 97 * For example, if a nanoapp is currently in nanoappHandleEvent(), the CHRE is 98 * not allowed to call nanoappHandleEvent() again, or to call a memory freeing 99 * callback. Similarly, if a nanoapp is currently in a memory freeing 100 * callback, the CHRE is not allowed to call nanoappHandleEvent(), or invoke 101 * another memory freeing callback. 102 * 103 * There are two exceptions to this rule: If an invocation of chreSendEvent() 104 * fails (returns 'false'), it is allowed to immediately invoke the memory 105 * freeing callback passed into that function. This is a rare case, and one 106 * where otherwise a CHRE implementation is likely to leak memory. Similarly, 107 * chreSendMessageToHost() is allowed to invoke the memory freeing callback 108 * directly, whether it returns 'true' or 'false'. This is because the CHRE 109 * implementation may copy the message data to its own buffer, and therefore 110 * wouldn't need the nanoapp-supplied buffer after chreSendMessageToHost() 111 * returns. 112 * 113 * For a nanoapp author, this means no thought needs to be given to 114 * synchronization issues with global objects, as they will, by definition, 115 * only be accessed by a single thread at once. 116 * 117 * [1]: Note to CHRE implementers: A future version of the CHRE platform may 118 * require multi-threading with preemption. This is mentioned as a heads up, 119 * and to allow implementors deciding between implementation approaches to 120 * make the most informed choice. 121 * 122 * @section timing Timing 123 * 124 * Nanoapps should expect to be running on a highly constrained system, with 125 * little memory and little CPU. Any single nanoapp should expect to 126 * be one of several nanoapps on the system, which also share the CPU with the 127 * CHRE and possibly other services as well. 128 * 129 * Thus, a nanoapp needs to be efficient in its memory and CPU usage. 130 * Also, as noted in the Threading Model section, a CHRE implementation may 131 * be single threaded. As a result, all methods invoked in a nanoapp 132 * (like nanoappStart, nanoappHandleEvent, memory free callbacks, etc.) 133 * must run "quickly". "Quickly" is difficult to define, as there is a 134 * diversity of Context Hub hardware. Nanoapp authors are strongly recommended 135 * to limit their application to consuming no more than 1 second of CPU time 136 * prior to returning control to the CHRE implementation. A CHRE implementation 137 * may consider a nanoapp as unresponsive if it spends more time than this to 138 * process a single event, and take corrective action. 139 * 140 * A nanoapp may have the need to occasionally perform a large block of 141 * calculations that exceeds the 1 second guidance. The recommended approach in 142 * this case is to split up the large block of calculations into smaller 143 * batches. In one call into the nanoapp, the nanoapp can perform the first 144 * batch, and then set a timer or send an event (chreSendEvent()) to itself 145 * indicating which batch should be done next. This will allow the nanoapp to 146 * perform the entire calculation over time, without monopolizing system 147 * resources. 148 * 149 * @section floats Floating point support 150 * 151 * The C type 'float' is used in this API, and thus a CHRE implementation 152 * is required to support 'float's. 153 * 154 * Support of the C types 'double' and 'long double' is optional for a 155 * CHRE implementation. Note that if a CHRE decides to support them, unlike 156 * 'float' support, there is no requirement that this support is particularly 157 * efficient. So nanoapp authors should be aware this may be inefficient. 158 * 159 * If a CHRE implementation chooses not to support 'double' or 160 * 'long double', then the build toolchain setup provided needs to set 161 * the preprocessor define CHRE_NO_DOUBLE_SUPPORT. 162 * 163 * @section compat CHRE and Nanoapp compatibility 164 * 165 * CHRE implementations must make affordances to maintain binary compatibility 166 * across minor revisions of the API version (e.g. v1.1 to v1.2). This applies 167 * to both running a nanoapp compiled for a newer version of the API on a CHRE 168 * implementation built against an older version (backwards compatibility), and 169 * vice versa (forwards compatibility). API changes that are acceptable in 170 * minor version changes that may require special measures to ensure binary 171 * compatibility include: addition of new functions; addition of arguments to 172 * existing functions when the default value used for nanoapps compiled against 173 * the old version is well-defined and does not affect existing functionality; 174 * and addition of fields to existing structures, even when this induces a 175 * binary layout change (this should be made rare via judicious use of reserved 176 * fields). API changes that must only occur alongside a major version change 177 * and are therefore not compatible include: removal of any function, argument, 178 * field in a data structure, or mandatory functional behavior that a nanoapp 179 * may depend on; any change in the interpretation of an existing data structure 180 * field that alters the way it was defined previously (changing the units of a 181 * field would fall under this, but appropriating a previously reserved field 182 * for some new functionality would not); and any change in functionality or 183 * expected behavior that conflicts with the previous definition. 184 * 185 * Note that the CHRE API only specifies the software interface between a 186 * nanoapp and the CHRE system - the binary interface (ABI) between nanoapp and 187 * CHRE is necessarily implementation-dependent. Therefore, the recommended 188 * approach to accomplish binary compatibility is to build a Nanoapp Support 189 * Library (NSL) that is specific to the CHRE implementation into the nanoapp 190 * binary, and use it to handle ABI details in a way that ensures compatibility. 191 * In addition, to accomplish forwards compatibility, the CHRE implementation is 192 * expected to recognize the CHRE API version that a nanoapp is targeting and 193 * engage compatibility behaviors where necessary. 194 * 195 * By definition, major API version changes (e.g. v1.1 to v2.0) break 196 * compatibility. Therefore, a CHRE implementation must not attempt to load a 197 * nanoapp that is targeting a newer major API version. 198 */ 199 200 #endif /* _CHRE_H_ */ 201 202