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