[radio] define Radio::kInvalidRssi constant (#8097)

This commit harmonizes the constant used to indicate an "Invalid RSSI
value". It defines `Radio::kInvalidRssi` which is then used in all
core modules replacing `OT_RADIO_INVALID_RSSI` and similar constants
in `SubMac/Mac`.

src/core/api/thread_api.cpp

@@ -354,7 +354,7 @@ otError otThreadGetParentAverageRssi(otInstance *aInstance, int8_t *aParentRssi)
 
     *aParentRssi = AsCoreType(aInstance).Get<Mle::MleRouter>().GetParent().GetLinkInfo().GetAverageRss();
 
-    VerifyOrExit(*aParentRssi != OT_RADIO_RSSI_INVALID, error = kErrorFailed);
+    VerifyOrExit(*aParentRssi != Radio::kInvalidRssi, error = kErrorFailed);
 
 exit:
     return error;
@@ -368,7 +368,7 @@ otError otThreadGetParentLastRssi(otInstance *aInstance, int8_t *aLastRssi)
 
     *aLastRssi = AsCoreType(aInstance).Get<Mle::MleRouter>().GetParent().GetLinkInfo().GetLastRss();
 
-    VerifyOrExit(*aLastRssi != OT_RADIO_RSSI_INVALID, error = kErrorFailed);
+    VerifyOrExit(*aLastRssi != Radio::kInvalidRssi, error = kErrorFailed);
 
 exit:
     return error;

src/core/common/message.hpp

@@ -1126,7 +1126,7 @@ public:
     /**
      * This method returns the average RSS (Received Signal Strength) associated with the message.
      *
-     * @returns The current average RSS value (in dBm) or OT_RADIO_RSSI_INVALID if no average is available.
+     * @returns The current average RSS value (in dBm) or `Radio::kInvalidRssi` if no average is available.
      *
      */
     int8_t GetAverageRss(void) const { return GetMetadata().mRssAverager.GetAverage(); }

src/core/mac/mac.cpp

@@ -348,7 +348,7 @@ void Mac::ReportEnergyScanResult(int8_t aRssi)
 {
     EnergyScanResult result;
 
-    VerifyOrExit((mEnergyScanHandler != nullptr) && (aRssi != kInvalidRssiValue));
+    VerifyOrExit((mEnergyScanHandler != nullptr) && (aRssi != Radio::kInvalidRssi));
 
     result.mChannel = mScanChannel;
     result.mMaxRssi = aRssi;

src/core/mac/mac.hpp

@@ -697,7 +697,6 @@ public:
 #endif
 
 private:
-    static constexpr int8_t   kInvalidRssiValue  = SubMac::kInvalidRssiValue;
     static constexpr uint16_t kMaxCcaSampleCount = OPENTHREAD_CONFIG_CCA_FAILURE_RATE_AVERAGING_WINDOW;
 
     enum Operation : uint8_t

src/core/mac/mac_links.hpp

@@ -291,8 +291,6 @@ class Links : public InstanceLocator
     friend class ot::Instance;
 
 public:
-    static const int8_t kInvalidRssiValue = SubMac::kInvalidRssiValue; ///< Invalid RSSI value.
-
     /**
      * This constructor initializes the `Links` object.
      *
@@ -576,7 +574,7 @@ public:
     /**
      * This method gets the most recent RSSI measurement from radio link.
      *
-     * @returns The RSSI in dBm when it is valid. `kInvalidRssiValue` when RSSI is invalid.
+     * @returns The RSSI in dBm when it is valid. `Radio::kInvalidRssi` when RSSI is invalid.
      *
      */
     int8_t GetRssi(void) const
@@ -585,7 +583,7 @@ public:
 #if OPENTHREAD_CONFIG_RADIO_LINK_IEEE_802_15_4_ENABLE
             mSubMac.GetRssi();
 #else
-            kInvalidRssiValue;
+            Radio::kInvalidRssi;
 #endif
     }
 

src/core/mac/sub_mac.cpp

@@ -79,7 +79,7 @@ void SubMac::Init(void)
     mShortAddress    = kShortAddrInvalid;
     mExtAddress.Clear();
     mRxOnWhenBackoff   = true;
-    mEnergyScanMaxRssi = kInvalidRssiValue;
+    mEnergyScanMaxRssi = Radio::kInvalidRssi;
     mEnergyScanEndTime = Time{0};
 #if OPENTHREAD_CONFIG_MAC_ADD_DELAY_ON_NO_ACK_ERROR_BEFORE_RETRY
     mRetxDelayBackOffExponent = kRetxDelayMinBackoffExponent;
@@ -673,7 +673,7 @@ int8_t SubMac::GetRssi(void) const
 #if OPENTHREAD_CONFIG_MAC_FILTER_ENABLE
     if (mRadioFilterEnabled)
     {
-        rssi = kInvalidRssiValue;
+        rssi = Radio::kInvalidRssi;
     }
     else
 #endif
@@ -716,7 +716,7 @@ Error SubMac::EnergyScan(uint8_t aScanChannel, uint16_t aScanDuration)
     }
 
 #if OPENTHREAD_CONFIG_MAC_FILTER_ENABLE
-    VerifyOrExit(!mRadioFilterEnabled, HandleEnergyScanDone(kInvalidRssiValue));
+    VerifyOrExit(!mRadioFilterEnabled, HandleEnergyScanDone(Radio::kInvalidRssi));
 #endif
 
     if (RadioSupportsEnergyScan())
@@ -729,7 +729,7 @@ Error SubMac::EnergyScan(uint8_t aScanChannel, uint16_t aScanDuration)
         SuccessOrAssert(Get<Radio>().Receive(aScanChannel));
 
         SetState(kStateEnergyScan);
-        mEnergyScanMaxRssi = kInvalidRssiValue;
+        mEnergyScanMaxRssi = Radio::kInvalidRssi;
         mEnergyScanEndTime = TimerMilli::GetNow() + static_cast<uint32_t>(aScanDuration);
         mTimer.Start(0);
     }
@@ -748,9 +748,9 @@ void SubMac::SampleRssi(void)
 
     int8_t rssi = GetRssi();
 
-    if (rssi != kInvalidRssiValue)
+    if (rssi != Radio::kInvalidRssi)
     {
-        if ((mEnergyScanMaxRssi == kInvalidRssiValue) || (rssi > mEnergyScanMaxRssi))
+        if ((mEnergyScanMaxRssi == Radio::kInvalidRssi) || (rssi > mEnergyScanMaxRssi))
         {
             mEnergyScanMaxRssi = rssi;
         }

src/core/mac/sub_mac.hpp

@@ -108,8 +108,6 @@ class SubMac : public InstanceLocator, private NonCopyable
     friend class LinkRaw;
 
 public:
-    static constexpr int8_t kInvalidRssiValue = 127; ///< Invalid Received Signal Strength Indicator (RSSI) value.
-
     /**
      * This class defines the callbacks notifying `SubMac` user of changes and events.
      *
@@ -189,7 +187,7 @@ public:
         /**
          * This method notifies user of `SubMac` that energy scan is complete.
          *
-         * @param[in]  aMaxRssi  Maximum RSSI seen on the channel, or `SubMac::kInvalidRssiValue` if failed.
+         * @param[in]  aMaxRssi  Maximum RSSI seen on the channel, or `Radio::kInvalidRssi` if failed.
          *
          */
         void EnergyScanDone(int8_t aMaxRssi);
@@ -367,7 +365,7 @@ public:
     /**
      * This method gets the most recent RSSI measurement.
      *
-     * @returns The RSSI in dBm when it is valid. `kInvalidRssiValue` when RSSI is invalid.
+     * @returns The RSSI in dBm when it is valid. `Radio::kInvalidRssi` when RSSI is invalid.
      *
      */
     int8_t GetRssi(void) const;

src/core/meshcop/joiner.cpp

@@ -244,7 +244,7 @@ uint8_t Joiner::CalculatePriority(int8_t aRssi, bool aSteeringDataAllowsAny)
 {
     int16_t priority;
 
-    if (aRssi == OT_RADIO_RSSI_INVALID)
+    if (aRssi == Radio::kInvalidRssi)
     {
         aRssi = -127;
     }

src/core/radio/radio.hpp

@@ -103,6 +103,8 @@ public:
     static constexpr uint32_t kSupportedChannelPages = (1 << OPENTHREAD_CONFIG_PLATFORM_RADIO_PROPRIETARY_CHANNEL_PAGE);
 #endif
 
+    static constexpr int8_t kInvalidRssi = OT_RADIO_RSSI_INVALID; ///< Invalid RSSI value.
+
     static_assert((OPENTHREAD_CONFIG_RADIO_2P4GHZ_OQPSK_SUPPORT || OPENTHREAD_CONFIG_RADIO_915MHZ_OQPSK_SUPPORT ||
                    OPENTHREAD_CONFIG_PLATFORM_RADIO_PROPRIETARY_SUPPORT),
                   "OPENTHREAD_CONFIG_RADIO_2P4GHZ_OQPSK_SUPPORT "
@@ -994,7 +996,7 @@ inline Error Radio::Transmit(Mac::TxFrame &)
 
 inline int8_t Radio::GetRssi(void)
 {
-    return OT_RADIO_RSSI_INVALID;
+    return kInvalidRssi;
 }
 
 inline Error Radio::EnergyScan(uint8_t, uint16_t)

src/core/radio/trel_link.cpp

@@ -240,7 +240,7 @@ void Link::BeginTransmit(void)
         mRxFrame.mRadioType = Mac::kRadioTypeTrel;
 #endif
         mRxFrame.mInfo.mRxInfo.mTimestamp             = 0;
-        mRxFrame.mInfo.mRxInfo.mRssi                  = OT_RADIO_RSSI_INVALID;
+        mRxFrame.mInfo.mRxInfo.mRssi                  = Radio::kInvalidRssi;
         mRxFrame.mInfo.mRxInfo.mLqi                   = OT_RADIO_LQI_NONE;
         mRxFrame.mInfo.mRxInfo.mAckedWithFramePending = false;
 

src/core/thread/link_quality.cpp

@@ -64,7 +64,7 @@ Error RssAverager::Add(int8_t aRss)
     Error    error = kErrorNone;
     uint16_t newValue;
 
-    VerifyOrExit(aRss != OT_RADIO_RSSI_INVALID, error = kErrorInvalidArgs);
+    VerifyOrExit(aRss != Radio::kInvalidRssi, error = kErrorInvalidArgs);
 
     // Restrict the RSS value to the closed range [0, -128] so the RSS times precision multiple can fit in 11 bits.
     if (aRss > 0)
@@ -90,7 +90,7 @@ int8_t RssAverager::GetAverage(void) const
 {
     int8_t average;
 
-    VerifyOrExit(mCount != 0, average = OT_RADIO_RSSI_INVALID);
+    VerifyOrExit(mCount != 0, average = Radio::kInvalidRssi);
 
     average = -static_cast<int8_t>(mAverage >> kPrecisionBitShift);
 
@@ -134,7 +134,7 @@ void LinkQualityInfo::Clear(void)
 {
     mRssAverager.Clear();
     SetLinkQuality(kLinkQuality0);
-    mLastRss = OT_RADIO_RSSI_INVALID;
+    mLastRss = Radio::kInvalidRssi;
 
     mFrameErrorRate.Clear();
     mMessageErrorRate.Clear();
@@ -144,7 +144,7 @@ void LinkQualityInfo::AddRss(int8_t aRss)
 {
     uint8_t oldLinkQuality = kNoLinkQuality;
 
-    VerifyOrExit(aRss != OT_RADIO_RSSI_INVALID);
+    VerifyOrExit(aRss != Radio::kInvalidRssi);
 
     mLastRss = aRss;
 
@@ -180,7 +180,7 @@ uint8_t ComputeLinkMargin(int8_t aNoiseFloor, int8_t aRss)
 {
     int8_t linkMargin = aRss - aNoiseFloor;
 
-    if (linkMargin < 0 || aRss == OT_RADIO_RSSI_INVALID)
+    if (linkMargin < 0 || aRss == Radio::kInvalidRssi)
     {
         linkMargin = 0;
     }

src/core/thread/link_quality.hpp

@@ -125,13 +125,13 @@ public:
     /**
      * This method adds a received signal strength (RSS) value to the average.
      *
-     * If @p aRss is OT_RADIO_RSSI_INVALID, it is ignored and error status kErrorInvalidArgs is returned.
+     * If @p aRss is `Radio::kInvalidRssi`, it is ignored and error status kErrorInvalidArgs is returned.
      * The value of RSS is capped at 0dBm (i.e., for any given RSS value higher than 0dBm, 0dBm is used instead).
      *
      * @param[in] aRss                Received signal strength value (in dBm) to be added to the average.
      *
      * @retval kErrorNone         New RSS value added to average successfully.
-     * @retval kErrorInvalidArgs  Value of @p aRss is OT_RADIO_RSSI_INVALID.
+     * @retval kErrorInvalidArgs  Value of @p aRss is `Radio::kInvalidRssi`.
      *
      */
     Error Add(int8_t aRss);
@@ -139,7 +139,7 @@ public:
     /**
      * This method returns the current average signal strength value maintained by the averager.
      *
-     * @returns The current average value (in dBm) or OT_RADIO_RSSI_INVALID if no average is available.
+     * @returns The current average value (in dBm) or `Radio::kInvalidRssi` if no average is available.
      *
      */
     int8_t GetAverage(void) const;
@@ -317,7 +317,7 @@ public:
     /**
      * This method returns the current average received signal strength value.
      *
-     * @returns The current average value or @c OT_RADIO_RSSI_INVALID if no average is available.
+     * @returns The current average value or `Radio::kInvalidRssi` if no average is available.
      *
      */
     int8_t GetAverageRss(void) const { return mRssAverager.GetAverage(); }

src/core/thread/mle.cpp

@@ -3901,7 +3901,7 @@ void Mle::ParentSearch::HandleTimer(void)
 
     parentRss = Get<Mle>().GetParent().GetLinkInfo().GetAverageRss();
     LogInfo("PeriodicParentSearch: Parent RSS %d", parentRss);
-    VerifyOrExit(parentRss != OT_RADIO_RSSI_INVALID);
+    VerifyOrExit(parentRss != Radio::kInvalidRssi);
 
     if (parentRss < kRssThreadhold)
     {

src/core/utils/channel_monitor.cpp

@@ -158,7 +158,7 @@ void ChannelMonitor::HandleEnergyScanResult(Mac::EnergyScanResult *aResult)
 
         LogDebg("channel: %d, rssi:%d", aResult->mChannel, aResult->mMaxRssi);
 
-        if (aResult->mMaxRssi != OT_RADIO_RSSI_INVALID)
+        if (aResult->mMaxRssi != Radio::kInvalidRssi)
         {
             newValue = (aResult->mMaxRssi >= kRssiThreshold) ? kMaxOccupancy : 0;
         }

src/core/utils/history_tracker.cpp

@@ -129,7 +129,7 @@ void HistoryTracker::RecordMessage(const Message &aMessage, const Mac::Address &
     entry->mChecksum             = headers.GetChecksum();
     entry->mIpProto              = headers.GetIpProto();
     entry->mIcmp6Type            = headers.IsIcmp6() ? headers.GetIcmpHeader().GetType() : 0;
-    entry->mAveRxRss             = (aType == kRxMessage) ? aMessage.GetRssAverager().GetAverage() : kInvalidRss;
+    entry->mAveRxRss             = (aType == kRxMessage) ? aMessage.GetRssAverager().GetAverage() : Radio::kInvalidRssi;
     entry->mLinkSecurity         = aMessage.IsLinkSecurityEnabled();
     entry->mTxSuccess            = (aType == kTxMessage) ? aMessage.GetTxSuccess() : true;
     entry->mPriority             = aMessage.GetPriority();

src/core/utils/history_tracker.hpp

@@ -273,7 +273,6 @@ private:
     static constexpr AddressEvent kAddressAdded   = OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED;
     static constexpr AddressEvent kAddressRemoved = OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED;
 
-    static constexpr int8_t   kInvalidRss    = OT_RADIO_RSSI_INVALID;
     static constexpr uint16_t kInvalidRloc16 = Mac::kShortAddrInvalid;
 
     typedef otHistoryTrackerNeighborEvent NeighborEvent;

src/core/utils/jam_detector.cpp

@@ -177,7 +177,7 @@ void JamDetector::HandleTimer(void)
 
     // If the RSSI is valid, check if it exceeds the threshold
     // and try to update the history bit map
-    if (rssi != OT_RADIO_RSSI_INVALID)
+    if (rssi != Radio::kInvalidRssi)
     {
         didExceedThreshold = (rssi >= mRssiThreshold);
         UpdateHistory(didExceedThreshold);

tests/unit/test_link_quality.cpp

@@ -70,7 +70,7 @@ int8_t sNoiseFloor = -100; // dBm
 // Check and verify the raw average RSS value to match the value from GetAverage().
 void VerifyRawRssValue(int8_t aAverage, uint16_t aRawValue)
 {
-    if (aAverage != OT_RADIO_RSSI_INVALID)
+    if (aAverage != Radio::kInvalidRssi)
     {
         VerifyOrQuit(aAverage == -static_cast<int16_t>((aRawValue + (kRawAverageMultiple / 2)) >> kRawAverageBitShift),
                      "Raw value does not match the average.");
@@ -126,7 +126,7 @@ void VerifyRawRssValue(RssAverager &aRssAverager)
     int8_t   average  = aRssAverager.GetAverage();
     uint16_t rawValue = aRssAverager.GetRaw();
 
-    if (average != OT_RADIO_RSSI_INVALID)
+    if (average != Radio::kInvalidRssi)
     {
         VerifyOrQuit(average == -static_cast<int16_t>((rawValue + (kRawAverageMultiple / 2)) >> kRawAverageBitShift),
                      "Raw value does not match the average.");
@@ -166,7 +166,7 @@ void TestRssAveraging(void)
     rssAverager.Clear();
 
     printf("\nAfter Clear: ");
-    VerifyOrQuit(rssAverager.GetAverage() == OT_RADIO_RSSI_INVALID, "Initial value from GetAverage() is incorrect.");
+    VerifyOrQuit(rssAverager.GetAverage() == Radio::kInvalidRssi, "Initial value from GetAverage() is incorrect.");
     VerifyRawRssValue(rssAverager);
     PrintOutcome(rssAverager);
 
@@ -184,7 +184,7 @@ void TestRssAveraging(void)
 
     printf("Clear(): ");
     rssAverager.Clear();
-    VerifyOrQuit(rssAverager.GetAverage() == OT_RADIO_RSSI_INVALID, "GetAverage() after Clear() is incorrect.");
+    VerifyOrQuit(rssAverager.GetAverage() == Radio::kInvalidRssi, "GetAverage() after Clear() is incorrect.");
     VerifyRawRssValue(rssAverager);
     PrintOutcome(rssAverager);