[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

@@ -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

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
+ * 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 target power.
+ * 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
+ * @param[in]  aTargetPower  The target power in 0.01dBm.
- *                           target power.
  *
  * @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.
  *
  */

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 != kInvalidIndex) ? powerIndex : minPowerIndex;
-
-    mCalibratedPowerIndex = powerIndex;
     mLastChannel          = aChannel;
 
 exit:

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) ==
+    SuccessOrQuit(otPlatRadioGetRawPowerSetting(instance, 11, rawPowerSetting, &rawPowerSettingLength));
-                 OT_ERROR_NOT_FOUND);
+    VerifyOrQuit(rawPowerSettingLength == 1);
+    VerifyOrQuit(rawPowerSetting[0] == 0x00);
 
     SuccessOrQuit(otPlatRadioSetChannelTargetPower(instance, 11, 5000));
     rawPowerSettingLength = sizeof(rawPowerSetting);