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