ash/include/ash_api/ash.h - platform/system/chre - Git at Google

 /*
  * Copyright (C) 2017 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 ASH_H_
 #define ASH_H_

 /**
  * @file
  * Defines the interface for the Android Sensor Hub support.
  * These APIs are only accessible to system nanoapps and allow them to interact
  * with the underlying sensor framework.
  * These APIs are not part of the CHRE API and their support is optional.
  */

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

 #ifdef __cplusplus
 extern "C" {
 #endif

 /**
  * The values returned by this sensor cannot be trusted, calibration is needed
  * or the environment doesn't allow readings.
  */
 #define ASH_CAL_ACCURACY_UNRELIABLE UINT8_C(0)

 /**
  * This sensor is reporting data with low accuracy, calibration with the
  * environment is needed.
  */
 #define ASH_CAL_ACCURACY_LOW UINT8_C(1)

 /**
  * This sensor is reporting data with an average level of accuracy, calibration
  * with the environment may improve the readings.
  */
 #define ASH_CAL_ACCURACY_MEDIUM UINT8_C(2)

 /**
  * This sensor is reporting data with maximum accuracy.
  */
 #define ASH_CAL_ACCURACY_HIGH UINT8_C(3)

 /**
  * Calibration info for a sensor which reports on a maximum of three axes.
  *
  * Let Su be the uncalibrated sensor data and Sc the calibrated one,
  * Sc = compMatrix * (Su - bias)
  *
  */
 struct ashCalInfo {
   /**
    * The zero-bias vector in the x, y, z order. If the sensor reports on N
    * axes with N < 3, only the first N elements are considered valid.
    */
   float bias[3];

   /**
    * The compensation matrix in the row major order. If the sensor reports on N
    * axes with N < 3, only the first N elements of each row are considered
    * valid.
    */
   float compMatrix[9];

   /**
    * One of the ASH_CAL_ACCURACY_* constants. This corresponds to the
    * definition in the Android SensorManager. See
    * https://developer.android.com/reference/android/hardware/SensorEvent.html#accuracy
    * for more details.
    * Note that this accuracy field is simply a suggestion to the platform and
    * the platform can ignore or over-write it.
    */
   uint8_t accuracy;
 };

 //! This is used to indicate the persistent storage of the ASH implementaion.
 #define ASH_CAL_STORAGE_ASH UINT8_C(0)

 //! This is used to indicate the persistent storage in the sensor registry.
 #define ASH_CAL_STORAGE_SNS UINT8_C(1)

 //! Interval between cal params storage when AP is up, in usec.
 #define ASH_CAL_SAVE_INTERVAL_USEC UINT64_C(300000000)

 //! This is used to indicate that the cal params are invalid.
 #define ASH_CAL_PARAMS_SOURCE_NONE    UINT8_C(0)

 //! This is used to indicate that the cal params were set by factory
 //! calibration.
 #define ASH_CAL_PARAMS_SOURCE_FACTORY UINT8_C(1)

 //! This is used to indicate that the cal params were set by runtime
 //! calibration.
 #define ASH_CAL_PARAMS_SOURCE_RUNTIME UINT8_C(2)

 /**
  * A struct for calibration parameters to be saved to and loaded from a
  * persistent area. The source of each section is indicated by the
  * corresponding *Source field, which is one of the ASH_CAL_PARAMS_SOURCE_*
  * constants.
  */
 struct ashCalParams {
   //! The offset of the sensor in the x, y and z axis at temperature
   //! offsetTempCelsius.
   float offset[3];

   //! The temperature at which last offset was updated.
   float offsetTempCelsius;

   //! The temperature sensitivity of offset.
   float tempSensitivity[3];

   //! The estimated offset at zero degree Celsius.
   float tempIntercept[3];

   //! The scale factor of the x, y and z axis.
   float scaleFactor[3];

   //! The cross-axis factor in the [yx, zx, zy] order.
   float crossAxis[3];

   //! The source of offset[3]
   uint8_t offsetSource;

   //! The source of offsetTempCelsius
   uint8_t offsetTempCelsiusSource;

   //! The source of tempSensitivity[3]
   uint8_t tempSensitivitySource;

   //! The source of tempIntercept[3]
   uint8_t tempInterceptSource;

   uint8_t scaleFactorSource;

   //! The source of crossAxis[3]
   uint8_t crossAxisSource;
 };

 /**
  * Updates the runtime calibration info of a given sensor type for the platform
  * to compensate for. The calibration will be applied on top of the sensor's
  * factory calibration if present.
  *
  * @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
  * @param calInfo A non-null pointer to ashCalInfo to update the sensor's
           calibration.
  * @return true if the calibration info has been successfully updated.
  */
 bool ashSetCalibration(uint8_t sensorType, const struct ashCalInfo *calInfo);

 /**
  * Loads the stored cal params from the specified storage area.
  *
  * If ASH_CAL_STORAGE_SNS is specified as the storage area, it reads from the
  * sensor registry with factory cal params. This should only be used for
  * debugging as it can wake up the AP.
  *
  * If ASH_CAL_STORAGE_ASH is specified as the storage area, the stored cal
  * params in the ASH storage are provided if they exist. Otherwise, the sensor
  * registry cal params are provided instead.
  *
  * @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
  * @param storage Either ASH_CAL_STORAGE_ASH or ASH_CAL_STORAGE_SNS.
  * @param params A non-null pointer to a ashCalParams that the cal params will
  *               be populated to.
  *
  * @return true if the cal params have been successfully populated to the
  *              provided memory.
  */
 bool ashLoadCalibrationParams(uint8_t sensorType, uint8_t storage,
                               struct ashCalParams *params);

 /**
  * Saves the cal params to a local cache, and saves to ASH's persistent storage
  * area when the AP wakes up, or when the AP is up and it has been
  * ASH_CAL_SAVE_INTERVAL_USEC since the cal params were last saved to the ASH
  * storage.
  *
  * @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
  * @param params A non-null pointer to a ashCalParams to be saved to the local
  *               cache.
  *
  * @return true if the cal params have been successfully saved to the local
  *              cache.
  */
 bool ashSaveCalibrationParams(uint8_t sensorType,
                               const struct ashCalParams *params);

 #ifdef __cplusplus
 }
 #endif

 #endif  // ASH_H_
	/*
	* Copyright (C) 2017 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 ASH_H_
	#define ASH_H_

	/**
	* @file
	* Defines the interface for the Android Sensor Hub support.
	* These APIs are only accessible to system nanoapps and allow them to interact
	* with the underlying sensor framework.
	* These APIs are not part of the CHRE API and their support is optional.
	*/

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

	#ifdef __cplusplus
	extern "C" {
	#endif

	/**
	* The values returned by this sensor cannot be trusted, calibration is needed
	* or the environment doesn't allow readings.
	*/
	#define ASH_CAL_ACCURACY_UNRELIABLE UINT8_C(0)

	/**
	* This sensor is reporting data with low accuracy, calibration with the
	* environment is needed.
	*/
	#define ASH_CAL_ACCURACY_LOW UINT8_C(1)

	/**
	* This sensor is reporting data with an average level of accuracy, calibration
	* with the environment may improve the readings.
	*/
	#define ASH_CAL_ACCURACY_MEDIUM UINT8_C(2)

	/**
	* This sensor is reporting data with maximum accuracy.
	*/
	#define ASH_CAL_ACCURACY_HIGH UINT8_C(3)

	/**
	* Calibration info for a sensor which reports on a maximum of three axes.
	*
	* Let Su be the uncalibrated sensor data and Sc the calibrated one,
	* Sc = compMatrix * (Su - bias)
	*
	*/
	struct ashCalInfo {
	/**
	* The zero-bias vector in the x, y, z order. If the sensor reports on N
	* axes with N < 3, only the first N elements are considered valid.
	*/
	float bias[3];

	/**
	* The compensation matrix in the row major order. If the sensor reports on N
	* axes with N < 3, only the first N elements of each row are considered
	* valid.
	*/
	float compMatrix[9];

	/**
	* One of the ASH_CAL_ACCURACY_* constants. This corresponds to the
	* definition in the Android SensorManager. See
	* https://developer.android.com/reference/android/hardware/SensorEvent.html#accuracy
	* for more details.
	* Note that this accuracy field is simply a suggestion to the platform and
	* the platform can ignore or over-write it.
	*/
	uint8_t accuracy;
	};

	//! This is used to indicate the persistent storage of the ASH implementaion.
	#define ASH_CAL_STORAGE_ASH UINT8_C(0)

	//! This is used to indicate the persistent storage in the sensor registry.
	#define ASH_CAL_STORAGE_SNS UINT8_C(1)

	//! Interval between cal params storage when AP is up, in usec.
	#define ASH_CAL_SAVE_INTERVAL_USEC UINT64_C(300000000)

	//! This is used to indicate that the cal params are invalid.
	#define ASH_CAL_PARAMS_SOURCE_NONE UINT8_C(0)

	//! This is used to indicate that the cal params were set by factory
	//! calibration.
	#define ASH_CAL_PARAMS_SOURCE_FACTORY UINT8_C(1)

	//! This is used to indicate that the cal params were set by runtime
	//! calibration.
	#define ASH_CAL_PARAMS_SOURCE_RUNTIME UINT8_C(2)

	/**
	* A struct for calibration parameters to be saved to and loaded from a
	* persistent area. The source of each section is indicated by the
	* corresponding Source field, which is one of the ASH_CAL_PARAMS_SOURCE_
	* constants.
	*/
	struct ashCalParams {
	//! The offset of the sensor in the x, y and z axis at temperature
	//! offsetTempCelsius.
	float offset[3];

	//! The temperature at which last offset was updated.
	float offsetTempCelsius;

	//! The temperature sensitivity of offset.
	float tempSensitivity[3];

	//! The estimated offset at zero degree Celsius.
	float tempIntercept[3];

	//! The scale factor of the x, y and z axis.
	float scaleFactor[3];

	//! The cross-axis factor in the [yx, zx, zy] order.
	float crossAxis[3];

	//! The source of offset[3]
	uint8_t offsetSource;

	//! The source of offsetTempCelsius
	uint8_t offsetTempCelsiusSource;

	//! The source of tempSensitivity[3]
	uint8_t tempSensitivitySource;

	//! The source of tempIntercept[3]
	uint8_t tempInterceptSource;

	uint8_t scaleFactorSource;

	//! The source of crossAxis[3]
	uint8_t crossAxisSource;
	};

	/**
	* Updates the runtime calibration info of a given sensor type for the platform
	* to compensate for. The calibration will be applied on top of the sensor's
	* factory calibration if present.
	*
	* @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
	* @param calInfo A non-null pointer to ashCalInfo to update the sensor's
	calibration.
	* @return true if the calibration info has been successfully updated.
	*/
	bool ashSetCalibration(uint8_t sensorType, const struct ashCalInfo *calInfo);

	/**
	* Loads the stored cal params from the specified storage area.
	*
	* If ASH_CAL_STORAGE_SNS is specified as the storage area, it reads from the
	* sensor registry with factory cal params. This should only be used for
	* debugging as it can wake up the AP.
	*
	* If ASH_CAL_STORAGE_ASH is specified as the storage area, the stored cal
	* params in the ASH storage are provided if they exist. Otherwise, the sensor
	* registry cal params are provided instead.
	*
	* @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
	* @param storage Either ASH_CAL_STORAGE_ASH or ASH_CAL_STORAGE_SNS.
	* @param params A non-null pointer to a ashCalParams that the cal params will
	* be populated to.
	*
	* @return true if the cal params have been successfully populated to the
	* provided memory.
	*/
	bool ashLoadCalibrationParams(uint8_t sensorType, uint8_t storage,
	struct ashCalParams *params);

	/**
	* Saves the cal params to a local cache, and saves to ASH's persistent storage
	* area when the AP wakes up, or when the AP is up and it has been
	* ASH_CAL_SAVE_INTERVAL_USEC since the cal params were last saved to the ASH
	* storage.
	*
	* @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
	* @param params A non-null pointer to a ashCalParams to be saved to the local
	* cache.
	*
	* @return true if the cal params have been successfully saved to the local
	* cache.
	*/
	bool ashSaveCalibrationParams(uint8_t sensorType,
	const struct ashCalParams *params);

	#ifdef __cplusplus
	}
	#endif

	#endif // ASH_H_