[posix] add a tx-power radio URL parameter (#13574)

The radio URL can configure the CCA threshold, the FEM LNA gain, the
region and a per-channel power cap, but not the power the radio actually
transmits at. `ot-ctl txpower` sets it at runtime only, so a deployment
cannot be brought up from its configuration alone -- something has to
issue a CLI command after every start.

`max-power-table` does not cover this. It is a cap: the effective power
is `min(txPower, channelMax)`, so it can lower the power but never raise
it above whatever the RCP happens to be at. Nothing on the host sets that
power during initialisation, and OPENTHREAD_CONFIG_DEFAULT_TRANSMIT_POWER
is consumed by the platform layer rather than here, so an RCP-based
deployment runs at whatever constant its RCP firmware was built with.

This adds `tx-power[=dbm]`, applied during radio initialisation next to
`cca-threshold` and `fem-lnagain`. The two combine rather than override:
the radio transmits at `min(tx-power, max-power-table)`, which the help
text spells out -- conditionally, since `max-power-table` is itself behind
OPENTHREAD_POSIX_CONFIG_MAX_POWER_TABLE_ENABLE and a build without it
would otherwise point at a parameter its own help does not list.

`tests/scripts/expect/posix-tx-power.exp` covers it, following
posix-ccathreshold.exp: two valid values, the two int8 boundaries that
must be rejected, and a run without the parameter that must report 0 dBm
-- without that last case the test could not tell a value that came from
the radio URL from one the radio happened to be at. Because it goes through
`RadioSpinel::SetTransmitPower()`, it also lands in the restoration
bookkeeping and survives an RCP reset.

Measured against a simulated RCP:

  tx-power=11    ot-ctl txpower -> 11 dBm
  no parameter   ot-ctl txpower ->  0 dBm

and against an SLZB-06M (EFR32, SL-OPENTHREAD/2.4.2.0), with the radio
deliberately set to 5 dBm beforehand so neither the default nor a
retained value could explain the result:

  tx-power=11    ot-ctl txpower -> 10 dBm

10 rather than 11 because the EFR32 selects the nearest step at or below
the requested power; 5 reads back as 4 for the same reason.

Closes #13573

src/posix/platform/radio.cpp

@@ -152,6 +152,12 @@ void Radio::ProcessRadioUrl(const RadioUrl &aRadioUrl)
         SuccessOrDie(mRadioSpinel.SetCcaEnergyDetectThreshold(value));
     }
 
+    if (aRadioUrl.HasParam("tx-power"))
+    {
+        SuccessOrDie(aRadioUrl.ParseInt8("tx-power", value));
+        SuccessOrDie(mRadioSpinel.SetTransmitPower(value));
+    }
+
 #if OPENTHREAD_POSIX_CONFIG_CONFIGURATION_FILE_ENABLE
     // config files should be parsed before the region parameter
     if (aRadioUrl.HasParam("product-config-file"))

src/posix/platform/radio_url.cpp

@@ -108,8 +108,15 @@ const char *otSysGetRadioUrlHelpString(void)
     "                                  If the number of values is less than that of supported channels,\n" \
     "                                  the last value will be applied to all remaining channels.\n"        \
     "                                  Special value 0x7f disables a channel.\n"
+
+// Only meaningful while max-power-table is compiled in; without it the note
+// would point at a parameter the help does not list.
+#define OT_RADIO_URL_HELP_TX_POWER_CAP                                                                \
+    "                                  max-power-table only caps the power; the radio transmits at\n" \
+    "                                  min(tx-power, max-power-table).\n"
 #else
 #define OT_RADIO_URL_HELP_MAX_POWER_TABLE
+#define OT_RADIO_URL_HELP_TX_POWER_CAP
 #endif
 
     return "RadioURL:\n" OT_RADIO_URL_HELP_BUS OT_SPINEL_SPI_RADIO_URL_HELP_BUS OT_SPINEL_HDLC_RADIO_URL_HELP_BUS
@@ -117,6 +124,7 @@ const char *otSysGetRadioUrlHelpString(void)
            "    region[=region-code]          Set the radio's region code. The region code must be an\n"
            "                                  ISO 3166 alpha-2 code.\n"
            "    cca-threshold[=dbm]           Set the radio's CCA ED threshold in dBm measured at antenna connector.\n"
+           "    tx-power[=dbm]                Set the radio's transmit power in dBm.\n" OT_RADIO_URL_HELP_TX_POWER_CAP
            "    enable-coex[=1|0]             If not specified, RCP coex operates with its default configuration.\n"
            "                                  Disable coex with 0, and enable it with other values.\n"
            "    fem-lnagain[=dbm]             Set the Rx LNA gain in dBm of the external FEM.\n"

tests/scripts/expect/posix-tx-power.exp

@@ -0,0 +1,75 @@
+#!/usr/bin/expect -f
+#
+#  Copyright (c) 2026, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+source "tests/scripts/expect/_common.exp"
+
+spawn $env(OT_POSIX_APPS)/ot-cli "spinel+hdlc+uart://$env(OT_SIMULATION_APPS)/ncp/ot-rcp?forkpty-arg=1&tx-power=11"
+expect_after {
+    timeout { exit 1 }
+}
+send "txpower\n"
+expect "11 dBm"
+expect_line "Done"
+send "\x04"
+expect eof
+
+spawn $env(OT_POSIX_APPS)/ot-cli "spinel+hdlc+uart://$env(OT_SIMULATION_APPS)/ncp/ot-rcp?forkpty-arg=1&tx-power=-20"
+expect_after {
+    timeout { exit 1 }
+}
+send "txpower\n"
+expect -- "-20 dBm"
+expect_line "Done"
+send "\x04"
+expect eof
+
+# Without the parameter the radio keeps its default, so the value above can
+# only have come from the radio URL.
+spawn $env(OT_POSIX_APPS)/ot-cli "spinel+hdlc+uart://$env(OT_SIMULATION_APPS)/ncp/ot-rcp?forkpty-arg=1"
+expect_after {
+    timeout { exit 1 }
+}
+send "txpower\n"
+expect "0 dBm"
+expect_line "Done"
+send "\x04"
+expect eof
+
+# Out of int8 range on either side: the value is rejected and the app exits.
+spawn $env(OT_POSIX_APPS)/ot-cli "spinel+hdlc+uart://$env(OT_SIMULATION_APPS)/ncp/ot-rcp?forkpty-arg=1&tx-power=128"
+expect_after {
+    timeout { exit 1 }
+}
+expect eof
+
+spawn $env(OT_POSIX_APPS)/ot-cli "spinel+hdlc+uart://$env(OT_SIMULATION_APPS)/ncp/ot-rcp?forkpty-arg=1&tx-power=-129"
+expect_after {
+    timeout { exit 1 }
+}
+expect eof