1 /* 2 * Copyright (C) 2019 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_PAL_SENSOR_H_ 18 #define CHRE_PAL_SENSOR_H_ 19 20 #include <cstdbool> 21 #include <cstdint> 22 23 #include "chre/pal/system.h" 24 #include "chre/pal/version.h" 25 #include "chre_api/chre/sensor.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * Initial version of the CHRE sensor PAL, tied to CHRE API v1.3. 33 */ 34 #define CHRE_PAL_SENSOR_API_V1_3 CHRE_PAL_CREATE_API_VERSION(1, 3) 35 36 // v1.0-v1.2 skipped to avoid confusion with older versions of the CHRE API. 37 #define CHRE_PAL_SENSOR_API_CURRENT_VERSION CHRE_PAL_SENSOR_API_V1_3 38 39 /** 40 * ID value that must be returned from flush() if request IDs are not 41 * supported by this PAL. 42 */ 43 #define CHRE_PAL_SENSOR_FLUSH_UNSUPPORTED_REQUEST_ID UINT32_MAX 44 45 /** 46 * The amount of time, in seconds, that the getSensors() method can block for 47 * before returning. 48 */ 49 #define CHRE_PAL_SENSOR_SENSOR_INIT_TIMEOUT_SEC 45 50 51 struct chrePalSensorCallbacks { 52 /** 53 * Invoked whenever a sensor's sampling status changes or when 54 * chrePalSensorApi.configureSensor is initially invoked for a given sensor. 55 * 56 * All fields in the provided status must represent the current sampling 57 * status of the sensor. 58 * 59 * This function call passes ownership of the status memory to the core CHRE 60 * system, i.e. the PAL module must not modify the referenced data until the 61 * associated API function is called to release the memory. 62 * 63 * @param sensorInfoIndex The index into the array returned by 64 * chrePalSensorApi.getSensors indicating the sensor this status update 65 * corresponds to. 66 * @param status The latest sampling status for the given sensor. The PAL must 67 * ensure this memory remains accessible until 68 * releaseSamplingStatusEvent() is invoked. 69 * 70 * @see chrePalSensorApi.configureSensor 71 */ 72 void (*samplingStatusUpdateCallback)(uint32_t sensorInfoIndex, 73 struct chreSensorSamplingStatus *status); 74 75 /** 76 * Callback used to pass new sensor data that's been generated for the sensor 77 * specified by the sensorInfoIndex. 78 * 79 * The event data format is one of the chreSensorXXXData defined in the CHRE 80 * API, implicitly specified by the sensor type. 81 * 82 * This function call passes ownership of the data memory to the core CHRE 83 * system, i.e. the PAL module must not modify the referenced data until the 84 * associated API function is called to release the memory. 85 * 86 * @param sensorInfoIndex The index into the array returned by 87 * chrePalSensorApi.getSensors indicating the sensor this sensor data 88 * corresponds to. 89 * @param data The sensor data in one of the chreSensorXXXData formats as 90 * required by the sensor type for the given sensor. The PAL must ensure 91 * this memory remains accessible until releaseSensorDataEvent() is 92 * invoked. 93 */ 94 void (*dataEventCallback)(uint32_t sensorInfoIndex, void *data); 95 96 /** 97 * Invoked whenever a sensor bias event is generated or when bias events have 98 * been enabled for a given sensor and the latest bias values need to be 99 * delivered. 100 * 101 * @param sensorInfoIndex The index into the array returned by 102 * chrePalSensorApi.getSensors indicating the sensor this bias data 103 * corresponds to. 104 * @param biasData The bias information in one of the chreSensorXXXData 105 * formats as required by the sensor type for the given sensor. The PAL 106 * must ensure this memory remains accessible until releaseBiasEvent() 107 * is invoked. 108 * 109 * @see chrePalSensorApi.configureBiasEvents 110 */ 111 void (*biasEventCallback)(uint32_t sensorInfoIndex, void *biasData); 112 113 /** 114 * Invoked whenever a request issued through chrePalSensorApi.flush has 115 * completed. 116 * 117 * This callback must be invoked no later than 118 * CHRE_SENSOR_FLUSH_COMPLETE_TIMEOUT_NS after chrePalSensorApi.flush was 119 * called. 120 * 121 * @param sensorInfoIndex The index into the array returned by 122 * chrePalSensorApi.getSensors indicating the sensor this flush completion 123 * corresponds to. 124 * @param flushRequestId UID corresponding to what the PAL returned when the 125 * flush was requested. Can be set to 126 * CHRE_PAL_SENSOR_FLUSH_UNSUPPORTED_REQUEST_ID if the PAL implementation 127 * doesn't support flush requests. 128 * @param errorCode Value from the chreError enum specifying any error that 129 * occurred while processing the flush request. CHRE_ERROR_NONE if 130 * the request was successful. 131 * 132 * @see chrePalSensorApi.flush 133 */ 134 void (*flushCompleteCallback)(uint32_t sensorInfoIndex, 135 uint32_t flushRequestId, uint8_t errorCode); 136 }; 137 138 struct chrePalSensorApi { 139 /** 140 * Version of the module providing this API. This value must be 141 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 142 * API version constant (CHRE_PAL_SENSOR_API_*) and the module-specific patch 143 * version. 144 */ 145 uint32_t moduleVersion; 146 147 /** 148 * Initializes the sensor module. Initialization must complete synchronously. 149 * 150 * @param systemApi Structure containing CHRE system function pointers which 151 * the PAL implementation should prefer to use over equivalent 152 * functionality exposed by the underlying platform. The module does 153 * not need to deep-copy this structure; its memory remains 154 * accessible at least until after close() is called. 155 * @param callbacks Structure containing entry points to the core CHRE 156 * system. The module does not need to deep-copy this structure; its 157 * memory remains accessible at least until after close() is called. 158 * 159 * @return true if initialization was successful, false otherwise 160 */ 161 bool (*open)(const struct chrePalSystemApi *systemApi, 162 const struct chrePalSensorCallbacks *callbacks); 163 164 /** 165 * Performs clean shutdown of the sensor module, usually done in preparation 166 * for stopping the CHRE. The sensor module must end any active requests to 167 * ensure that it will not invoke any callbacks past this point, and 168 * complete any relevant teardown activities before returning from this 169 * function. The PAL must also free any memory (e.g. the sensor array if it 170 * was dynamically allocated) inside this function. 171 */ 172 void (*close)(); 173 174 /** 175 * Creates a chreSensorInfo struct for every CHRE-supported sensor that is 176 * able to be communicated with via the PAL and places them into an array that 177 * is passed to the framework via the sensors parameter. The memory used for 178 * the array is owned by the PAL and may be statically or dynamically 179 * allocated. If the PAL dynamically allocates the array, it must be freed 180 * when close() is invoked. 181 * 182 * This function must block until all CHRE-supported sensors are able to be 183 * communicated with via the PAL and all info required by the chreSensorInfo 184 * struct has been retrieved. No more than 185 * CHRE_PAL_SENSOR_SENSOR_INIT_TIMEOUT_SEC must pass between the time this 186 * method is invoked and when it returns. 187 * 188 * If more than CHRE_PAL_SENSOR_SENSOR_INIT_TIMEOUT_SEC pass, this function 189 * must return with an array that includes as many sensors as the PAL was able 190 * to ensure could be communicated with during that time. 191 * 192 * If the PAL supports multiple sensors of the same sensor type, the default 193 * sensor should be listed first in the returned array. 194 * 195 * This method will only be invoked once during the CHRE framework's 196 * initialization process. 197 * 198 * @param sensors A non-null pointer to an array that must be initialized 199 * and populated with all sensors the PAL needs to make available to the 200 * CHRE framework on this device. 201 * @param arraySize The size of the filled in sensors array. 202 * @return false if any errors occurred while attempting to discover sensors. 203 * true if all sensors are available. If false, the sensors array may be 204 * partially filled. 205 */ 206 bool (*getSensors)(struct chreSensorInfo *const *sensors, 207 uint32_t *arraySize); 208 209 /** 210 * Configures the sensor specified by the given index into the array returned 211 * by getSensors() following the same set of requirements as 212 * chreSensorConfigure(). 213 * 214 * It's guaranteed that only one request from CHRE will be issued for any 215 * sensor at a time. If a new request is issued for a sensor with an active 216 * request, the CHRE framework expects it would override the existing one. 217 * 218 * Additionally, the CHRE framework will verify the issued request is valid 219 * by checking against the chreSensorInfo for the issued sensor so the PAL 220 * can and should avoid duplicating these checks to remove extra logic. 221 * 222 * Once the request is accepted by the PAL, any sensor data generated by the 223 * sensor must be sent via the dataEventCallback(). Additionally, if this 224 * request enables the sensor, the samplingStatusUpdateCallback() must be 225 * invoked after processing CHRE's request to provide the latest sampling 226 * status. 227 * 228 * As mentioned in chreSensorConfigure, bias event delivery must be enabled 229 * for calibrated sensor types automatically. An added recommendation is that 230 * the PAL should deliver the bias data at the same interval that sensor data 231 * is delivered, in order to optimize for power, with the bias data being 232 * delivered first so that nanoapps are easily able to translate sensor data 233 * if necessary. If bias events are not delivered at the same interval as the 234 * sensor data, they should be delivered as close to the corresponding sensor 235 * data as possible to reduce the amount of time nanoapps need to remember 236 * multiple bias updates. 237 * 238 * @param sensorInfoIndex The index into the array provided via getSensors() 239 * indicating the sensor that must be configured. 240 * @param mode chreSensorConfigureMode enum value specifying which mode the 241 * sensor must be configured for. 242 * @param intervalNs The interval, in nanoseconds, at which events must be 243 * generated by the sensor. 244 * @param latencyNs The maximum latency, in nanoseconds, allowed before the 245 * PAL begins delivery of events. This will control how many events can be 246 * queued by the sensor before requiring a delivery event. 247 * @return true if the configuration succeeded, false otherwise. 248 */ 249 bool (*configureSensor)(uint32_t sensorInfoIndex, 250 enum chreSensorConfigureMode mode, 251 uint64_t intervalNs, uint64_t latencyNs); 252 253 /** 254 * Issues a request to flush all samples stored for batching. The PAL 255 * implementation is expected to unconditionally issue this request for the 256 * given sensor. The CHRE framework will ensure that it must have an active, 257 * powered, batching request issued through configureSensor before invoking 258 * this method. 259 * 260 * It's strongly recommended that PAL implementations support request IDs per 261 * flush request to allow the framework to issue multiple flush requests per 262 * sensor and remove the need for queueing in CHRE. 263 * 264 * Once the PAL accepts the flush request, it's required that the earlier 265 * provided flushCompleteCallback() will be invoked once the flush request 266 * has completed. The PAL is responsible for not allowing more than 267 * CHRE_SENSOR_FLUSH_COMPLETE_TIMEOUT_NS to pass after this flush request has 268 * been issued before invoking the flushCompleteCallback(). If more than 269 * CHRE_SENSOR_FLUSH_COMPLETE_TIMEOUT_NS pass, the PAL is required to invoke 270 * flushCompleteCallback() with an errorCode value of CHRE_ERROR_TIMEOUT to 271 * allow the CHRE framework to recover from the timeout. 272 * 273 * @param sensorInfoIndex The index into the array provided via getSensors() 274 * indicating the sensor that must have its samples flushed 275 * @param flushRequestId A pointer where a UID will be stored identify this 276 * flush request. Must be set to 277 * CHRE_PAL_SENSOR_FLUSH_UNSUPPORTED_REQUEST_ID if request IDs are not 278 * supported by this PAL. This value must be passed into 279 * flushCompleteCallback() when the flush request is completed. 280 * @return true if the request was accepted for processing, false otherwise. 281 * 282 * @see chreSensorFlushAsync 283 */ 284 bool (*flush)(uint32_t sensorInfoIndex, uint32_t *flushRequestId); 285 286 /** 287 * Configures the reception of bias events for the specified sensor. 288 * 289 * It's required that this implementation meets the same requirements as 290 * chreSensorConfigureBiasEvents() with one key difference: 291 * - The framework will only enable bias events for a given sensor after it 292 * has placed an active request through configureSensor() and will ensure 293 * bias events are not enabled for sensors that don't have an active request 294 * in place. 295 * 296 * Additionally, as specified for configureSensor(), it is recommended that 297 * the PAL should deliver the bias data at the same interval that sensor data 298 * is delivered, in order to optimize for power, with the bias data being 299 * delivered first so that nanoapps are easily able to translate sensor data 300 * if necessary. If bias events are not delivered at the same interval as the 301 * sensor data, they should be delivered as close to the corresponding sensor 302 * data as possible to reduce the amount of time nanoapps need to remember 303 * multiple bias updates. 304 * 305 * Once bias delivery is enabled for a given sensor, the PAL is required to 306 * invoke biasEventCallback() with the latest bias and any future bias updates 307 * received from the sensor. 308 * 309 * @param sensorInfoIndex The index into the array provided via getSensors() 310 * indicating the sensor that bias events must be enabled / disabled for 311 * @param enable whether to enable or disable bias event delivery 312 * @param latencyNs The maximum latency, in nanoseconds, allowed before the 313 * PAL begins delivery of events. This will control how many events can be 314 * queued before requiring a delivery event. This value will match 315 * the latency requested for sensor data through configureSensor() 316 */ 317 bool (*configureBiasEvents)(uint32_t sensorInfoIndex, bool enable, 318 uint64_t latencyNs); 319 320 /** 321 * Synchronously provides the most recent bias info available for a sensor. 322 * 323 * The implementation of this function must meet the same requirements as 324 * specified for chreSensorGetThreeAxisBias(). 325 * 326 * @param sensorInfoIndex The index into the array provided via getSensors() 327 * indicating the sensor that bias info must be returned for 328 * @param bias A pointer to where the bias will be stored 329 * @return true if the bias was successfully stored, false if the 330 * sensorInfoIndex is invalid or the sensor doesn't support three axis bias 331 * delivery 332 */ 333 bool (*getThreeAxisBias)(uint32_t sensorInfoIndex, 334 struct chreSensorThreeAxisData *bias); 335 336 /** 337 * Invoked when the core CHRE system no longer needs a status update event 338 * that was provided via dataEventCallback() 339 * 340 * @param data Sensor data to release 341 */ 342 void (*releaseSensorDataEvent)(void *data); 343 344 /** 345 * Invoked when the core CHRE system no longer needs a status update event 346 * that was provided via samplingStatusUpdateCallback() 347 * 348 * @param status Sampling status update to release 349 */ 350 void (*releaseSamplingStatusEvent)(struct chreSensorSamplingStatus *status); 351 352 /** 353 * Invoked when the core CHRE system no longer needs a bias event that was 354 * provided via biasEventCallback() 355 * 356 * @param bias Bias data to release 357 */ 358 void (*releaseBiasEvent)(void *bias); 359 }; 360 361 /** 362 * Retrieve a handle for the CHRE sensor PAL. 363 * 364 * @param requestedApiVersion The implementation of this function must return a 365 * pointer to a structure with the same major version as requested. 366 * @return Pointer to API handle, or NULL if a compatible API version is not 367 * supported by the module, or the API as a whole is not implemented. If 368 * non-NULL, the returned API handle must be valid as long as this 369 * module is loaded. 370 */ 371 const struct chrePalSensorApi *chrePalSensorGetApi( 372 uint32_t requestedApiVersion); 373 374 #ifdef __cplusplus 375 } 376 #endif 377 378 #endif // CHRE_PAL_SENSOR_H_ 379