[platform] add per-frame tx power capability (#10481)

This commit adds a new radio capability to indicates that the platform
supports specifying tx power per frame.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (425)
+#define OPENTHREAD_API_VERSION (426)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/radio.h

@@ -127,16 +127,17 @@ typedef uint16_t otRadioCaps;
  */
 enum
 {
-    OT_RADIO_CAPS_NONE             = 0,      ///< Radio supports no capability.
-    OT_RADIO_CAPS_ACK_TIMEOUT      = 1 << 0, ///< Radio supports AckTime event.
-    OT_RADIO_CAPS_ENERGY_SCAN      = 1 << 1, ///< Radio supports Energy Scans.
-    OT_RADIO_CAPS_TRANSMIT_RETRIES = 1 << 2, ///< Radio supports tx retry logic with collision avoidance (CSMA).
-    OT_RADIO_CAPS_CSMA_BACKOFF     = 1 << 3, ///< Radio supports CSMA backoff for frame transmission (but no retry).
-    OT_RADIO_CAPS_SLEEP_TO_TX      = 1 << 4, ///< Radio supports direct transition from sleep to TX with CSMA.
-    OT_RADIO_CAPS_TRANSMIT_SEC     = 1 << 5, ///< Radio supports tx security.
-    OT_RADIO_CAPS_TRANSMIT_TIMING  = 1 << 6, ///< Radio supports tx at specific time.
-    OT_RADIO_CAPS_RECEIVE_TIMING   = 1 << 7, ///< Radio supports rx at specific time.
-    OT_RADIO_CAPS_RX_ON_WHEN_IDLE  = 1 << 8, ///< Radio supports RxOnWhenIdle handling.
+    OT_RADIO_CAPS_NONE                 = 0,      ///< Radio supports no capability.
+    OT_RADIO_CAPS_ACK_TIMEOUT          = 1 << 0, ///< Radio supports AckTime event.
+    OT_RADIO_CAPS_ENERGY_SCAN          = 1 << 1, ///< Radio supports Energy Scans.
+    OT_RADIO_CAPS_TRANSMIT_RETRIES     = 1 << 2, ///< Radio supports tx retry logic with collision avoidance (CSMA).
+    OT_RADIO_CAPS_CSMA_BACKOFF         = 1 << 3, ///< Radio supports CSMA backoff for frame transmission (but no retry).
+    OT_RADIO_CAPS_SLEEP_TO_TX          = 1 << 4, ///< Radio supports direct transition from sleep to TX with CSMA.
+    OT_RADIO_CAPS_TRANSMIT_SEC         = 1 << 5, ///< Radio supports tx security.
+    OT_RADIO_CAPS_TRANSMIT_TIMING      = 1 << 6, ///< Radio supports tx at specific time.
+    OT_RADIO_CAPS_RECEIVE_TIMING       = 1 << 7, ///< Radio supports rx at specific time.
+    OT_RADIO_CAPS_RX_ON_WHEN_IDLE      = 1 << 8, ///< Radio supports RxOnWhenIdle handling.
+    OT_RADIO_CAPS_TRANSMIT_FRAME_POWER = 1 << 9, ///< Radio supports setting per-frame transmit power.
 };
 
 #define OT_PANID_BROADCAST 0xffff ///< IEEE 802.15.4 Broadcast PAN ID
@@ -315,6 +316,25 @@ typedef struct otRadioFrame
              */
             uint8_t mRxChannelAfterTxDone;
 
+            /**
+             * The transmit power in dBm.
+             *
+             * If the platform layer does not provide `OT_RADIO_CAPS_TRANSMIT_FRAME_POWER` capability, it can ignore
+             * this value.
+             *
+             * If the value is OT_RADIO_POWER_INVALID, then the platform should ignore this value and transmit the frame
+             * with its default transmit power.
+             *
+             * Otherwise, the platform should transmit this frame with the maximum power no larger than minimal of the
+             * following values:
+             *     1. mTxPower,
+             *     2. The power limit set by otPlatRadioSetChannelTargetPower(),
+             *     3. The power limit set by otPlatRadioSetChannelMaxTransmitPower(),
+             *     4. The power limit set by otPlatRadioSetRegion().
+             *
+             */
+            int8_t mTxPower;
+
             /**
              * Indicates whether frame counter and CSL IEs are properly updated in the header.
              *

src/core/mac/mac_frame.hpp

@@ -1276,6 +1276,14 @@ public:
         SetRxChannelAfterTxDone(aChannel);
     }
 
+    /**
+     * Sets TX power to send the frame.
+     *
+     * @param[in]  aTxPower  The tx power used for transmission.
+     *
+     */
+    void SetTxPower(int8_t aTxPower) { mInfo.mTxInfo.mTxPower = aTxPower; }
+
     /**
      * Gets the RX channel after frame TX is done.
      *

src/core/mac/mac_links.hpp

@@ -186,6 +186,7 @@ public:
         mTxFrame802154.SetTxDelay(0);
         mTxFrame802154.SetTxDelayBaseTime(0);
 #endif
+        mTxFrame802154.SetTxPower(kRadioPowerInvalid);
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
         mTxFrame802154.SetCslIePresent(false);
 #endif

src/core/radio/radio.hpp

@@ -52,6 +52,8 @@ static constexpr uint32_t kUsPerTenSymbols = OT_US_PER_TEN_SYMBOLS; ///< Time fo
 static constexpr uint32_t kRadioHeaderShrDuration = 160;            ///< Duration of SHR in us
 static constexpr uint32_t kRadioHeaderPhrDuration = 32;             ///< Duration of PHR in us
 
+static constexpr int8_t kRadioPowerInvalid = OT_RADIO_POWER_INVALID; ///< Invalid TX power value
+
 #if OPENTHREAD_CONFIG_MAC_CSL_RECEIVER_ENABLE
 /**
  * Minimum CSL period supported in units of 10 symbols.