[nrf fromlist] drivers: ieee802154: add Kconfig IEEE802154_SELECTIVE_TXCHANNEL

The Kconfig `IEEE802154_SELECTIVE_TXCHANNEL` is added along with
the new capability `IEEE802154_HW_SELECTIVE_TXCHANNEL`.
The new capability of the ieee802154 drivers allows to schedule
CSL transmissions as stated in IEEE 802.15.4-2020 chapter 6.12.2.7
CSL over multiple channels. The benefit of the new API is that
additional call to `ieee802154_radio_api::set_channel()` is not
required. The drivers will switch to the new channel as late as
possible for CSL transmissions thus will not interrupt any reception
that might be in progress until the very late moment when the
transmission actually starts.
This improves reception performance when CSL transmissions are used.

Upstream PR: zephyrproject-rtos/zephyr#79919

Signed-off-by: Damian Krolik <[email protected]>
Signed-off-by: Andrzej Kuroś <[email protected]>

Author: ankuns

drivers/ieee802154/Kconfig

@@ -92,6 +92,14 @@ config IEEE802154_CSL_DEBUG
 	help
 	  Enable support for CSL debugging by avoiding sleep state in favor of receive state.
 
+config IEEE802154_SELECTIVE_TXCHANNEL
+	bool "Support for selective TX channel setting"
+	help
+	  Enable support for selectively setting TX channel for every timed transmission request.
+	  The drivers MAY have the capability IEEE802154_HW_SELECTIVE_TXCHANNEL only if
+	  this Kconfig option is enabled. If the Kconfig option is disabled the drivers
+	  MUST NOT have the capability.
+
 module = IEEE802154_DRIVER
 module-str = IEEE 802.15.4 driver
 module-help = Sets log level for IEEE 802.15.4 Device Drivers.

include/zephyr/net/ieee802154_pkt.h

@@ -59,6 +59,16 @@ struct net_pkt_cb_ieee802154 {
 			 */
 			uint8_t rssi;
 		};
+		struct {
+#if defined(CONFIG_IEEE802154_SELECTIVE_TXCHANNEL)
+			/* The channel used for timed transmissions.
+			 *
+			 * Please refer to `ieee802154_radio_api::tx` documentation for
+			 * details.
+			 */
+			uint8_t txchannel;
+#endif /* CONFIG_IEEE802154_SELECTIVE_TXCHANNEL */
+		};
 	};
 
 	/* Flags */
@@ -179,6 +189,18 @@ static inline void net_pkt_set_ieee802154_rssi_dbm(struct net_pkt *pkt, int16_t
 	CODE_UNREACHABLE;
 }
 
+#if defined(CONFIG_IEEE802154_SELECTIVE_TXCHANNEL)
+static inline uint8_t net_pkt_ieee802154_txchannel(struct net_pkt *pkt)
+{
+	return net_pkt_cb_ieee802154(pkt)->txchannel;
+}
+
+static inline void net_pkt_set_ieee802154_txchannel(struct net_pkt *pkt, uint8_t channel)
+{
+	net_pkt_cb_ieee802154(pkt)->txchannel = channel;
+}
+#endif /* CONFIG_IEEE802154_SELECTIVE_TXCHANNEL */
+
 static inline bool net_pkt_ieee802154_ack_fpb(struct net_pkt *pkt)
 {
 	return net_pkt_cb_ieee802154(pkt)->ack_fpb;

include/zephyr/net/ieee802154_radio.h

@@ -520,13 +520,26 @@ enum ieee802154_hw_caps {
 	/** RxOnWhenIdle handling supported */
 	IEEE802154_RX_ON_WHEN_IDLE = BIT(12),
 
+	/** Support for timed transmissions on selective channel.
+	 *
+	 *  This capability informs that transmissions with modes
+	 *  @ref IEEE802154_TX_MODE_TXTIME and @ref IEEE802154_TX_MODE_TXTIME_CCA support
+	 *  scheduling of timed transmissions on selective tx channel.
+	 *  The driver MAY have this capability only if the Kconfig option
+	 *  `CONFIG_IEEE802154_SELECTIVE_TXCHANNEL` is set, otherwise the driver MUST
+	 *  NOT have this capability.
+	 *
+	 *  Please refer to the `ieee802154_radio_api::tx` documentation for details.
+	 */
+	IEEE802154_HW_SELECTIVE_TXCHANNEL = BIT(13),
+
 	/* Note: Update also IEEE802154_HW_CAPS_BITS_COMMON_COUNT when changing
 	 * the ieee802154_hw_caps type.
 	 */
 };
 
 /** @brief Number of bits used by ieee802154_hw_caps type. */
-#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT (13)
+#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT (14)
 
 /** @brief This and higher values are specific to the protocol- or driver-specific extensions. */
 #define IEEE802154_HW_CAPS_BITS_PRIV_START IEEE802154_HW_CAPS_BITS_COMMON_COUNT
@@ -625,6 +638,8 @@ enum ieee802154_tx_mode {
 	 * Transmit packet in the future, at the specified time, no CCA.
 	 *
 	 * @note requires IEEE802154_HW_TXTIME capability.
+	 *
+	 * @note capability IEEE802154_HW_SELECTIVE_TXCHANNEL may apply.
 	 */
 	IEEE802154_TX_MODE_TXTIME,
 
@@ -635,6 +650,8 @@ enum ieee802154_tx_mode {
 	 *
 	 * @note Required for Thread 1.2 Coordinated Sampled Listening feature
 	 * (see Thread specification 1.2.0, ch. 3.2.6.3).
+	 *
+	 * @note capability IEEE802154_HW_SELECTIVE_TXCHANNEL may apply.
 	 */
 	IEEE802154_TX_MODE_TXTIME_CCA,
 
@@ -1657,6 +1674,23 @@ struct ieee802154_radio_api {
 	 * considerable idle waiting time. SHALL return `-ENETDOWN` unless the
 	 * interface is "UP".
 	 *
+	 * @note The transmission occurs on the radio channel set by the call to
+	 * `set_channel()`. However, if the `CONFIG_IEEE802154_SELECTIVE_TXCHANNEL`
+	 * is set and the driver has the capability `IEEE802154_HW_SELECTIVE_TXCHANNEL`
+	 * then the transmissions requested with `mode` IEEE802154_TX_MODE_TXTIME
+	 * or `IEEE802154_TX_MODE_TXTIME_CCA` SHALL use the radio channel
+	 * returned by `net_pkt_ieee802154_txchannel()` to transmit the packet
+	 * and receive an ACK on that channel if the frame requested it. After
+	 * the operation the driver should return to the channel set previously by
+	 * `set_channel()` call.
+	 * It is responsibility of an upper layer to set the required radio channel
+	 * for the packet by a call to `net_pkt_set_ieee802154_txchannel()`.
+	 * This feature allows CSL transmissions as stated in IEEE 802.15.4-2020
+	 * chapter 6.12.2.7 CSL over multiple channels. This feature allows to perform
+	 * a switch of the radio channel as late as possible before transmission without
+	 * interrupting possible reception that could occur if separate `set_channel()`
+	 * was called.
+	 *
 	 * @param dev pointer to IEEE 802.15.4 driver device
 	 * @param mode the transmission mode, some of which require specific
 	 * offloading capabilities.

include/zephyr/net/ieee802154_radio_openthread.h

@@ -64,6 +64,9 @@ enum ieee802154_openthread_tx_mode {
 	 * section 11.3, table 11-2).
 	 *
 	 * Requires IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA capability.
+	 *
+	 * @note Capability @ref IEEE802154_HW_SELECTIVE_TXCHANNEL applies as for
+	 *       @ref IEEE802154_TX_MODE_TXTIME_CCA.
 	 */
 	IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA = IEEE802154_TX_MODE_PRIV_START
 };