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_api/chre/common.h" 35 #include "chre_api/chre/gnss.h" 36 #include "chre/pal/system.h" 37 #include "chre/pal/version.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 /** 49 * The version of the CHRE GNSS PAL defined in this header file. 50 */ 51 #define CHRE_PAL_GNSS_API_CURRENT_VERSION CHRE_PAL_GNSS_API_V1_0 52 53 struct chrePalGnssCallbacks { 54 /** 55 * This function can be used by the PAL module to request that the core CHRE 56 * system re-send requests for any active sessions. For example, if the GNSS 57 * subsystem has recovered from a system crash, this function can be used to 58 * silently (from the client's perspective) restore open sessions. 59 */ 60 void (*requestStateResync)(void); 61 62 /** 63 * Callback invoked to inform the CHRE of the result of changes to the 64 * location session status requested via controlLocationSession in struct 65 * chrePalGnssApi. 66 * 67 * Unsolicited calls to this function must not be made. In other words, 68 * this callback should only be invoked as the direct result of an earlier 69 * call to controlLocationSession. If the location session is terminated on 70 * the remote end, then requestStateResync() should be used if it is due to 71 * a recoverable condition, otherwise the PAL should leave the location 72 * session in the "enabled" state even though it does not expect to deliver 73 * new location events. 74 * 75 * @param enabled true if the location session is currently active, false 76 * otherwise 77 * @param errorCode An error code from enum chreError 78 * 79 * @see #controlLocationSession 80 * @see #chreError 81 */ 82 void (*locationStatusChangeCallback)(bool enabled, uint8_t errorCode); 83 84 /** 85 * Callback used to pass GNSS location fixes to the core CHRE system, which 86 * distributes it to clients (nanoapps). These events are only delivered 87 * while a location session is active, i.e. locationStatusChangeCallback was 88 * previously invoked with enabled=true. 89 * 90 * This function call passes ownership of the event memory to the core CHRE 91 * system, i.e. the PAL module must not modify the referenced data until the 92 * associated API function is called to release the memory. 93 * 94 * @param event Event data to distribute to clients. The GNSS module 95 * must ensure that this memory remains accessible until it is passed 96 * to the releaseLocationEvent function in struct chrePalGnssApi. 97 */ 98 void (*locationEventCallback)(struct chreGnssLocationEvent *event); 99 100 /** 101 * Callback invoked to inform the CHRE of the result of changes to the raw 102 * GNSS measurement session status requested via controlMeasurementSession 103 * in struct chrePalGnssApi. 104 * 105 * Unsolicited calls to this function must not be made. See 106 * locationStatusChangeCallback() for more information. 107 * 108 * @param enabled true if the measurement session is currently active, false 109 * otherwise 110 * @param errorCode An error code from enum chreError 111 */ 112 void (*measurementStatusChangeCallback)(bool enabled, uint8_t errorCode); 113 114 /** 115 * Callback used to pass raw GNSS measurement data from the GNSS module to 116 * the core CHRE system, which distributes it to clients (nanoapps). 117 * 118 * This function call passes ownership of the event memory to the core CHRE 119 * system, i.e. the PAL module must not modify the referenced data until the 120 * associated API function is called to release the memory. 121 * 122 * @param event Event data to distribute to clients. The GNSS module 123 * must ensure that this memory remains accessible until it is passed 124 * to the releaseMeasurementDataEvent() function in struct 125 * chrePalGnssApi. 126 */ 127 void (*measurementEventCallback)(struct chreGnssDataEvent *event); 128 }; 129 130 struct chrePalGnssApi { 131 /** 132 * Version of the module providing this API. This value should be 133 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 134 * API version constant (CHRE_PAL_GNSS_API_*) and the module-specific patch 135 * version. 136 */ 137 uint32_t moduleVersion; 138 139 /** 140 * Initializes the GNSS module. Initialization must complete synchronously. 141 * 142 * @param systemApi Structure containing CHRE system function pointers which 143 * the PAL implementation should prefer to use over equivalent 144 * functionality exposed by the underlying platform. The module does 145 * not need to deep-copy this structure; its memory remains 146 * accessible at least until after close() is called. 147 * @param callbacks Structure containing entry points to the core CHRE 148 * system. The module does not need to deep-copy this structure; its 149 * memory remains accessible at least until after close() is called. 150 * 151 * @return true if initialization was successful, false otherwise 152 */ 153 bool (*open)(const struct chrePalSystemApi *systemApi, 154 const struct chrePalGnssCallbacks *callbacks); 155 156 /** 157 * Performs clean shutdown of the GNSS module, usually done in preparation 158 * for stopping the CHRE. The GNSS module must end any active sessions, 159 * ensure that it will not invoke any callbacks past this point, and 160 * complete any relevant teardown activities before returning from this 161 * function. 162 */ 163 void (*close)(void); 164 165 /** 166 * Retrieves information about the features supported by this module. The 167 * value returned from this function must not change for the duration of 168 * execution. 169 * 170 * @return See chreGnssGetCapabilities() 171 * 172 * @see chreGnssGetCapabilities() 173 */ 174 uint32_t (*getCapabilities)(void); 175 176 /** 177 * Start/stop/modify the GNSS location session used for clients of the CHRE 178 * API. 179 * 180 * @param enable true to start/modify the session, false to stop the 181 * session. If false, other parameters are ignored. 182 * @param minIntervalMs See chreGnssLocationSessionStartAsync() 183 * @param minTimeToNextFixMs See chreGnssLocationSessionStartAsync() 184 * 185 * @return true if the request was accepted for further processing, in which 186 * case its result will be indicated via a call to the location 187 * session status change callback 188 * 189 * @see chreGnssLocationSessionStartAsync() 190 * @see chreGnssLocationSessionStopAsync() 191 */ 192 bool (*controlLocationSession)( 193 bool enable, uint32_t minIntervalMs, uint32_t minTimeToNextFixMs); 194 195 /** 196 * Invoked when the core CHRE system no longer needs a location event 197 * structure that was provided to it via locationEventCallback(). The GNSS 198 * module may use this to free associated memory, etc. 199 */ 200 void (*releaseLocationEvent)(struct chreGnssLocationEvent *event); 201 202 /** 203 * Start/stop/modify the raw GNSS measurement session used for clients of 204 * the CHRE API. 205 * 206 * @param enable true to start/modify the session, false to stop the 207 * session. If false, other parameters are ignored. 208 * @param minIntervalMs See chreGnssMeasurementSessionStartAsync() 209 * 210 * @return true if the request was accepted for further processing, in which 211 * case its result will be indicated via a call to the measurement 212 * session status change callback. 213 * 214 * @see chreGnssMeasurementSessionStartAsync() 215 * @see chreGnssMeasurementSessionStopAsync() 216 */ 217 bool (*controlMeasurementSession)( 218 bool enable, uint32_t minIntervalMs); 219 220 /** 221 * Invoked when the core CHRE system no longer needs a raw measurement event 222 * structure that was provided to it via measurementEventCallback(). The 223 * GNSS module may use this to free associated memory, etc. 224 * 225 * @param event Event data to release 226 */ 227 void (*releaseMeasurementDataEvent)(struct chreGnssDataEvent *event); 228 }; 229 230 /** 231 * Retrieve a handle for the CHRE GNSS PAL. 232 * 233 * @param requestedApiVersion The implementation of this function must return a 234 * pointer to a structure with the same major version as requested. 235 * 236 * @return Pointer to API handle, or NULL if a compatible API version is not 237 * supported by the module, or the API as a whole is not implemented. If 238 * non-NULL, the returned API handle must be valid as long as this 239 * module is loaded. 240 */ 241 const struct chrePalGnssApi *chrePalGnssGetApi(uint32_t requestedApiVersion); 242 243 #ifdef __cplusplus 244 } 245 #endif 246 247 #endif // CHRE_PAL_GNSS_H_ 248