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 * @file
22 * Context Hub Runtime Environment API dealing with events and messages.
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 * nanoappHandleEvent argument: struct chreNanoappInfo
87 *
88 * Indicates that a nanoapp has successfully started (its nanoappStart()
89 * function has been called, and it returned true) and is able to receive events
90 * sent via chreSendEvent().  Note that this event is not sent for nanoapps that
91 * were started prior to the current nanoapp - use chreGetNanoappInfo() to
92 * determine if another nanoapp is already running.
93 *
94 * @since v1.1
95 */
96#define CHRE_EVENT_NANOAPP_STARTED  UINT16_C(0x0003)
97
98/**
99 * nanoappHandleEvent argument: struct chreNanoappInfo
100 *
101 * Indicates that a nanoapp has stopped executing and is no longer able to
102 * receive events sent via chreSendEvent().  Any events sent prior to receiving
103 * this event are not guaranteed to have been delivered.
104 *
105 * @since v1.1
106 */
107#define CHRE_EVENT_NANOAPP_STOPPED  UINT16_C(0x0004)
108
109/**
110 * First possible value for CHRE_EVENT_SENSOR events.
111 *
112 * This allows us to separately define our CHRE_EVENT_SENSOR_* events in
113 * chre/sensor.h, without fear of collision with other event values.
114 */
115#define CHRE_EVENT_SENSOR_FIRST_EVENT  UINT16_C(0x0100)
116
117/**
118 * Last possible value for CHRE_EVENT_SENSOR events.
119 *
120 * This allows us to separately define our CHRE_EVENT_SENSOR_* events in
121 * chre/sensor.h, without fear of collision with other event values.
122 */
123#define CHRE_EVENT_SENSOR_LAST_EVENT  UINT16_C(0x02FF)
124
125/**
126 * First event in the block reserved for GNSS. These events are defined in
127 * chre/gnss.h.
128 */
129#define CHRE_EVENT_GNSS_FIRST_EVENT  UINT16_C(0x0300)
130#define CHRE_EVENT_GNSS_LAST_EVENT   UINT16_C(0x030F)
131
132/**
133 * First event in the block reserved for WiFi. These events are defined in
134 * chre/wifi.h.
135 */
136#define CHRE_EVENT_WIFI_FIRST_EVENT  UINT16_C(0x0310)
137#define CHRE_EVENT_WIFI_LAST_EVENT   UINT16_C(0x031F)
138
139/**
140 * First event in the block reserved for WWAN. These events are defined in
141 * chre/wwan.h.
142 */
143#define CHRE_EVENT_WWAN_FIRST_EVENT  UINT16_C(0x0320)
144#define CHRE_EVENT_WWAN_LAST_EVENT   UINT16_C(0x032F)
145
146/**
147 * First in a range of values dedicated for internal CHRE implementation usage.
148 *
149 * If a CHRE wishes to use events internally, any values within this range
150 * are assured not to be taken by future CHRE API additions.
151 */
152#define CHRE_EVENT_INTERNAL_FIRST_EVENT  UINT16_C(0x7E00)
153
154/**
155 * Last in a range of values dedicated for internal CHRE implementation usage.
156 *
157 * If a CHRE wishes to use events internally, any values within this range
158 * are assured not to be taken by future CHRE API additions.
159 */
160#define CHRE_EVENT_INTERNAL_LAST_EVENT  UINT16_C(0x7FFF)
161
162/**
163 * A special value for the hostEndpoint argument in
164 * chreSendMessageToHostEndpoint() that indicates that the message should be
165 * delivered to all host endpoints.  This value will not be used in the
166 * hostEndpoint field of struct chreMessageFromHostData supplied with
167 * CHRE_EVENT_MESSAGE_FROM_HOST.
168 *
169 * @since v1.1
170 */
171#define CHRE_HOST_ENDPOINT_BROADCAST  UINT16_C(0xFFFF)
172
173/**
174 * A special value for hostEndpoint in struct chreMessageFromHostData that
175 * indicates that a host endpoint is unknown or otherwise unspecified.  This
176 * value may be received in CHRE_EVENT_MESSAGE_FROM_HOST, but it is not valid to
177 * provide it to chreSendMessageToHostEndpoint().
178 *
179 * @since v1.1
180 */
181#define CHRE_HOST_ENDPOINT_UNSPECIFIED  UINT16_C(0xFFFE)
182
183
184/**
185 * Data provided with CHRE_EVENT_MESSAGE_FROM_HOST.
186 */
187struct chreMessageFromHostData {
188    /**
189     * Message type supplied by the host.
190     *
191     * NOTE: In CHRE API v1.0, support for forwarding this field from the host
192     * was not strictly required, and some implementations did not support it.
193     * However, its support is mandatory as of v1.1.
194     */
195    uint32_t messageType;
196
197    /**
198     * The size, in bytes of the following 'message'.
199     *
200     * This can be 0.
201     */
202    uint32_t messageSize;
203
204    /**
205     * The message from the host.
206     *
207     * These contents are of a format that the host and nanoapp must have
208     * established beforehand.
209     *
210     * This data is 'messageSize' bytes in length.  Note that if 'messageSize'
211     * is 0, this might be NULL.
212     */
213    const void *message;
214
215    /**
216     * An identifier for the host-side entity that sent this message.  Unless
217     * this is set to CHRE_HOST_ENDPOINT_UNSPECIFIED, it can be used in
218     * chreSendMessageToHostEndpoint() to send a directed reply that will only
219     * be received by the given entity on the host.  Endpoint identifiers are
220     * opaque values assigned at runtime, so they cannot be assumed to always
221     * describe a specific entity across restarts.
222     *
223     * If running on a CHRE API v1.0 implementation, this field will always be
224     * set to CHRE_HOST_ENDPOINT_UNSPECIFIED.
225     *
226     * @since v1.1
227     */
228    uint16_t hostEndpoint;
229};
230
231/**
232 * Provides metadata for a nanoapp in the system.
233 */
234struct chreNanoappInfo {
235    /**
236     * Nanoapp identifier. The convention for populating this value is to set
237     * the most significant 5 bytes to a value that uniquely identifies the
238     * vendor, and the lower 3 bytes identify the nanoapp.
239     */
240    uint64_t appId;
241
242    /**
243     * Nanoapp version.  The semantics of this field are defined by the nanoapp,
244     * however nanoapps are recommended to follow the same scheme used for the
245     * CHRE version exposed in chreGetVersion().  That is, the most significant
246     * byte represents the major version, the next byte the minor version, and
247     * the lower two bytes the patch version.
248     */
249    uint32_t version;
250
251    /**
252     * The instance ID of this nanoapp, which can be used in chreSendEvent() to
253     * address an event specifically to this nanoapp.  This identifier is
254     * guaranteed to be unique among all nanoapps in the system.
255     */
256    uint32_t instanceId;
257};
258
259/**
260 * Callback which frees data associated with an event.
261 *
262 * This callback is (optionally) provided to the chreSendEvent() method as
263 * a means for freeing the event data and performing any other cleanup
264 * necessary when the event is completed.  When this callback is invoked,
265 * 'eventData' is no longer needed and can be released.
266 *
267 * @param eventType  The 'eventType' argument from chreSendEvent().
268 * @param eventData  The 'eventData' argument from chreSendEvent().
269 *
270 * @see chreSendEvent
271 */
272typedef void (chreEventCompleteFunction)(uint16_t eventType, void *eventData);
273
274/**
275 * Callback which frees a message.
276 *
277 * This callback is (optionally) provided to the chreSendMessageToHost() method
278 * as a means for freeing the message.  When this callback is invoked,
279 * 'message' is no longer needed and can be released.  Note that this in
280 * no way assures that said message did or did not make it to the host, simply
281 * that this memory is no longer needed.
282 *
283 * @param message  The 'message' argument from chreSendMessageToHost().
284 * @param messageSize  The 'messageSize' argument from chreSendMessageToHost().
285 *
286 * @see chreSendMessageToHost
287 */
288typedef void (chreMessageFreeFunction)(void *message, size_t messageSize);
289
290
291/**
292 * Enqueue an event to be sent to another nanoapp.
293 *
294 * Note: This version of the API does not give an easy means to discover
295 * another nanoapp's instance ID.  For now, events will need to be sent to/from
296 * the host to initially discover these IDs.
297 *
298 * @param eventType  This is a user-defined event type, of at least the
299 *     value CHRE_EVENT_FIRST_USER_VALUE.  It is illegal to attempt to use any
300 *     of the CHRE_EVENT_* values reserved for the CHRE.
301 * @param eventData  A pointer value that will be understood by the receiving
302 *     app.  Note that NULL is perfectly acceptable.  It also is not required
303 *     that this be a valid pointer, although if this nanoapp is intended to
304 *     work on arbitrary CHRE implementations, then the size of a
305 *     pointer cannot be assumed to be a certain size.  Note that the caller
306 *     no longer owns this memory after the call.
307 * @param freeCallback  A pointer to a callback function.  After the lifetime
308 *     of 'eventData' is over (either through successful delivery or the event
309 *     being dropped), this callback will be invoked.  This argument is allowed
310 *     to be NULL, in which case no callback will be invoked.
311 * @param targetInstanceId  The ID of the instance we're delivering this event
312 *     to.  Note that this is allowed to be our own instance.
313 * @returns true if the event was enqueued, false otherwise.  Note that even
314 *     if this method returns 'false', the 'freeCallback' will be invoked,
315 *     if non-NULL.  Note in the 'false' case, the 'freeCallback' may be
316 *     invoked directly from within chreSendEvent(), so it's necessary
317 *     for nanoapp authors to avoid possible recursion with this.
318 *
319 * @see chreEventDataFreeFunction
320 */
321bool chreSendEvent(uint16_t eventType, void *eventData,
322                   chreEventCompleteFunction *freeCallback,
323                   uint32_t targetInstanceId);
324
325/**
326 * Send a message to the host, using the broadcast endpoint
327 * CHRE_HOST_ENDPOINT_BROADCAST.  Refer to chreSendMessageToHostEndpoint() for
328 * further details.
329 *
330 * @see chreSendMessageToHostEndpoint
331 *
332 * @deprecated New code should use chreSendMessageToHostEndpoint() instead of
333 * this function.  A future update to the API may cause references to this
334 * function to produce a compiler warning.
335 */
336bool chreSendMessageToHost(void *message, uint32_t messageSize,
337                           uint32_t messageType,
338                           chreMessageFreeFunction *freeCallback);
339
340/**
341 * Send a message to the host.
342 *
343 * This message is by definition arbitrarily defined.  Since we're not
344 * just a passing a pointer to memory around the system, but need to copy
345 * this into various buffers to send it to the host, the CHRE
346 * implementation cannot be asked to support an arbitrarily large message
347 * size.  As a result, we have the CHRE implementation define
348 * CHRE_MESSAGE_TO_HOST_MAX_SIZE.
349 *
350 * CHRE_MESSAGE_TO_HOST_MAX_SIZE is not given a value by the Platform API.  The
351 * Platform API does define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, and requires
352 * that CHRE_MESSAGE_TO_HOST_MAX_SIZE is at least that value.
353 *
354 * As a result, if your message sizes are all less than
355 * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, then you have no concerns on any
356 * CHRE implementation.  If your message sizes are larger, you'll need to
357 * come up with a strategy for splitting your message across several calls
358 * to this method.  As long as that strategy works for
359 * CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, it will work across all CHRE
360 * implementations (although on some implementations less calls to this
361 * method may be necessary).
362 *
363 * @param message  Pointer to a block of memory to send to the host.
364 *     NULL is acceptable only if messageSize is 0.  If non-NULL, this
365 *     must be a legitimate pointer (that is, unlike chreSendEvent(), a small
366 *     integral value cannot be cast to a pointer for this).  Note that the
367 *     caller no longer owns this memory after the call.
368 * @param messageSize  The size, in bytes, of the given message.
369 *     This cannot exceed CHRE_MESSAGE_TO_HOST_MAX_SIZE.
370 * @param messageType  Message type sent to the app on the host.
371 *     NOTE: In CHRE API v1.0, support for forwarding this field to the host was
372 *     not strictly required, and some implementations did not support it.
373 *     However, its support is mandatory as of v1.1.
374 * @param hostEndpoint  An identifier for the intended recipient of the message,
375 *     or CHRE_HOST_ENDPOINT_BROADCAST if all registered endpoints on the host
376 *     should receive the message.  Endpoint identifiers are assigned on the
377 *     host side, and nanoapps may learn of the host endpoint ID of an intended
378 *     recipient via an initial message sent by the host.  This parameter is
379 *     always treated as CHRE_HOST_ENDPOINT_BROADCAST if running on a CHRE API
380 *     v1.0 implementation.
381 * @param freeCallback  A pointer to a callback function.  After the lifetime
382 *     of 'message' is over (which does not assure that 'message' made it to
383 *     the host, just that the transport layer no longer needs this memory),
384 *     this callback will be invoked.  This argument is allowed
385 *     to be NULL, in which case no callback will be invoked.
386 * @returns true if the message was accepted for transmission, false otherwise.
387 *     Note that even if this method returns 'false', the 'freeCallback' will
388 *     be invoked, if non-NULL.  In either case, the 'freeCallback' may be
389 *     invoked directly from within chreSendMessageToHost(), so it's necessary
390 *     for nanoapp authors to avoid possible recursion with this.
391 *
392 * @see chreMessageFreeFunction
393 *
394 * @since v1.1
395 */
396bool chreSendMessageToHostEndpoint(void *message, size_t messageSize,
397                                   uint32_t messageType, uint16_t hostEndpoint,
398                                   chreMessageFreeFunction *freeCallback);
399
400/**
401 * Queries for information about a nanoapp running in the system.
402 *
403 * In the current API, appId is required to be unique, i.e. there cannot be two
404 * nanoapps running concurrently with the same appId.  If this restriction is
405 * removed in a future API version and multiple instances of the same appId are
406 * present, this function must always return the first app to start.
407 *
408 * @param appId Identifier for the nanoapp that the caller is requesting
409 *     information about.
410 * @param info Output parameter.  If this function returns true, this structure
411 *     will be populated with details of the specified nanoapp.
412 * @returns true if a nanoapp with the given ID is currently running, and the
413 *     supplied info parameter was populated with its information.
414 *
415 * @since v1.1
416 */
417bool chreGetNanoappInfoByAppId(uint64_t appId, struct chreNanoappInfo *info);
418
419/**
420 * Queries for information about a nanoapp running in the system, using the
421 * runtime unique identifier.  This method can be used to get information about
422 * the sender of an event.
423 *
424 * @param instanceId
425 * @param info Output parameter.  If this function returns true, this structure
426 *     will be populated with details of the specified nanoapp.
427 * @returns true if a nanoapp with the given instance ID is currently running,
428 *     and the supplied info parameter was populated with its information.
429 *
430 * @since v1.1
431 */
432bool chreGetNanoappInfoByInstanceId(uint32_t instanceId,
433                                    struct chreNanoappInfo *info);
434
435
436#ifdef __cplusplus
437}
438#endif
439
440#endif  /* _CHRE_EVENT_H_ */
441
442