From 5109018dfa4055379690aceb8c6aa5eb8b2250d1 Mon Sep 17 00:00:00 2001 From: Nathan Harold Date: Mon, 28 Jan 2019 13:07:27 -0800 Subject: [PATCH] Explicitly Document INT_MAX for Invalid Fields When fields are inapplicable, they should not be set to a clearly out-of-range value to signal to the framework that those fields are not used. In some cases, there is an in-range invalid value that has been defined by the standards. The docs are inconsistent in calling out INT_MAX as the value to be used when something is inapplicable vs the case when a measurement is simply not reported. In all cases, INT_MAX can be used to denote an invalid value, and in cases where the field/structure is inapplicable, it is the correct value. This CL updates all the docstrings for SignalStrength-related fields to clarify that INT_MAX is the correct "invalid" value for cases when fields are inapplicable. Bug: 123088652 Test: compilation (docstring-only change); CTS naturally enforces this change on devices with newer HALs; backwards compatibility is preserved for existing HAL versions. Change-Id: I5cfa917f504d15691ab3f2c298189bdd47794a42 --- current.txt | 3 ++- radio/1.0/types.hal | 61 +++++++++++++++++++++++++++++++-------------- radio/1.2/types.hal | 29 +++++++++++++++++++++ 3 files changed, 73 insertions(+), 20 deletions(-) diff --git a/current.txt b/current.txt index 5dba85bc3e..37de397b30 100644 --- a/current.txt +++ b/current.txt @@ -395,8 +395,9 @@ b7ecf29927055ec422ec44bf776223f07d79ad9f92ccf9becf167e62c2607e7a android.hardwar 1fb32361286b938d48a55c2539c846732afce0b99fe08590f556643125bc13d3 android.hardware.neuralnetworks@1.0::types e22e8135d061d0e9c4c1a70c25c19fdba10f4d3cda9795ef25b6392fc520317c android.hardware.neuralnetworks@1.1::types 1d4a5776614c08b5d794a5ec5ab04697260cbd4b3441d5935cd53ee71d19da02 android.hardware.radio@1.0::IRadioResponse -271187e261b30c01a33011aea257c07a2d2f05b72943ebee89e973e997849973 android.hardware.radio@1.0::types +ed9da80ec0c96991fd03f0a46107815d0e50f764656e49dba4980fa5c31d5bc3 android.hardware.radio@1.0::types 1d19720d4fd38b1095f0f555a4bd92b3b12c9b1d0f560b0e9a474cd6dcc20db6 android.hardware.radio@1.2::IRadio +cd1757867a5e3a3faa362e785239515870d1a3c9ce756c6f0cf0f0fd8aac2547 android.hardware.radio@1.2::types e78cf871f9fd1c072874e481e06e18e2681763cf2aa38c1fd777d53bab4eb69b android.hardware.sensors@1.0::types 1722ad002317b1fae1400de709e90f442d94ef22864e05f7a12af48c32e8edc8 android.hardware.usb@1.1::types 29c8da7a13c40d488f569c812441d5754ee45bdcdb8ce6564f524b708d10a057 android.hardware.vibrator@1.1::types diff --git a/radio/1.0/types.hal b/radio/1.0/types.hal index 17718e040e..8393cf5e14 100644 --- a/radio/1.0/types.hal +++ b/radio/1.0/types.hal @@ -1230,85 +1230,108 @@ struct LastCallFailCauseInfo { struct GsmSignalStrength { uint32_t signalStrength; // Valid values are (0-61, 99) as defined in - // TS 27.007 8.69 - uint32_t bitErrorRate; // bit error rate (0-7, 99) as defined in TS 27.007 8.5 + // TS 27.007 8.69; INT_MAX means invalid/unreported. + uint32_t bitErrorRate; // bit error rate (0-7, 99) as defined in TS 27.007 8.5; + // INT_MAX means invalid/unreported. int32_t timingAdvance; // Timing Advance in bit periods. 1 bit period = 48/13 us. - // INT_MAX denotes invalid value + // INT_MAX means invalid/unreported. }; struct WcdmaSignalStrength{ int32_t signalStrength; // Valid values are (0-31, 99) as defined in - // TS 27.007 8.5 - int32_t bitErrorRate; // bit error rate (0-7, 99) as defined in TS 27.007 8.5 + // TS 27.007 8.5; INT_MAX means unreported. + int32_t bitErrorRate; // bit error rate (0-7, 99) as defined in TS 27.007 8.5; + // INT_MAX means invalid/unreported. }; struct CdmaSignalStrength { uint32_t dbm; // This value is the actual RSSI // value multiplied by -1. Example: If the // actual RSSI is -75, then this response value will - // be 75. + // be 75. INT_MAX means invalid/unreported. uint32_t ecio; // This value is the actual // Ec/Io multiplied by -10. Example: If the // actual Ec/Io is -12.5 dB, then this response value - // will be 125. + // will be 125. INT_MAX means invalid/unreported. }; struct EvdoSignalStrength { uint32_t dbm; // This value is the actual // RSSI value multiplied by -1. // Example: If the actual RSSI is -75, - // then this response value will be 75. + // then this response value will be 75; INT_MAX means + // invalid/unreported. uint32_t ecio; // This value is the actual // Ec/Io multiplied by -10. Example: If the // actual Ec/Io is -12.5 dB, then this response value - // will be 125. + // will be 125; INT_MAX means invalid/unreported. uint32_t signalNoiseRatio; // Valid values are 0-8. 8 is the highest signal to - // noise ratio. + // noise ratio; INT_MAX means invalid/unreported. }; struct LteSignalStrength { uint32_t signalStrength; // Valid values are (0-31, 99) as defined in - // TS 27.007 8.5 + // TS 27.007 8.5; INT_MAX means invalid/unreported. uint32_t rsrp; // The current Reference Signal Receive Power in dBm // multipled by -1. - // Range: 44 to 140 dBm - // INT_MAX: 0x7FFFFFFF denotes invalid value. + // Range: 44 to 140 dBm; + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP TS 36.133 9.1.4 uint32_t rsrq; // The current Reference Signal Receive Quality in dB // multiplied by -1. - // Range: 20 to 3 dB. - // INT_MAX: 0x7FFFFFFF denotes invalid value. + // Range: 20 to 3 dB; + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP TS 36.133 9.1.7 int32_t rssnr; // The current reference signal signal-to-noise ratio in // 0.1 dB units. // Range: -200 to +300 (-200 = -20.0 dB, +300 = 30dB). - // INT_MAX : 0x7FFFFFFF denotes invalid value. + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP TS 36.101 8.1.1 uint32_t cqi; // The current Channel Quality Indicator. // Range: 0 to 15. - // INT_MAX : 0x7FFFFFFF denotes invalid value. + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP TS 36.101 9.2, 9.3, A.4 uint32_t timingAdvance; // timing advance in micro seconds for a one way trip // from cell to device. // Approximate distance is calculated using // 300m/us * timingAdvance. // Range: 0 to 1282 inclusive. - // INT_MAX : 0x7FFFFFFF denotes unknown value. + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP 36.213 section 4.2.3 }; struct TdScdmaSignalStrength { uint32_t rscp; // The Received Signal Code Power in dBm multiplied by -1. // Range : 25 to 120 - // INT_MAX: 0x7FFFFFFF denotes invalid value. + // INT_MAX: 0x7FFFFFFF denotes invalid/unreported value. // Reference: 3GPP TS 25.123, section 9.1.1.1 }; struct SignalStrength { + /** + * If GSM measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ GsmSignalStrength gw; + /** + * If CDMA measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ CdmaSignalStrength cdma; + /** + * If EvDO measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ EvdoSignalStrength evdo; + /** + * If LTE measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ LteSignalStrength lte; + /** + * If TD-SCDMA measurements are provided, this structure must contain valid measurements; + * otherwise all fields should be set to INT_MAX to mark them as invalid. + */ TdScdmaSignalStrength tdScdma; }; diff --git a/radio/1.2/types.hal b/radio/1.2/types.hal index 4715facfa0..2dceeb158d 100644 --- a/radio/1.2/types.hal +++ b/radio/1.2/types.hal @@ -427,11 +427,13 @@ struct WcdmaSignalStrength { /** * CPICH RSCP as defined in TS 25.215 5.1.1 * Valid values are (0-96, 255) as defined in TS 27.007 8.69 + * INT_MAX denotes that the value is invalid/unreported. */ uint32_t rscp; /** * Ec/No value as defined in TS 25.215 5.1.5 * Valid values are (0-49, 255) as defined in TS 27.007 8.69 + * INT_MAX denotes that the value is invalid/unreported. */ uint32_t ecno; @@ -441,26 +443,53 @@ struct TdscdmaSignalStrength { /** * UTRA carrier RSSI as defined in TS 25.225 5.1.4 * Valid values are (0-31, 99) as defined in TS 27.007 8.5 + * INT_MAX denotes that the value is invalid/unreported. */ uint32_t signalStrength; /** * Transport Channel BER as defined in TS 25.225 5.2.5 * Valid values are (0-7, 99) as defined in TS 27.007 8.5 + * INT_MAX denotes that the value is invalid/unreported. */ uint32_t bitErrorRate; /** * P-CCPCH RSCP as defined in TS 25.225 5.1.1 * Valid values are (0-96, 255) as defined in TS 27.007 8.69 + * INT_MAX denotes that the value is invalid/unreported. */ uint32_t rscp; }; struct SignalStrength { + /** + * If GSM measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ GsmSignalStrength gsm; + /** + * If CDMA measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ CdmaSignalStrength cdma; + /** + * If EvDO measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ EvdoSignalStrength evdo; + /** + * If LTE measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ LteSignalStrength lte; + /** + * If TD-SCDMA measurements are provided, this structure must contain valid measurements; + * otherwise all fields should be set to INT_MAX to mark them as invalid. + */ TdScdmaSignalStrength tdScdma; + /** + * If WCDMA measurements are provided, this structure must contain valid measurements; otherwise + * all fields should be set to INT_MAX to mark them as invalid. + */ WcdmaSignalStrength wcdma; };