From ddbc99b8219bed13f8ba9c9dbd1be6e2b4dcdce5 Mon Sep 17 00:00:00 2001
From: Zhanglong Xia <zhanglongxia@google.com>
Date: Tue, 13 Aug 2024 13:25:05 +0800
Subject: [PATCH] [radio] update the description of
 `otPlatradioSetChannelTargetPower()` (#10585)

This commit updates the descrition of the function
`otPlatRadioSetChannelTargetPower()` to make the function descrition
more accurate, and updates the implementation of the function based on
the latest description.
---
 include/openthread/instance.h         |  2 +-
 include/openthread/platform/radio.h   | 13 ++++++++-----
 src/core/utils/power_calibration.cpp  | 12 +++++++++---
 tests/unit/test_power_calibration.cpp |  5 +++--
 4 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index 677ddc5f6..613e456d6 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (431)
+#define OPENTHREAD_API_VERSION (432)
 
 /**
  * @addtogroup api-instance
diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h
index fc11416c6..45fbe4594 100644
--- a/include/openthread/platform/radio.h
+++ b/include/openthread/platform/radio.h
@@ -1380,16 +1380,19 @@ otError otPlatRadioClearCalibratedPowers(otInstance *aInstance);
  * @note This API is an optional radio platform API. It's up to the platform layer to implement it.
  *       If this API is implemented, the function `otPlatRadioSetTransmitPower()` should be disabled.
  *
- * The radio driver should set the actual output power to be less than or equal to the target power and as close
- * as possible to the target power.
+ * The radio driver should set the actual output power to be less than or equal to the @p aTargetPower and as close
+ * as possible to the @p aTargetPower. If the @p aTargetPower is lower than the minimum output power supported
+ * by the platform, the output power should be set to the minimum output power supported by the platform.  If the
+ * @p aTargetPower is higher than the maximum output power supported by the platform, the output power should be
+ * set to the maximum output power supported by the platform. If the @p aTargetPower is set to `INT16_MAX`, the
+ * corresponding channel is disabled.
  *
  * @param[in]  aInstance     The OpenThread instance structure.
  * @param[in]  aChannel      The radio channel.
- * @param[in]  aTargetPower  The target power in 0.01dBm. Passing `INT16_MAX` will disable this channel to use the
- *                           target power.
+ * @param[in]  aTargetPower  The target power in 0.01dBm.
  *
  * @retval  OT_ERROR_NONE             Successfully set the target power.
- * @retval  OT_ERROR_INVALID_ARGS     The @p aChannel or @p aTargetPower is invalid.
+ * @retval  OT_ERROR_INVALID_ARGS     The @p aChannel is invalid.
  * @retval  OT_ERROR_NOT_IMPLEMENTED  The feature is not implemented.
  *
  */
diff --git a/src/core/utils/power_calibration.cpp b/src/core/utils/power_calibration.cpp
index 0818d0440..4c0c4c724 100644
--- a/src/core/utils/power_calibration.cpp
+++ b/src/core/utils/power_calibration.cpp
@@ -144,6 +144,8 @@ Error PowerCalibration::GetPowerSettings(uint8_t   aChannel,
     int16_t foundPower = kInvalidPower;
     int16_t targetPower;
     int16_t actualPower;
+    int16_t minPower      = NumericLimits<int16_t>::kMax;
+    uint8_t minPowerIndex = kInvalidIndex;
 
     VerifyOrExit(IsChannelValid(aChannel), error = kErrorInvalidArgs);
     VerifyOrExit((mLastChannel != aChannel) || IsPowerUpdated());
@@ -151,6 +153,7 @@ Error PowerCalibration::GetPowerSettings(uint8_t   aChannel,
     chIndex     = aChannel - Radio::kChannelMin;
     targetPower = mTargetPowerTable[chIndex];
     VerifyOrExit(targetPower != kInvalidPower, error = kErrorNotFound);
+    VerifyOrExit(mCalibratedPowerTables[chIndex].GetLength() > 0, error = kErrorNotFound);
 
     for (uint8_t i = 0; i < mCalibratedPowerTables[chIndex].GetLength(); i++)
     {
@@ -161,11 +164,14 @@ Error PowerCalibration::GetPowerSettings(uint8_t   aChannel,
             foundPower = actualPower;
             powerIndex = i;
         }
+        else if (actualPower < minPower)
+        {
+            minPower      = actualPower;
+            minPowerIndex = i;
+        }
     }
 
-    VerifyOrExit(powerIndex != kInvalidIndex, error = kErrorNotFound);
-
-    mCalibratedPowerIndex = powerIndex;
+    mCalibratedPowerIndex = (powerIndex != kInvalidIndex) ? powerIndex : minPowerIndex;
     mLastChannel          = aChannel;
 
 exit:
diff --git a/tests/unit/test_power_calibration.cpp b/tests/unit/test_power_calibration.cpp
index 9c8067ba6..8e0faf175 100644
--- a/tests/unit/test_power_calibration.cpp
+++ b/tests/unit/test_power_calibration.cpp
@@ -67,8 +67,9 @@ void TestPowerCalibration(void)
 
     SuccessOrQuit(otPlatRadioSetChannelTargetPower(instance, 11, 4999));
     rawPowerSettingLength = sizeof(rawPowerSetting);
-    VerifyOrQuit(otPlatRadioGetRawPowerSetting(instance, 11, rawPowerSetting, &rawPowerSettingLength) ==
-                 OT_ERROR_NOT_FOUND);
+    SuccessOrQuit(otPlatRadioGetRawPowerSetting(instance, 11, rawPowerSetting, &rawPowerSettingLength));
+    VerifyOrQuit(rawPowerSettingLength == 1);
+    VerifyOrQuit(rawPowerSetting[0] == 0x00);
 
     SuccessOrQuit(otPlatRadioSetChannelTargetPower(instance, 11, 5000));
     rawPowerSettingLength = sizeof(rawPowerSetting);