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 * This header file includes all the headers which combine to fully defined 22 * the interface for the Context Hub Runtime Environment (CHRE). This is the 23 * environment in which a nanoapp runs. 24 * 25 * This interface is of interest to both implementors of CHREs and 26 * authors of nanoapps. The API documentation attempts to address concerns 27 * of both. 28 * 29 * See individual header files for API specific, and general comments below 30 * for overall platform information. 31 */ 32 33 #include <chre/event.h> 34 #include <chre/nanoapp.h> 35 #include <chre/re.h> 36 #include <chre/sensor.h> 37 #include <chre/version.h> 38 39 40 /** 41 * Entry points. 42 * 43 * The following entry points are required to be handled by the CHRE 44 * implementation, and the functions must all be implemented by nanoapps. 45 * o nanoappStart function (see chre_nanoapp.h) 46 * o nanoappHandleEvent function (see chre_nanoapp.h) 47 * o nanoappEnd function (see chre_nanoapp.h) 48 * o bss section zeroed out (prior to nanoappStart) 49 * o static variables initialized (prior to nanoappStart) 50 * o global C++ constructors called (prior to nanoappStart) 51 * o global C++ destructors called (after nanoappEnd) 52 */ 53 54 55 /** 56 * Threading model. 57 * 58 * A CHRE implementation is free to chose among many different 59 * threading models, including a single threaded system or a multi-threaded 60 * system with preemption. The current platform definition is agnostic to this 61 * underlying choice [1]. 62 * 63 * However, the Platform does require that all nanoapps are treated as 64 * non-reentrant. That is, any of the functions of the nanoapp, including 65 * the entry points defined above and the memory freeing callbacks defined 66 * below, cannot be invoked by the CHRE if a previous invocation 67 * hasn't completed. Note this means no nanoapp function can be invoked 68 * from an interrupt context. 69 * 70 * For example, if a nanoapp is currently in nanoappHandleEvent(), the CHRE is 71 * not allowed to call nanoappHandleEvent() again, or to call a memory freeing 72 * callback. Similarly, if a nanoapp is currently in a memory freeing 73 * callback, the CHRE is not allowed to call nanoappHandleEvent(), or invoke 74 * another memory freeing callback. 75 * 76 * There are two exceptions to this rule: If an invocation of chreSendEvent() 77 * fails (returns 'false'), it is allowed to immediately invoke the memory 78 * freeing callback passed into that function. This is a rare case, and one 79 * where otherwise a CHRE implementation is likely to leak memory. Similarly, 80 * chreSendMessageToHost() is allowed to invoke the memory freeing callback 81 * directly, whether it returns 'true' or 'false'. This is because the CHRE 82 * implementation may copy the message data to its own buffer, and therefore 83 * wouldn't need the nanoapp-supplied buffer after chreSendMessageToHost() 84 * returns. 85 * 86 * For a nanoapp author, this means no thought needs to be given to 87 * synchronization issues with global objects, as they will, by definition, 88 * only be accessed by a single thread at once. 89 * 90 * 91 * [1] Note to CHRE implementors: A future version of the CHRE platform may 92 * require multi-threading with preemption. This is mentioned as a heads up, 93 * and to allow implementors deciding between implementation approaches to 94 * make the most informed choice. 95 */ 96 97 /** 98 * Notes on timing. 99 * 100 * Nanoapps should expect to be running on a highly constrained system, with 101 * little memory and little CPU. Any single nanoapp should expect to 102 * be one of several nanoapps on the system, which also share the CPU with the 103 * CHRE and possibly other services as well. 104 * 105 * Thus, a nanoapp needs to be efficient in its memory and CPU usage. 106 * Also, as noted in the Threading Model section, a CHRE implementation may 107 * be single threaded. As a result, all methods invoked in a nanoapp 108 * (like nanoappStart, nanoappHandleEvent, memory free callbacks, etc.) 109 * must run "quickly". "Quickly" is difficult to define, as there is a 110 * diversity of Context Hub hardware. For Android N, there is no firm 111 * definition of "quickly", but expect this term to gain definition in 112 * future releases as we get feedback from partners. 113 * 114 * In order to write a nanoapp that will be able to adopt to future 115 * stricter notions of "quickly", all nanoapp methods should be written so 116 * they execute in a small amount of time. Some nanoapps may have the need 117 * to occasionally perform a large block of calculations, which may seem 118 * to violate this. The recommended approach in this case is to 119 * split up the large block of calculations into smaller batches. In one 120 * call into the nanoapp, the nanoapp can perform the first batch, and then 121 * send an event (chreSendEvent()) to itself indicating which batch should be 122 * done next. This will allow the nanoapp to perform the entire calculation 123 * over time, without monopolizing system resources. 124 */ 125 126 /** 127 * Floating point support. 128 * 129 * The C type 'float' is used in this API, and thus a CHRE implementation 130 * is required to support 'float's. 131 * 132 * Support of the C types 'double' and 'long double' is optional for a 133 * CHRE implementation. Note that if a CHRE decides to support them, unlike 134 * 'float' support, there is no requirement that this support is particularly 135 * efficient. So nanoapp authors should be aware this may be inefficient. 136 * 137 * If a CHRE implementation choses not to support 'double' or 138 * 'long double', then the build toolchain setup provided needs to set 139 * the preprocessor define CHRE_NO_DOUBLE_SUPPORT. 140 */ 141 142 /** 143 * CHRE and Nanoapp compatibility. 144 * 145 * The Android N release introduces the first version of this API. 146 * It is anticipated that there will be a lot of feedback from 147 * Android partners on this initial API. To allow more flexibility 148 * in addressing that feedback, there is no plan to assure 149 * binary compatibility between the Android N and Android O CHRE 150 * implementations and nanoapps. 151 * 152 * That is, a nanoapp built with the Android O version of this 153 * API should not expect to run on a CHRE built with 154 * the Android N API. Similarly, a nanoapp build with the 155 * Android N API should not expect to run on a CHRE 156 * build with the Android O API. Such a nanoapp will need to 157 * recompiled with the appropriate API in order to work. 158 */ 159 160 #endif /* _CHRE_H_ */ 161 162