From c519aa45349cef14e8e35fe73f0c4705346716db Mon Sep 17 00:00:00 2001 From: Zhanglong Xia Date: Tue, 22 Oct 2024 05:50:49 +0800 Subject: [PATCH] [api] update descriptions of the radio platform power APIs (#10839) Current radio platform defines three power related APIs: `otPlatRadioSetTransmitPower()`, `otPlatRadioSetChannelMaxTransmitPower()` and `otPlatRadioSetChannelTargetPower()`. However, the descriptions of these APIs do not clearly define the relationship between them, which causes a lot of confusion for radio platform developers. https://github.com/orgs/openthread/discussions/10761 https://github.com/orgs/openthread/discussions/10611 https://github.com/orgs/openthread/discussions/9899 This commit updates the descriptions these APIs to clearly define the relationship between these power APIs. --- include/openthread/instance.h | 2 +- include/openthread/platform/radio.h | 11 ++++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index eeb4af8bebb..1eeb751e866 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -52,7 +52,7 @@ extern "C" { * * @note This number versions both OpenThread platform and user APIs. */ -#define OPENTHREAD_API_VERSION (455) +#define OPENTHREAD_API_VERSION (456) /** * @addtogroup api-instance diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 7c57f90bae7..bd7d24fe295 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -533,10 +533,10 @@ void otPlatRadioSetShortAddress(otInstance *aInstance, otShortAddress aShortAddr otError otPlatRadioGetTransmitPower(otInstance *aInstance, int8_t *aPower); /** - * Set the radio's transmit power in dBm. + * Set the radio's transmit power in dBm for all channels. * * @note The real transmit power will be no larger than the power specified in the max power table for - * the current channel. + * the current channel that was configured by `otPlatRadioSetChannelMaxTransmitPower()`. * * @param[in] aInstance The OpenThread instance structure. * @param[in] aPower The transmit power in dBm. @@ -1185,6 +1185,9 @@ uint8_t otPlatRadioGetCslUncertainty(otInstance *aInstance); /** * Set the max transmit power for a specific channel. * + * @note This function will be deprecated in October 2027. It is recommended to use the function + * `otPlatRadioSetChannelTargetPower()`. + * * @param[in] aInstance The OpenThread instance structure. * @param[in] aChannel The radio channel. * @param[in] aMaxPower The max power in dBm, passing OT_RADIO_RSSI_INVALID will disable this channel. @@ -1300,7 +1303,9 @@ otError otPlatRadioClearCalibratedPowers(otInstance *aInstance); * Set the target power for the given channel. * * @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. + * If this function and `otPlatRadioSetTransmitPower()` are implemented at the same time: + * - If neither of these two functions is called, the radio outputs the platform-defined default power. + * - If both functions are called, the last one to be called takes effect. * * 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