Adds bias event types for uncalibrated sensors

Also clarifies default behaviors of bias APIs for calibrated sensors.

Bug: 119269599
Test: Compile only
Change-Id: I1d8b3b75eddab94ffdb8e8caf186da9deacc30f9

1 files changed, 92 insertions, 9 deletions

diff --git a/chre_api/include/chre_api/chre/sensor.h b/chre_api/include/chre_api/chre/sensor.h
index 6e418d2d..7985e9a9 100644
--- a/chre_api/include/chre_api/chre/sensor.h
+++ b/chre_api/include/chre_api/chre/sensor.h
@@ -237,10 +237,16 @@ extern "C" {
  *
  * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias'
  * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias;
- * bias[1] == y_bias; bias[2] == z_bias).
+ * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated
+ * data to generate calibrated data.
  *
  * All values are in radians/second and measure the rate of rotation
  * around the X, Y and Z axis.
+ *
+ * If bias delivery is supported, this event is generated by default when
+ * chreSensorConfigure is called to enable for the sensor of type
+ * CHRE_SENSOR_TYPE_GYROSCOPE, or if bias delivery is explicitly enabled
+ * through chreSensorConfigureBiasEvents() for the sensor.
  */
 #define CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO \
     (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 1)
@@ -250,10 +256,16 @@ extern "C" {
  *
  * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias'
  * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias;
- * bias[1] == y_bias; bias[2] == z_bias).
+ * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated
+ * data to generate calibrated data.
  *
  * All values are in micro-Tesla (uT) and measure the geomagnetic
  * field in the X, Y and Z axis.
+ *
+ * If bias delivery is supported, this event is generated by default when
+ * chreSensorConfigure is called to enable for the sensor of type
+ * CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD, or if bias delivery is explicitly enabled
+ * through chreSensorConfigureBiasEvents() for the sensor.
  */
 #define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO \
     (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 2)
@@ -263,11 +275,17 @@ extern "C" {
  *
  * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias'
  * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias;
- * bias[1] == y_bias; bias[2] == z_bias).
+ * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated
+ * data to generate calibrated data.
  *
  * All values are in SI units (m/s^2) and measure the acceleration applied to
  * the device.
  *
+ * If bias delivery is supported, this event is generated by default when
+ * chreSensorConfigure is called to enable for the sensor of type
+ * CHRE_SENSOR_TYPE_ACCELEROMETER, or if bias delivery is explicitly enabled
+ * through chreSensorConfigureBiasEvents() for the sensor.
+ *
  * @since v1.3
  */
 #define CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO \
@@ -286,11 +304,68 @@ extern "C" {
 #define CHRE_EVENT_SENSOR_FLUSH_COMPLETE \
     (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 4)
 
-#if CHRE_EVENT_SENSOR_FLUSH_COMPLETE > CHRE_EVENT_SENSOR_LAST_EVENT
+/**
+ * nanoappHandleEvent argument: struct chreSensorThreeAxisData
+ *
+ * The data of this event is the same as that of
+ * CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO, except the sensorHandle field of
+ * chreSensorDataHeader contains the handle of the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE.
+ *
+ * This event is only generated if the bias reporting is explicitly enabled
+ * for a nanoapp through chreSensorConfigureBiasEvents() for the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE.
+ *
+ * @see CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO
+ *
+ * @since v1.3
+ */
+#define CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_BIAS_INFO \
+    (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 5)
+
+/**
+ * nanoappHandleEvent argument: struct chreSensorThreeAxisData
+ *
+ * The data of this event is the same as that of
+ * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO, except the sensorHandle field
+ * of chreSensorDataHeader contains the handle of the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD.
+ *
+ * This event is only generated if the bias reporting is explicitly enabled
+ * for a nanoapp through chreSensorConfigureBiasEvents() for the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD.
+ *
+ * @see CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO
+ *
+ * @since v1.3
+ */
+#define CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_BIAS_INFO \
+    (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 6)
+
+/**
+ * nanoappHandleEvent argument: struct chreSensorThreeAxisData
+ *
+ * The data of this event is the same as that of
+ * CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO, except the sensorHandle field
+ * of chreSensorDataHeader contains the handle of the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER.
+ *
+ * This event is only generated if the bias reporting is explicitly enabled
+ * for a nanoapp through chreSensorConfigureBiasEvents for the sensor of type
+ * CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER.
+ *
+ * @see CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO
+ *
+ * @since v1.3
+ */
+#define CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_BIAS_INFO \
+    (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 7)
+
+#if CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_BIAS_INFO > \
+    CHRE_EVENT_SENSOR_LAST_EVENT
 #error Too many sensor events.
 #endif
 
-
 /**
  * Value indicating we want the smallest possible latency for a sensor.
  *
@@ -681,6 +756,13 @@ bool chreGetSensorSamplingStatus(uint32_t sensorHandle,
  * an interest in powering the sensor, DONE is still necessary
  * to silence the event reporting.
  *
+ * When a calibrated sensor (e.g. CHRE_SENSOR_TYPE_ACCELEROMETER) is
+ * successfully enabled through this method and if bias delivery is supported,
+ * by default CHRE will start delivering bias events for the sensor
+ * (e.g. CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO) to the nanoapp. If the
+ * nanoapp does not wish to receive these events, they can be disabled through
+ * chreSensorConfigureBiasEvents after enabling the sensor.
+ *
  * @param sensorHandle  The handle to the sensor, as obtained from
  *     chreSensorFindDefault().
  * @param mode  The mode to use.  See descriptions within the
@@ -711,6 +793,7 @@ bool chreGetSensorSamplingStatus(uint32_t sensorHandle,
  * @see chreSensorConfigureMode
  * @see chreSensorFindDefault
  * @see chreSensorInfo
+ * @see chreSensorConfigureBiasEvents
  */
 bool chreSensorConfigure(uint32_t sensorHandle,
                          enum chreSensorConfigureMode mode,
@@ -794,10 +877,10 @@ static inline bool chreSensorConfigureWithBatchInterval(
  * provide bias events to the nanoapp by default when chreSensorConfigure is
  * called to enable the calibrated version of the sensor (for backwards
  * compatibility reasons, as this is the defined behavior for CHRE API v1.0).
- * For uncalibrated sensors, nanoapps must explicitly configure an enable
- * request through this method to receive bias events. If bias event delivery is
- * not supported for the sensor, this method will return false and no bias
- * events will be generated.
+ * When configuring uncalibrated sensors, nanoapps must explicitly configure an
+ * enable request through this method to receive bias events. If bias event
+ * delivery is not supported for the sensor, this method will return false and
+ * no bias events will be generated.
  *
  * To enable bias event delivery (enable=true), the nanoapp must be registered
  * to the sensor through chreSensorConfigure, and bias events will only be