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