From 76ba504677c2ceaf2910de85c85647a0eefd1ae1 Mon Sep 17 00:00:00 2001 From: WyattRiley Date: Tue, 14 Aug 2018 18:19:30 -0700 Subject: [PATCH] Clarifying GnssMeasurement and Clock commments Change-Id: Ia51b16a2904ab43f67464fc91321fad99a2bb614 Fixes: 77812939 Test: Comments only, verified builds --- current.txt | 1 + gnss/1.0/IGnssMeasurementCallback.hal | 85 +++++++++++++++++---------- 2 files changed, 55 insertions(+), 31 deletions(-) diff --git a/current.txt b/current.txt index 327833fd3d..b1a651f01f 100644 --- a/current.txt +++ b/current.txt @@ -386,6 +386,7 @@ cd4330c3196bda1d642a32abfe23a7d64ebfbda721940643af6867af3b3f0aa9 android.hardwar # ABI preserving changes to HALs during Android Q da33234403ff5d60f3473711917b9948e6484a4260b5247acdafb111193a9de2 android.hardware.configstore@1.0::ISurfaceFlingerConfigs +78886339f2c848cf13c1edd3ebba63f89796b2620d3bf3b5c21d038a53519ba0 android.hardware.gnss@1.0::IGnssMeasurementCallback b7ecf29927055ec422ec44bf776223f07d79ad9f92ccf9becf167e62c2607e7a android.hardware.keymaster@4.0::IKeymasterDevice 574e8f1499436fb4075894dcae0b36682427956ecb114f17f1fe22d116a83c6b android.hardware.neuralnetworks@1.0::IPreparedModel 1fb32361286b938d48a55c2539c846732afce0b99fe08590f556643125bc13d3 android.hardware.neuralnetworks@1.0::types diff --git a/gnss/1.0/IGnssMeasurementCallback.hal b/gnss/1.0/IGnssMeasurementCallback.hal index b27c2e0d35..d3489e65b0 100644 --- a/gnss/1.0/IGnssMeasurementCallback.hal +++ b/gnss/1.0/IGnssMeasurementCallback.hal @@ -124,6 +124,12 @@ interface IGnssMeasurementCallback { /** * A set of flags indicating the validity of the fields in this data * structure. + * + * Fields for which there is no corresponding flag must be filled in + * with a valid value. For convenience, these are marked as mandatory. + * + * Others fields may have invalid information in them, if not marked as + * valid by the corresponding bit in gnssClockFlags. */ bitfield gnssClockFlags; @@ -155,7 +161,7 @@ interface IGnssMeasurementCallback { * Sub-nanosecond accuracy can be provided by means of the 'biasNs' field. * The value contains the timeUncertaintyNs in it. * - * This field is mandatory. + * This value is mandatory. */ int64_t timeNs; @@ -172,29 +178,31 @@ interface IGnssMeasurementCallback { /** * The difference between hardware clock ('time' field) inside GNSS receiver - * and the true GNSS time since 0000Z, January 6, 1980, in nanoseconds. + * and the true GPS time since 0000Z, January 6, 1980, in nanoseconds. * * The sign of the value is defined by the following equation: - * local estimate of GNSS time = timeNs - (fullBiasNs + biasNs) + * local estimate of GPS time = timeNs - (fullBiasNs + biasNs) * - * This value is mandatory if the receiver has estimated GNSS time. If the - * computed time is for a non-GNSS constellation, the time offset of that - * constellation to GNSS has to be applied to fill this value. The error - * estimate for the sum of this and the biasNs is the biasUncertaintyNs, - * and the caller is responsible for using this uncertainty (it can be very - * large before the GNSS time has been solved for.) If the data is available - * gnssClockFlags must contain HAS_FULL_BIAS. + * If receiver has computed time for a non-GPS constellation, the time offset of + * that constellation versus GPS time must be applied to fill this value. + * + * The error estimate for the sum of this and the biasNs is the biasUncertaintyNs. + * + * If the data is available gnssClockFlags must contain HAS_FULL_BIAS. + * + * This value is mandatory if the receiver has estimated GPS time. */ int64_t fullBiasNs; /** - * Sub-nanosecond bias. + * Sub-nanosecond bias - used with fullBiasNS, see fullBiasNs for details. + * * The error estimate for the sum of this and the fullBiasNs is the * biasUncertaintyNs. * - * If the data is available gnssClockFlags must contain HAS_BIAS. If GNSS - * has computed a position fix. This value is mandatory if the receiver has - * estimated GNSS time. + * If the data is available gnssClockFlags must contain HAS_BIAS. + * + * This value is mandatory if the receiver has estimated GPS time. */ double biasNs; @@ -203,9 +211,12 @@ interface IGnssMeasurementCallback { * bias) in nanoseconds. The uncertainty is represented as an absolute * (single sided) value. * - * If the data is available gnssClockFlags must contain - * HAS_BIAS_UNCERTAINTY. This value is mandatory if the receiver - * has estimated GNSS time. + * The caller is responsible for using this uncertainty (it can be very + * large before the GPS time has been fully resolved.) + * + * If the data is available gnssClockFlags must contain HAS_BIAS_UNCERTAINTY. + * + * This value is mandatory if the receiver has estimated GPS time. */ double biasUncertaintyNs; @@ -216,10 +227,9 @@ interface IGnssMeasurementCallback { * frequency, and that the (fullBiasNs + biasNs) is growing more positive * over time. * - * The value contains the 'drift uncertainty' in it. * If the data is available gnssClockFlags must contain HAS_DRIFT. * - * This value is mandatory if the receiver has estimated GNSS time. + * This value is mandatory if the receiver has estimated GPS time. */ double driftNsps; @@ -228,15 +238,15 @@ interface IGnssMeasurementCallback { * second). * The uncertainty is represented as an absolute (single sided) value. * - * If the data is available gnssClockFlags must contain - * HAS_DRIFT_UNCERTAINTY. If GNSS has computed a position fix this - * field is mandatory and must be populated. + * If the data is available gnssClockFlags must contain HAS_DRIFT_UNCERTAINTY. + * + * This value is mandatory if the receiver has estimated GPS time. */ double driftUncertaintyNsps; /** - * When there are any discontinuities in the HW clock, this field is - * mandatory. + * This field must be incremented, when there are discontinuities in the + * hardware clock. * * A "discontinuity" is meant to cover the case of a switch from one source * of clock to another. A single free-running crystal oscillator (XO) @@ -262,6 +272,8 @@ interface IGnssMeasurementCallback { * as this avoids the need to use (waste) a GNSS measurement to fully * re-solve for the GNSS clock bias and drift, when using the accompanying * measurements, from consecutive GnssData reports. + * + * This value is mandatory. */ uint32_t hwClockDiscontinuityCount; @@ -280,17 +292,26 @@ interface IGnssMeasurementCallback { /** * A set of flags indicating the validity of the fields in this data * structure. + * + * Fields for which there is no corresponding flag must be filled in + * with a valid value. For convenience, these are marked as mandatory. + * + * Others fields may have invalid information in them, if not marked as + * valid by the corresponding bit in flags. */ bitfield flags; /** * Satellite vehicle ID number, as defined in GnssSvInfo::svid - * This is a mandatory value. + * + * This value is mandatory. */ int16_t svid; /** * Defines the constellation of the given SV. + * + * This value is mandatory. */ GnssConstellationType constellation; @@ -302,8 +323,10 @@ interface IGnssMeasurementCallback { * measurement time = GnssClock::timeNs + timeOffsetNs * * It provides an individual time-stamp for the measurement, and allows - * sub-nanosecond accuracy. - * This is a mandatory value. + * sub-nanosecond accuracy. It may be zero if all measurements are + * aligned to a common time. + * + * This value is mandatory. */ double timeOffsetNs; @@ -313,7 +336,7 @@ interface IGnssMeasurementCallback { * Based on the sync state, the 'received GNSS tow' field must be interpreted * accordingly. * - * This is a mandatory value. + * This value is mandatory. */ bitfield state; @@ -413,7 +436,7 @@ interface IGnssMeasurementCallback { * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. * It contains the measured C/N0 value for the signal at the antenna port. * - * This is a mandatory value. + * This value is mandatory. */ double cN0DbHz; @@ -449,7 +472,7 @@ interface IGnssMeasurementCallback { * 1-Sigma uncertainty of the pseudorangeRateMps. * The uncertainty is represented as an absolute (single sided) value. * - * This is a mandatory value. + * This value is mandatory. */ double pseudorangeRateUncertaintyMps; @@ -457,7 +480,7 @@ interface IGnssMeasurementCallback { * Accumulated delta range's state. It indicates whether ADR is reset or * there is a cycle slip(indicating loss of lock). * - * This is a mandatory value. + * This value is mandatory. */ bitfield accumulatedDeltaRangeState;