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