pal/include/chre/pal/gnss.h - platform/system/chre - Git at Google

 /*
  * Copyright (C) 2016 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef CHRE_PAL_GNSS_H_
 #define CHRE_PAL_GNSS_H_

 /**
  * @file
  * Defines the interface between the common CHRE core system and the
  * platform-specific GNSS module. This API is largely asynchronous - any
  * implementation must be able to handle multiple outstanding requests to
  * asynchronous APIs such as controlLocationSession() under reasonable resource
  * constraints. Requests to the same API and their associated responses must be
  * handled strictly in-order. Refer to {@link #chreAsyncResult} for more
  * information.
  */

 #include <stdbool.h>
 #include <stdint.h>

 #include "chre/pal/system.h"
 #include "chre/pal/version.h"
 #include "chre_api/chre/common.h"
 #include "chre_api/chre/gnss.h"

 #ifdef __cplusplus
 extern "C" {
 #endif

 /**
  * Initial version of the CHRE GNSS PAL, tied to CHRE API v1.1.
  */
 #define CHRE_PAL_GNSS_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0)

 // v1.1 skipped to avoid confusion with CHRE API v1.1

 /**
  * Introduced alongside CHRE API v1.2, adding support for listening in on GNSS
  * fixes initiated by other clients of the GNSS engine via
  * configurePassiveLocationListener().
  */
 #define CHRE_PAL_GNSS_API_V1_2 CHRE_PAL_CREATE_API_VERSION(1, 2)

 /**
  * Introduced alongside CHRE API v1.3, adding support for altitude/speed/bearing
  * accuracy in chreGnssLocationEvent delivered by locationEventCallback.
  */
 #define CHRE_PAL_GNSS_API_V1_3 CHRE_PAL_CREATE_API_VERSION(1, 3)

 /**
  * Introduced alongside CHRE API v1.4, adding support for carrier frequency in
  * chreGnssMeasurement delivered by measurementStatusChangeCallback.
  */
 #define CHRE_PAL_GNSS_API_V1_4 CHRE_PAL_CREATE_API_VERSION(1, 4)

 /**
  * The version of the CHRE GNSS PAL defined in this header file.
  */
 #define CHRE_PAL_GNSS_API_CURRENT_VERSION CHRE_PAL_GNSS_API_V1_4

 struct chrePalGnssCallbacks {
   /**
    * This function can be used by the PAL module to request that the core CHRE
    * system re-send requests for any active sessions and its current passive
    * location listener setting. For example, if the GNSS subsystem has
    * recovered from a system crash, this function can be used to silently
    * (from the client's perspective) restore open sessions.
    */
   void (*requestStateResync)(void);

   /**
    * Callback invoked to inform the CHRE of the result of changes to the
    * location session status requested via controlLocationSession in struct
    * chrePalGnssApi.
    *
    * Unsolicited calls to this function must not be made. In other words,
    * this callback should only be invoked as the direct result of an earlier
    * call to controlLocationSession. If the location session is terminated on
    * the remote end, then requestStateResync() should be used if it is due to
    * a recoverable condition, otherwise the PAL should leave the location
    * session in the "enabled" state even though it does not expect to deliver
    * new location events.
    *
    * @param enabled true if the location session is currently active, false
    *        otherwise
    * @param errorCode An error code from enum chreError
    *
    * @see chrePalGnssApi.controlLocationSession
    * @see #chreError
    */
   void (*locationStatusChangeCallback)(bool enabled, uint8_t errorCode);

   /**
    * Callback used to pass GNSS location fixes to the core CHRE system, which
    * distributes it to clients (nanoapps). These events are only delivered
    * while a location session is active, i.e. locationStatusChangeCallback was
    * previously invoked with enabled=true.
    *
    * This function call passes ownership of the event memory to the core CHRE
    * system, i.e. the PAL module must not modify the referenced data until the
    * associated API function is called to release the memory.
    *
    * @param event Event data to distribute to clients. The GNSS module
    *        must ensure that this memory remains accessible until it is passed
    *        to the releaseLocationEvent function in struct chrePalGnssApi.
    */
   void (*locationEventCallback)(struct chreGnssLocationEvent *event);

   /**
    * Callback invoked to inform the CHRE of the result of changes to the raw
    * GNSS measurement session status requested via controlMeasurementSession
    * in struct chrePalGnssApi.
    *
    * Unsolicited calls to this function must not be made. See
    * locationStatusChangeCallback() for more information.
    *
    * @param enabled true if the measurement session is currently active, false
    *        otherwise
    * @param errorCode An error code from enum chreError
    */
   void (*measurementStatusChangeCallback)(bool enabled, uint8_t errorCode);

   /**
    * Callback used to pass raw GNSS measurement data from the GNSS module to
    * the core CHRE system, which distributes it to clients (nanoapps).
    *
    * This function call passes ownership of the event memory to the core CHRE
    * system, i.e. the PAL module must not modify the referenced data until the
    * associated API function is called to release the memory.
    *
    * @param event Event data to distribute to clients. The GNSS module
    *        must ensure that this memory remains accessible until it is passed
    *        to the releaseMeasurementDataEvent() function in struct
    *        chrePalGnssApi.
    */
   void (*measurementEventCallback)(struct chreGnssDataEvent *event);
 };

 struct chrePalGnssApi {
   /**
    * Version of the module providing this API. This value should be
    * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported
    * API version constant (CHRE_PAL_GNSS_API_*) and the module-specific patch
    * version.
    */
   uint32_t moduleVersion;

   /**
    * Initializes the GNSS module. Initialization must complete synchronously.
    *
    * @param systemApi Structure containing CHRE system function pointers which
    *        the PAL implementation should prefer to use over equivalent
    *        functionality exposed by the underlying platform. The module does
    *        not need to deep-copy this structure; its memory remains
    *        accessible at least until after close() is called.
    * @param callbacks Structure containing entry points to the core CHRE
    *        system. The module does not need to deep-copy this structure; its
    *        memory remains accessible at least until after close() is called.
    *
    * @return true if initialization was successful, false otherwise
    */
   bool (*open)(const struct chrePalSystemApi *systemApi,
                const struct chrePalGnssCallbacks *callbacks);

   /**
    * Performs clean shutdown of the GNSS module, usually done in preparation
    * for stopping the CHRE. The GNSS module must end any active sessions,
    * ensure that it will not invoke any callbacks past this point, and
    * complete any relevant teardown activities before returning from this
    * function.
    */
   void (*close)(void);

   /**
    * Retrieves information about the features supported by this module. The
    * value returned from this function must not change for the duration of
    * execution.
    *
    * @return See chreGnssGetCapabilities()
    *
    * @see chreGnssGetCapabilities()
    */
   uint32_t (*getCapabilities)(void);

   /**
    * Start/stop/modify the GNSS location session used for clients of the CHRE
    * API.
    *
    * @param enable true to start/modify the session, false to stop the
    *        session. If false, other parameters are ignored.
    * @param minIntervalMs See chreGnssLocationSessionStartAsync()
    * @param minTimeToNextFixMs See chreGnssLocationSessionStartAsync()
    *
    * @return true if the request was accepted for further processing, in which
    *         case its result will be indicated via a call to the location
    *         session status change callback
    *
    * @see chreGnssLocationSessionStartAsync()
    * @see chreGnssLocationSessionStopAsync()
    */
   bool (*controlLocationSession)(bool enable, uint32_t minIntervalMs,
                                  uint32_t minTimeToNextFixMs);

   /**
    * Invoked when the core CHRE system no longer needs a location event
    * structure that was provided to it via locationEventCallback(). The GNSS
    * module may use this to free associated memory, etc.
    */
   void (*releaseLocationEvent)(struct chreGnssLocationEvent *event);

   /**
    * Start/stop/modify the raw GNSS measurement session used for clients of
    * the CHRE API.
    *
    * @param enable true to start/modify the session, false to stop the
    *        session. If false, other parameters are ignored.
    * @param minIntervalMs See chreGnssMeasurementSessionStartAsync()
    *
    * @return true if the request was accepted for further processing, in which
    *         case its result will be indicated via a call to the measurement
    *         session status change callback.
    *
    * @see chreGnssMeasurementSessionStartAsync()
    * @see chreGnssMeasurementSessionStopAsync()
    */
   bool (*controlMeasurementSession)(bool enable, uint32_t minIntervalMs);

   /**
    * Invoked when the core CHRE system no longer needs a raw measurement event
    * structure that was provided to it via measurementEventCallback(). The
    * GNSS module may use this to free associated memory, etc.
    *
    * @param event Event data to release
    */
   void (*releaseMeasurementDataEvent)(struct chreGnssDataEvent *event);

   /**
    * Configures whether locationEventCallback() is used to opportunistically
    * deliver any location fixes produced for other clients of the GNSS
    * engine. For example, when the passive location listener is enabled, the
    * PAL implementation will deliver location fixes computed as a result of
    * requests from the applications processor. Note that this only controls
    * receipt of location fixes that CHRE would not otherwise receive - it must
    * not result in duplication of location events from an active location
    * session initiated by controlLocationSession().
    *
    * This feature is supported when the
    * CHRE_GNSS_CAPABILITIES_GNSS_ENGINE_BASED_PASSIVE_LISTENER bit is returned
    * in getCapabilities(). If not supported, this function must always return
    * false.
    *
    * This configuration represents CHRE's interest in receiving all available
    * GNSS fixes, independent of the state of CHRE's own location or
    * measurement sessions as set by controlLocationSession() and
    * controlMeasurementSession(), respectively. For example, toggling this
    * setting on and off must not have any impact on the behavior of an ongoing
    * location session.
    *
    * This setting must either persist across restarts of the GNSS engine, or
    * the PAL must use the requestStateResync() callback to retrieve the
    * current requested passive location listener state after the GNSS engine
    * has recovered from a restart.
    *
    * @param enable true to turn the passive location listener on, false to
    *        turn it off
    *
    * @return true if the feature is supported and the request was received,
    *         false otherwise
    *
    * @since v1.2
    */
   bool (*configurePassiveLocationListener)(bool enable);
 };

 /**
  * Retrieve a handle for the CHRE GNSS PAL.
  *
  * @param requestedApiVersion The implementation of this function must return a
  *        pointer to a structure with the same major version as requested.
  *
  * @return Pointer to API handle, or NULL if a compatible API version is not
  *         supported by the module, or the API as a whole is not implemented. If
  *         non-NULL, the returned API handle must be valid as long as this
  *         module is loaded.
  */
 const struct chrePalGnssApi *chrePalGnssGetApi(uint32_t requestedApiVersion);

 #ifdef __cplusplus
 }
 #endif

 #endif  // CHRE_PAL_GNSS_H_
	/*
	* Copyright (C) 2016 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef CHRE_PAL_GNSS_H_
	#define CHRE_PAL_GNSS_H_

	/**
	* @file
	* Defines the interface between the common CHRE core system and the
	* platform-specific GNSS module. This API is largely asynchronous - any
	* implementation must be able to handle multiple outstanding requests to
	* asynchronous APIs such as controlLocationSession() under reasonable resource
	* constraints. Requests to the same API and their associated responses must be
	* handled strictly in-order. Refer to {@link #chreAsyncResult} for more
	* information.
	*/

	#include <stdbool.h>
	#include <stdint.h>

	#include "chre/pal/system.h"
	#include "chre/pal/version.h"
	#include "chre_api/chre/common.h"
	#include "chre_api/chre/gnss.h"

	#ifdef __cplusplus
	extern "C" {
	#endif

	/**
	* Initial version of the CHRE GNSS PAL, tied to CHRE API v1.1.
	*/
	#define CHRE_PAL_GNSS_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0)

	// v1.1 skipped to avoid confusion with CHRE API v1.1

	/**
	* Introduced alongside CHRE API v1.2, adding support for listening in on GNSS
	* fixes initiated by other clients of the GNSS engine via
	* configurePassiveLocationListener().
	*/
	#define CHRE_PAL_GNSS_API_V1_2 CHRE_PAL_CREATE_API_VERSION(1, 2)

	/**
	* Introduced alongside CHRE API v1.3, adding support for altitude/speed/bearing
	* accuracy in chreGnssLocationEvent delivered by locationEventCallback.
	*/
	#define CHRE_PAL_GNSS_API_V1_3 CHRE_PAL_CREATE_API_VERSION(1, 3)

	/**
	* Introduced alongside CHRE API v1.4, adding support for carrier frequency in
	* chreGnssMeasurement delivered by measurementStatusChangeCallback.
	*/
	#define CHRE_PAL_GNSS_API_V1_4 CHRE_PAL_CREATE_API_VERSION(1, 4)

	/**
	* The version of the CHRE GNSS PAL defined in this header file.
	*/
	#define CHRE_PAL_GNSS_API_CURRENT_VERSION CHRE_PAL_GNSS_API_V1_4

	struct chrePalGnssCallbacks {
	/**
	* This function can be used by the PAL module to request that the core CHRE
	* system re-send requests for any active sessions and its current passive
	* location listener setting. For example, if the GNSS subsystem has
	* recovered from a system crash, this function can be used to silently
	* (from the client's perspective) restore open sessions.
	*/
	void (*requestStateResync)(void);

	/**
	* Callback invoked to inform the CHRE of the result of changes to the
	* location session status requested via controlLocationSession in struct
	* chrePalGnssApi.
	*
	* Unsolicited calls to this function must not be made. In other words,
	* this callback should only be invoked as the direct result of an earlier
	* call to controlLocationSession. If the location session is terminated on
	* the remote end, then requestStateResync() should be used if it is due to
	* a recoverable condition, otherwise the PAL should leave the location
	* session in the "enabled" state even though it does not expect to deliver
	* new location events.
	*
	* @param enabled true if the location session is currently active, false
	* otherwise
	* @param errorCode An error code from enum chreError
	*
	* @see chrePalGnssApi.controlLocationSession
	* @see #chreError
	*/
	void (*locationStatusChangeCallback)(bool enabled, uint8_t errorCode);

	/**
	* Callback used to pass GNSS location fixes to the core CHRE system, which
	* distributes it to clients (nanoapps). These events are only delivered
	* while a location session is active, i.e. locationStatusChangeCallback was
	* previously invoked with enabled=true.
	*
	* This function call passes ownership of the event memory to the core CHRE
	* system, i.e. the PAL module must not modify the referenced data until the
	* associated API function is called to release the memory.
	*
	* @param event Event data to distribute to clients. The GNSS module
	* must ensure that this memory remains accessible until it is passed
	* to the releaseLocationEvent function in struct chrePalGnssApi.
	*/
	void (locationEventCallback)(struct chreGnssLocationEvent event);

	/**
	* Callback invoked to inform the CHRE of the result of changes to the raw
	* GNSS measurement session status requested via controlMeasurementSession
	* in struct chrePalGnssApi.
	*
	* Unsolicited calls to this function must not be made. See
	* locationStatusChangeCallback() for more information.
	*
	* @param enabled true if the measurement session is currently active, false
	* otherwise
	* @param errorCode An error code from enum chreError
	*/
	void (*measurementStatusChangeCallback)(bool enabled, uint8_t errorCode);

	/**
	* Callback used to pass raw GNSS measurement data from the GNSS module to
	* the core CHRE system, which distributes it to clients (nanoapps).
	*
	* This function call passes ownership of the event memory to the core CHRE
	* system, i.e. the PAL module must not modify the referenced data until the
	* associated API function is called to release the memory.
	*
	* @param event Event data to distribute to clients. The GNSS module
	* must ensure that this memory remains accessible until it is passed
	* to the releaseMeasurementDataEvent() function in struct
	* chrePalGnssApi.
	*/
	void (measurementEventCallback)(struct chreGnssDataEvent event);
	};

	struct chrePalGnssApi {
	/**
	* Version of the module providing this API. This value should be
	* constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported
	* API version constant (CHRE_PAL_GNSS_API_*) and the module-specific patch
	* version.
	*/
	uint32_t moduleVersion;

	/**
	* Initializes the GNSS module. Initialization must complete synchronously.
	*
	* @param systemApi Structure containing CHRE system function pointers which
	* the PAL implementation should prefer to use over equivalent
	* functionality exposed by the underlying platform. The module does
	* not need to deep-copy this structure; its memory remains
	* accessible at least until after close() is called.
	* @param callbacks Structure containing entry points to the core CHRE
	* system. The module does not need to deep-copy this structure; its
	* memory remains accessible at least until after close() is called.
	*
	* @return true if initialization was successful, false otherwise
	*/
	bool (open)(const struct chrePalSystemApi systemApi,
	const struct chrePalGnssCallbacks *callbacks);

	/**
	* Performs clean shutdown of the GNSS module, usually done in preparation
	* for stopping the CHRE. The GNSS module must end any active sessions,
	* ensure that it will not invoke any callbacks past this point, and
	* complete any relevant teardown activities before returning from this
	* function.
	*/
	void (*close)(void);

	/**
	* Retrieves information about the features supported by this module. The
	* value returned from this function must not change for the duration of
	* execution.
	*
	* @return See chreGnssGetCapabilities()
	*
	* @see chreGnssGetCapabilities()
	*/
	uint32_t (*getCapabilities)(void);

	/**
	* Start/stop/modify the GNSS location session used for clients of the CHRE
	* API.
	*
	* @param enable true to start/modify the session, false to stop the
	* session. If false, other parameters are ignored.
	* @param minIntervalMs See chreGnssLocationSessionStartAsync()
	* @param minTimeToNextFixMs See chreGnssLocationSessionStartAsync()
	*
	* @return true if the request was accepted for further processing, in which
	* case its result will be indicated via a call to the location
	* session status change callback
	*
	* @see chreGnssLocationSessionStartAsync()
	* @see chreGnssLocationSessionStopAsync()
	*/
	bool (*controlLocationSession)(bool enable, uint32_t minIntervalMs,
	uint32_t minTimeToNextFixMs);

	/**
	* Invoked when the core CHRE system no longer needs a location event
	* structure that was provided to it via locationEventCallback(). The GNSS
	* module may use this to free associated memory, etc.
	*/
	void (releaseLocationEvent)(struct chreGnssLocationEvent event);

	/**
	* Start/stop/modify the raw GNSS measurement session used for clients of
	* the CHRE API.
	*
	* @param enable true to start/modify the session, false to stop the
	* session. If false, other parameters are ignored.
	* @param minIntervalMs See chreGnssMeasurementSessionStartAsync()
	*
	* @return true if the request was accepted for further processing, in which
	* case its result will be indicated via a call to the measurement
	* session status change callback.
	*
	* @see chreGnssMeasurementSessionStartAsync()
	* @see chreGnssMeasurementSessionStopAsync()
	*/
	bool (*controlMeasurementSession)(bool enable, uint32_t minIntervalMs);

	/**
	* Invoked when the core CHRE system no longer needs a raw measurement event
	* structure that was provided to it via measurementEventCallback(). The
	* GNSS module may use this to free associated memory, etc.
	*
	* @param event Event data to release
	*/
	void (releaseMeasurementDataEvent)(struct chreGnssDataEvent event);

	/**
	* Configures whether locationEventCallback() is used to opportunistically
	* deliver any location fixes produced for other clients of the GNSS
	* engine. For example, when the passive location listener is enabled, the
	* PAL implementation will deliver location fixes computed as a result of
	* requests from the applications processor. Note that this only controls
	* receipt of location fixes that CHRE would not otherwise receive - it must
	* not result in duplication of location events from an active location
	* session initiated by controlLocationSession().
	*
	* This feature is supported when the
	* CHRE_GNSS_CAPABILITIES_GNSS_ENGINE_BASED_PASSIVE_LISTENER bit is returned
	* in getCapabilities(). If not supported, this function must always return
	* false.
	*
	* This configuration represents CHRE's interest in receiving all available
	* GNSS fixes, independent of the state of CHRE's own location or
	* measurement sessions as set by controlLocationSession() and
	* controlMeasurementSession(), respectively. For example, toggling this
	* setting on and off must not have any impact on the behavior of an ongoing
	* location session.
	*
	* This setting must either persist across restarts of the GNSS engine, or
	* the PAL must use the requestStateResync() callback to retrieve the
	* current requested passive location listener state after the GNSS engine
	* has recovered from a restart.
	*
	* @param enable true to turn the passive location listener on, false to
	* turn it off
	*
	* @return true if the feature is supported and the request was received,
	* false otherwise
	*
	* @since v1.2
	*/
	bool (*configurePassiveLocationListener)(bool enable);
	};

	/**
	* Retrieve a handle for the CHRE GNSS PAL.
	*
	* @param requestedApiVersion The implementation of this function must return a
	* pointer to a structure with the same major version as requested.
	*
	* @return Pointer to API handle, or NULL if a compatible API version is not
	* supported by the module, or the API as a whole is not implemented. If
	* non-NULL, the returned API handle must be valid as long as this
	* module is loaded.
	*/
	const struct chrePalGnssApi *chrePalGnssGetApi(uint32_t requestedApiVersion);

	#ifdef __cplusplus
	}
	#endif

	#endif // CHRE_PAL_GNSS_H_