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_EVENT_H_
18#define _CHRE_EVENT_H_
19
20/**
21 * Context Hub Runtime Environment API dealing with events and messages.
22 */
23
24
25#include <stdbool.h>
26#include <stdint.h>
27#include <stdlib.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/**
34 * The CHRE implementation is required to provide the following
35 * preprocessor defines via the build system.
36 *
37 * CHRE_MESSAGE_TO_HOST_MAX_SIZE: The maximum size, in bytes, allowed for
38 *     a message sent to chreSendMessageToHost().  This must be at least
39 *     CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE.
40 */
41
42#ifndef CHRE_MESSAGE_TO_HOST_MAX_SIZE
43#error CHRE_MESSAGE_TO_HOST_MAX_SIZE must be defined by the Context Hub Runtime Environment implementation
44#endif
45
46/**
47 * The minimum size, in bytes, any CHRE implementation will
48 * use for CHRE_MESSAGE_TO_HOST_MAX_SIZE.
49 */
50#define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE 128
51
52#if CHRE_MESSAGE_TO_HOST_MAX_SIZE < CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE
53#error CHRE_MESSAGE_TO_HOST_MAX_SIZE is too small.
54#endif
55
56/**
57 * The lowest numerical value legal for a user-defined event.
58 *
59 * The system reserves all event values from 0 to 0x7FFF, inclusive.
60 * User events may use any value in the range 0x8000 to 0xFFFF, inclusive.
61 *
62 * Note that the same event values might be used by different nanoapps
63 * for different meanings.  This is not a concern, as these values only
64 * have meaning when paired with the originating nanoapp.
65 */
66#define CHRE_EVENT_FIRST_USER_VALUE  UINT16_C(0x8000)
67
68/**
69 * nanoappHandleEvent argument: struct chreMessageFromHostData
70 *
71 * The format of the 'message' part of this structure is left undefined,
72 * and it's up to the nanoapp and host to have an established protocol
73 * beforehand.
74 */
75#define CHRE_EVENT_MESSAGE_FROM_HOST  UINT16_C(0x0001)
76
77/**
78 * nanoappHandleEvent argument: 'cookie' given to chreTimerSet() method.
79 *
80 * Indicates that a timer has elapsed, in accordance with how chreTimerSet() was
81 * invoked.
82 */
83#define CHRE_EVENT_TIMER  UINT16_C(0x0002)
84
85/**
86 * First possible value for CHRE_EVENT_SENSOR events.
87 *
88 * This allows us to separately define our CHRE_EVENT_SENSOR_* events in
89 * chre_sensor.h, without fear of collision with other event values.
90 */
91#define CHRE_EVENT_SENSOR_FIRST_EVENT  UINT16_C(0x0100)
92
93/**
94 * Last possible value for CHRE_EVENT_SENSOR events.
95 *
96 * This allows us to separately define our CHRE_EVENT_SENSOR_* events in
97 * chre_sensor.h, without fear of collision with other event values.
98 */
99#define CHRE_EVENT_SENSOR_LAST_EVENT  UINT16_C(0x02FF)
100
101/**
102 * First in a range of values dedicated for internal CHRE implementation usage.
103 *
104 * If a CHRE wishes to use events internally, any values within this range
105 * are assured not to be taken by future CHRE API additions.
106 */
107#define CHRE_EVENT_INTERNAL_FIRST_EVENT  UINT16_C(0x7E00)
108
109/**
110 * Last in a range of values dedicated for internal CHRE implementation usage.
111 *
112 * If a CHRE wishes to use events internally, any values within this range
113 * are assured not to be taken by future CHRE API additions.
114 */
115#define CHRE_EVENT_INTERNAL_LAST_EVENT  UINT16_C(0x7FFF)
116
117
118/**
119 * CHRE_EVENT_MESSAGE_FROM_HOST
120 */
121struct chreMessageFromHostData {
122    /**
123     * Message type (NOTE: not implemented correctly in the Android N release).
124     *
125     * In future releases, this will be a message type provided by the host.
126     */
127    uint32_t reservedMessageType;
128
129    /**
130     * The size, in bytes of the following 'message'.
131     *
132     * This can be 0.
133     */
134    uint32_t messageSize;
135
136    /**
137     * The message from the host.
138     *
139     * These contents are of a format that the host and nanoapp must have
140     * established beforehand.
141     *
142     * This data is 'messageSize' bytes in length.  Note that if 'messageSize'
143     * is 0, this might be NULL.
144     */
145    const void *message;
146};
147
148/**
149 * Callback which frees data associated with an event.
150 *
151 * This callback is (optionally) provided to the chreSendEvent() method as
152 * a means for freeing the event data and performing any other cleanup
153 * necessary when the event is completed.  When this callback is invoked,
154 * 'eventData' is no longer needed and can be released.
155 *
156 * @param eventType  The 'eventType' argument from chreSendEvent().
157 * @param eventData  The 'eventData' argument from chreSendEvent().
158 *
159 * @see chreSendEvent
160 */
161typedef void (chreEventCompleteFunction)(uint16_t eventType, void *eventData);
162
163/**
164 * Callback which frees a message.
165 *
166 * This callback is (optionally) provided to the chreSendMessageToHost() method
167 * as a means for freeing the message.  When this callback is invoked,
168 * 'message' is no longer needed and can be released.  Note that this in
169 * no way assures that said message did or did not make it to the host, simply
170 * that this memory is no longer needed.
171 *
172 * @param message  The 'message' argument from chreSendMessageToHost().
173 * @param messageSize  The 'messageSize' argument from chreSendMessageToHost().
174 *
175 * @see chreSendMessageToHost
176 */
177typedef void (chreMessageFreeFunction)(void *message, size_t messageSize);
178
179
180
181/**
182 * Enqueue an event to be sent to another nanoapp.
183 *
184 * Note: This version of the API does not give an easy means to discover
185 * another nanoapp's instance ID.  For now, events will need to be sent to/from
186 * the host to initially discover these IDs.
187 *
188 * @param eventType  This is a user-defined event type, of at least the
189 *     value CHRE_EVENT_FIRST_USER_VALUE.  It is illegal to attempt to use any
190 *     of the CHRE_EVENT_* values reserved for the CHRE.
191 * @param eventData  A pointer value that will be understood by the receiving
192 *     app.  Note that NULL is perfectly acceptable.  It also is not required
193 *     that this be a valid pointer, although if this nanoapp is intended to
194 *     work on arbitrary CHRE implementations, then the size of a
195 *     pointer cannot be assumed to be a certain size.  Note that the caller
196 *     no longer owns this memory after the call.
197 * @param freeCallback  A pointer to a callback function.  After the lifetime
198 *     of 'eventData' is over (either through successful delivery or the event
199 *     being dropped), this callback will be invoked.  This argument is allowed
200 *     to be NULL, in which case no callback will be invoked.
201 * @param targetInstanceId  The ID of the instance we're delivering this event
202 *     to.  Note that this is allowed to be our own instance.
203 * @returns true if the event was enqueued, false otherwise.  Note that even
204 *     if this method returns 'false', the 'freeCallback' will be invoked,
205 *     if non-NULL.  Note in the 'false' case, the 'freeCallback' may be
206 *     invoked directly from within chreSendEvent(), so it's necessary
207 *     for nanoapp authors to avoid possible recursion with this.
208 *
209 * @see chreEventDataFreeFunction
210 */
211bool chreSendEvent(uint16_t eventType, void *eventData,
212                   chreEventCompleteFunction *freeCallback,
213                   uint32_t targetInstanceId);
214
215/**
216 * Send a message to the host.
217 *
218 * This message is by definition arbitrarily defined.  Since we're not
219 * just a passing a pointer to memory around the system, but need to copy
220 * this into various buffers to send it to the host, the CHRE
221 * implementation cannot be asked to support an arbitrarily large message
222 * size.  As a result, we have the CHRE implementation define
223 * CHRE_MESSAGE_TO_HOST_MAX_SIZE.
224 *
225 * CHRE_MESSAGE_TO_HOST_MAX_SIZE is not given a value by the Platform API.  The
226 * Platform API does define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, and requires
227 * that CHRE_MESSAGE_TO_HOST_MAX_SIZE is at least that value.
228 *
229 * As a result, if your message sizes are all less than
230 * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, then you have no concerns on any
231 * CHRE implementation.  If your message sizes are larger, you'll need to
232 * come up with a strategy for splitting your message across several calls
233 * to this method.  As long as that strategy works for
234 * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, it will work across all CHRE
235 * implementations (although on some implementations less calls to this
236 * method may be necessary).
237 *
238 * @param message  Pointer to a block of memory to send to the host.
239 *     NULL is acceptable only if messageSize is 0.  If non-NULL, this
240 *     must be a legitimate pointer (that is, unlike chreSendEvent(), a small
241 *     integral value cannot be cast to a pointer for this).  Note that the
242 *     caller no longer owns this memory after the call.
243 * @param messageSize  The size, in bytes, of the given message.
244 *     This cannot exceed CHRE_MESSAGE_TO_HOST_MAX_SIZE.
245 * @param reservedMessageType  Message type sent to the app on the host.
246 *     NOTE: In the N release, there is a bug in some HAL implementations
247 *     where this data does not make it to the app running on the host.
248 *     Nanoapps cannot trust this across all platforms for N, but that
249 *     will be fixed in O.
250 * @param freeCallback  A pointer to a callback function.  After the lifetime
251 *     of 'message' is over (which does not assure that 'message' made it to
252 *     the host, just that the transport layer no longer needs this memory),
253 *     this callback will be invoked.  This argument is allowed
254 *     to be NULL, in which case no callback will be invoked.
255 * @returns true if the message was accepted for transmission, false otherwise.
256 *     Note that even if this method returns 'false', the 'freeCallback' will
257 *     be invoked, if non-NULL.  In either case, the 'freeCallback' may be
258 *     invoked directly from within chreSendMessageToHost(), so it's necessary
259 *     for nanoapp authors to avoid possible recursion with this.
260 *
261 * @see chreMessageFreeFunction
262 */
263bool chreSendMessageToHost(void *message, uint32_t messageSize,
264                           uint32_t reservedMessageType,
265                           chreMessageFreeFunction *freeCallback);
266
267
268#ifdef __cplusplus
269}
270#endif
271
272#endif  /* _CHRE_EVENT_H_ */
273
274