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_PAL_GNSS_H_ 18 #define CHRE_PAL_GNSS_H_ 19 20 /** 21 * @file 22 * Defines the interface between the common CHRE core system and the 23 * platform-specific GNSS module. This API is largely asynchronous - any 24 * implementation must be able to handle multiple outstanding requests to 25 * asynchronous APIs such as controlLocationSession() under reasonable resource 26 * constraints. Requests to the same API and their associated responses must be 27 * handled strictly in-order. Refer to {@link #chreAsyncResult} for more 28 * information. 29 */ 30 31 #include <stdbool.h> 32 #include <stdint.h> 33 34 #include "chre/pal/system.h" 35 #include "chre/pal/version.h" 36 #include "chre_api/chre/common.h" 37 #include "chre_api/chre/gnss.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * Initial version of the CHRE GNSS PAL, tied to CHRE API v1.1. 45 */ 46 #define CHRE_PAL_GNSS_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0) 47 48 // v1.1 skipped to avoid confusion with CHRE API v1.1 49 50 /** 51 * Introduced alongside CHRE API v1.2, adding support for listening in on GNSS 52 * fixes initiated by other clients of the GNSS engine via 53 * configurePassiveLocationListener(). 54 */ 55 #define CHRE_PAL_GNSS_API_V1_2 CHRE_PAL_CREATE_API_VERSION(1, 2) 56 57 /** 58 * Introduced alongside CHRE API v1.3, adding support for altitude/speed/bearing 59 * accuracy in chreGnssLocationEvent delivered by locationEventCallback. 60 */ 61 #define CHRE_PAL_GNSS_API_V1_3 CHRE_PAL_CREATE_API_VERSION(1, 3) 62 63 /** 64 * Introduced alongside CHRE API v1.4, adding support for carrier frequency in 65 * chreGnssMeasurement delivered by measurementStatusChangeCallback. 66 */ 67 #define CHRE_PAL_GNSS_API_V1_4 CHRE_PAL_CREATE_API_VERSION(1, 4) 68 69 /** 70 * The version of the CHRE GNSS PAL defined in this header file. 71 */ 72 #define CHRE_PAL_GNSS_API_CURRENT_VERSION CHRE_PAL_GNSS_API_V1_4 73 74 struct chrePalGnssCallbacks { 75 /** 76 * This function can be used by the PAL module to request that the core CHRE 77 * system re-send requests for any active sessions and its current passive 78 * location listener setting. For example, if the GNSS subsystem has 79 * recovered from a system crash, this function can be used to silently 80 * (from the client's perspective) restore open sessions. 81 */ 82 void (*requestStateResync)(void); 83 84 /** 85 * Callback invoked to inform the CHRE of the result of changes to the 86 * location session status requested via controlLocationSession in struct 87 * chrePalGnssApi. 88 * 89 * Unsolicited calls to this function must not be made. In other words, 90 * this callback should only be invoked as the direct result of an earlier 91 * call to controlLocationSession. If the location session is terminated on 92 * the remote end, then requestStateResync() should be used if it is due to 93 * a recoverable condition, otherwise the PAL should leave the location 94 * session in the "enabled" state even though it does not expect to deliver 95 * new location events. 96 * 97 * @param enabled true if the location session is currently active, false 98 * otherwise 99 * @param errorCode An error code from enum chreError 100 * 101 * @see chrePalGnssApi.controlLocationSession 102 * @see #chreError 103 */ 104 void (*locationStatusChangeCallback)(bool enabled, uint8_t errorCode); 105 106 /** 107 * Callback used to pass GNSS location fixes to the core CHRE system, which 108 * distributes it to clients (nanoapps). These events are only delivered 109 * while a location session is active, i.e. locationStatusChangeCallback was 110 * previously invoked with enabled=true. 111 * 112 * This function call passes ownership of the event memory to the core CHRE 113 * system, i.e. the PAL module must not modify the referenced data until the 114 * associated API function is called to release the memory. 115 * 116 * @param event Event data to distribute to clients. The GNSS module 117 * must ensure that this memory remains accessible until it is passed 118 * to the releaseLocationEvent function in struct chrePalGnssApi. 119 */ 120 void (*locationEventCallback)(struct chreGnssLocationEvent *event); 121 122 /** 123 * Callback invoked to inform the CHRE of the result of changes to the raw 124 * GNSS measurement session status requested via controlMeasurementSession 125 * in struct chrePalGnssApi. 126 * 127 * Unsolicited calls to this function must not be made. See 128 * locationStatusChangeCallback() for more information. 129 * 130 * @param enabled true if the measurement session is currently active, false 131 * otherwise 132 * @param errorCode An error code from enum chreError 133 */ 134 void (*measurementStatusChangeCallback)(bool enabled, uint8_t errorCode); 135 136 /** 137 * Callback used to pass raw GNSS measurement data from the GNSS module to 138 * the core CHRE system, which distributes it to clients (nanoapps). 139 * 140 * This function call passes ownership of the event memory to the core CHRE 141 * system, i.e. the PAL module must not modify the referenced data until the 142 * associated API function is called to release the memory. 143 * 144 * @param event Event data to distribute to clients. The GNSS module 145 * must ensure that this memory remains accessible until it is passed 146 * to the releaseMeasurementDataEvent() function in struct 147 * chrePalGnssApi. 148 */ 149 void (*measurementEventCallback)(struct chreGnssDataEvent *event); 150 }; 151 152 struct chrePalGnssApi { 153 /** 154 * Version of the module providing this API. This value should be 155 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 156 * API version constant (CHRE_PAL_GNSS_API_*) and the module-specific patch 157 * version. 158 */ 159 uint32_t moduleVersion; 160 161 /** 162 * Initializes the GNSS module. Initialization must complete synchronously. 163 * 164 * @param systemApi Structure containing CHRE system function pointers which 165 * the PAL implementation should prefer to use over equivalent 166 * functionality exposed by the underlying platform. The module does 167 * not need to deep-copy this structure; its memory remains 168 * accessible at least until after close() is called. 169 * @param callbacks Structure containing entry points to the core CHRE 170 * system. The module does not need to deep-copy this structure; its 171 * memory remains accessible at least until after close() is called. 172 * 173 * @return true if initialization was successful, false otherwise 174 */ 175 bool (*open)(const struct chrePalSystemApi *systemApi, 176 const struct chrePalGnssCallbacks *callbacks); 177 178 /** 179 * Performs clean shutdown of the GNSS module, usually done in preparation 180 * for stopping the CHRE. The GNSS module must end any active sessions, 181 * ensure that it will not invoke any callbacks past this point, and 182 * complete any relevant teardown activities before returning from this 183 * function. 184 */ 185 void (*close)(void); 186 187 /** 188 * Retrieves information about the features supported by this module. The 189 * value returned from this function must not change for the duration of 190 * execution. 191 * 192 * @return See chreGnssGetCapabilities() 193 * 194 * @see chreGnssGetCapabilities() 195 */ 196 uint32_t (*getCapabilities)(void); 197 198 /** 199 * Start/stop/modify the GNSS location session used for clients of the CHRE 200 * API. 201 * 202 * @param enable true to start/modify the session, false to stop the 203 * session. If false, other parameters are ignored. 204 * @param minIntervalMs See chreGnssLocationSessionStartAsync() 205 * @param minTimeToNextFixMs See chreGnssLocationSessionStartAsync() 206 * 207 * @return true if the request was accepted for further processing, in which 208 * case its result will be indicated via a call to the location 209 * session status change callback 210 * 211 * @see chreGnssLocationSessionStartAsync() 212 * @see chreGnssLocationSessionStopAsync() 213 */ 214 bool (*controlLocationSession)(bool enable, uint32_t minIntervalMs, 215 uint32_t minTimeToNextFixMs); 216 217 /** 218 * Invoked when the core CHRE system no longer needs a location event 219 * structure that was provided to it via locationEventCallback(). The GNSS 220 * module may use this to free associated memory, etc. 221 */ 222 void (*releaseLocationEvent)(struct chreGnssLocationEvent *event); 223 224 /** 225 * Start/stop/modify the raw GNSS measurement session used for clients of 226 * the CHRE API. 227 * 228 * @param enable true to start/modify the session, false to stop the 229 * session. If false, other parameters are ignored. 230 * @param minIntervalMs See chreGnssMeasurementSessionStartAsync() 231 * 232 * @return true if the request was accepted for further processing, in which 233 * case its result will be indicated via a call to the measurement 234 * session status change callback. 235 * 236 * @see chreGnssMeasurementSessionStartAsync() 237 * @see chreGnssMeasurementSessionStopAsync() 238 */ 239 bool (*controlMeasurementSession)(bool enable, uint32_t minIntervalMs); 240 241 /** 242 * Invoked when the core CHRE system no longer needs a raw measurement event 243 * structure that was provided to it via measurementEventCallback(). The 244 * GNSS module may use this to free associated memory, etc. 245 * 246 * @param event Event data to release 247 */ 248 void (*releaseMeasurementDataEvent)(struct chreGnssDataEvent *event); 249 250 /** 251 * Configures whether locationEventCallback() is used to opportunistically 252 * deliver any location fixes produced for other clients of the GNSS 253 * engine. For example, when the passive location listener is enabled, the 254 * PAL implementation will deliver location fixes computed as a result of 255 * requests from the applications processor. Note that this only controls 256 * receipt of location fixes that CHRE would not otherwise receive - it must 257 * not result in duplication of location events from an active location 258 * session initiated by controlLocationSession(). 259 * 260 * This feature is supported when the 261 * CHRE_GNSS_CAPABILITIES_GNSS_ENGINE_BASED_PASSIVE_LISTENER bit is returned 262 * in getCapabilities(). If not supported, this function must always return 263 * false. 264 * 265 * This configuration represents CHRE's interest in receiving all available 266 * GNSS fixes, independent of the state of CHRE's own location or 267 * measurement sessions as set by controlLocationSession() and 268 * controlMeasurementSession(), respectively. For example, toggling this 269 * setting on and off must not have any impact on the behavior of an ongoing 270 * location session. 271 * 272 * This setting must either persist across restarts of the GNSS engine, or 273 * the PAL must use the requestStateResync() callback to retrieve the 274 * current requested passive location listener state after the GNSS engine 275 * has recovered from a restart. 276 * 277 * @param enable true to turn the passive location listener on, false to 278 * turn it off 279 * 280 * @return true if the feature is supported and the request was received, 281 * false otherwise 282 * 283 * @since v1.2 284 */ 285 bool (*configurePassiveLocationListener)(bool enable); 286 }; 287 288 /** 289 * Retrieve a handle for the CHRE GNSS PAL. 290 * 291 * @param requestedApiVersion The implementation of this function must return a 292 * pointer to a structure with the same major version as requested. 293 * 294 * @return Pointer to API handle, or NULL if a compatible API version is not 295 * supported by the module, or the API as a whole is not implemented. If 296 * non-NULL, the returned API handle must be valid as long as this 297 * module is loaded. 298 */ 299 const struct chrePalGnssApi *chrePalGnssGetApi(uint32_t requestedApiVersion); 300 301 #ifdef __cplusplus 302 } 303 #endif 304 305 #endif // CHRE_PAL_GNSS_H_ 306
