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