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 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 * 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 */ 121 struct 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 */ 161 typedef 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 */ 177 typedef 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 */ 211 bool 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 */ 263 bool 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