Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2023 Nordic Semiconductor ASA
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief This file extends interface of ieee802154_radio.h for OpenThread.
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_OPENTHREAD_H_
      13             : #define ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_OPENTHREAD_H_
      14             : 
      15             : #include <zephyr/net/ieee802154_radio.h>
      16             : 
      17             : /** Bit number starting the OpenThread specific capabilities of ieee802154 driver. */
      18           1 : #define IEEE802154_OPENTHREAD_HW_CAPS_BITS_START IEEE802154_HW_CAPS_BITS_PRIV_START
      19             : 
      20             : /**
      21             :  *  OpenThread specific capabilities of ieee802154 driver.
      22             :  *  This type extends @ref ieee802154_hw_caps.
      23             :  */
      24           1 : enum ieee802154_openthread_hw_caps {
      25             :         /** Capability to transmit with @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA
      26             :          *  mode.
      27             :          */
      28             :         IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA = BIT(IEEE802154_OPENTHREAD_HW_CAPS_BITS_START),
      29             : 
      30             :         /** Capability to support CST-related features.
      31             :          *
      32             :          * The CST-related features are described by "Specification changes for Thread-in-Mobile"
      33             :          * Draft version 1, July 11, 2024. The CST allows to transmit a frame with CST Phase and
      34             :          * CST Period IEs as described by chapter 4.6.6.1 of the Thread-in-Mobile specification
      35             :          * change. The upper layer implementation (OpenThread) is responsible for preparing
      36             :          * a frame to be transmitted that contains placeholders where the CST Phase and CST Period
      37             :          * are to be placed. The implementation of a driver is responsible for injecting
      38             :          * correct value for CST Phase IE and CST Period IE based on configuration parameters
      39             :          * @ref IEEE802154_OPENTHREAD_CONFIG_CST_PERIOD and
      40             :          * @ref IEEE802154_OPENTHREAD_CONFIG_EXPECTED_TX_TIME.
      41             :          *
      42             :          * @note The CST transmission in its design is very similar to CSL reception.
      43             :          * In the CSL reception the receiver side informs its peer about the moment in time
      44             :          * when it will be able to receive. In the CST transmission the transmitter side informs
      45             :          * its peer about the moment in time when the next transmission will occur.
      46             :          */
      47             :         IEEE802154_OPENTHREAD_HW_CST = BIT(IEEE802154_OPENTHREAD_HW_CAPS_BITS_START + 1),
      48             : };
      49             : 
      50             : /** @brief TX mode */
      51           1 : enum ieee802154_openthread_tx_mode {
      52             :         /**
      53             :          * The @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA mode allows to send
      54             :          * a scheduled packet if the channel is reported idle after at most
      55             :          * 1 + max_extra_cca_attempts CCAs performed back-to-back.
      56             :          *
      57             :          * This mode is a non-standard experimental OpenThread feature. It allows transmission
      58             :          * of a packet within a certain time window.
      59             :          * The earliest transmission time is specified as in the other TXTIME modes:
      60             :          * When the first CCA reports an idle channel then the first symbol of the packet's PHR
      61             :          * SHALL be present at the local antenna at the time represented by the scheduled
      62             :          * TX timestamp (referred to as T_tx below).
      63             :          *
      64             :          * If the first CCA reports a busy channel, then additional CCAs up to
      65             :          * max_extra_cca_attempts will be done until one of them reports an idle channel and
      66             :          * the packet is sent out or the max number of attempts is reached in which case
      67             :          * the transmission fails.
      68             :          *
      69             :          * The timing of these additional CCAs depends on the capabilities of the driver
      70             :          * which reports them in the T_recca and T_ccatx driver attributes
      71             :          * (see @ref IEEE802154_OPENTHREAD_ATTR_T_RECCA and
      72             :          * @ref IEEE802154_OPENTHREAD_ATTR_T_CCATX). Based on these attributes the upper layer
      73             :          * can calculate the latest point in time (T_txmax) that the first symbol of the scheduled
      74             :          * packet's PHR SHALL be present at the local antenna:
      75             :          *
      76             :          * T_maxtxdelay = max_extra_cca_attempts * (aCcaTime + T_recca) - T_recca + T_ccatx
      77             :          * T_txmax = T_tx + T_maxtxdelay
      78             :          *
      79             :          * See IEEE 802.15.4-2020, section 11.3, table 11-1 for the definition of aCcaTime.
      80             :          *
      81             :          * Drivers implementing this TX mode SHOULD keep T_recca and T_ccatx as short as possible.
      82             :          * T_ccatx SHALL be less than or equal aTurnaroundTime as defined in ibid.,
      83             :          * section 11.3, table 11-1.
      84             :          *
      85             :          * CCA SHALL be executed as defined by the phyCcaMode PHY PIB attribute (see ibid.,
      86             :          * section 11.3, table 11-2).
      87             :          *
      88             :          * Requires IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA capability.
      89             :          *
      90             :          * @note Capability @ref IEEE802154_HW_SELECTIVE_TXCHANNEL applies as for
      91             :          *       @ref IEEE802154_TX_MODE_TXTIME_CCA.
      92             :          */
      93             :         IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA = IEEE802154_TX_MODE_PRIV_START
      94             : };
      95             : 
      96             : /**
      97             :  *  OpenThread specific configuration types of ieee802154 driver.
      98             :  *  This type extends @ref ieee802154_config_type.
      99             :  */
     100           1 : enum ieee802154_openthread_config_type {
     101             :         /** Allows to configure extra CCA for transmission requested with mode
     102             :          *  @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA.
     103             :          *  Requires IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA capability.
     104             :          */
     105             :         IEEE802154_OPENTHREAD_CONFIG_MAX_EXTRA_CCA_ATTEMPTS  = IEEE802154_CONFIG_PRIV_START,
     106             : 
     107             :         /** Configures the CST period of a device.
     108             :          *
     109             :          *  When a frame containing CST Period IE is about to be transmitted by a driver,
     110             :          *  the driver SHALL inject the CST Period value to the CST Period IE based on
     111             :          *  the value of this configuration parameter.
     112             :          *
     113             :          *  Requires IEEE802154_OPENTHREAD_HW_CST capability.
     114             :          */
     115             :         IEEE802154_OPENTHREAD_CONFIG_CST_PERIOD,
     116             : 
     117             :         /** Configure a point in time at which a TX frame is expected to be transmitted.
     118             :          *
     119             :          *  When a frame containing CST Phase IE is about to be transmitted by a driver,
     120             :          *  the driver SHALL inject the CST Phase IE value to the CST Phase IE based on
     121             :          *  the value of this configuration parameter parameter, the time of transmission
     122             :          *  and the CST Period value.
     123             :          *
     124             :          *  This parameter configures the nanosecond resolution timepoint relative to
     125             :          *  the network subsystem's local clock at which a TX frame's end of SFD
     126             :          *  (i.e. equivalently its end of SHR, start of PHR) is expected to be transmitted
     127             :          *  at the local antenna.
     128             :          *
     129             :          *  Requires IEEE802154_OPENTHREAD_HW_CST capability.
     130             :          */
     131             :         IEEE802154_OPENTHREAD_CONFIG_EXPECTED_TX_TIME,
     132             : };
     133             : 
     134             : /**
     135             :  * Thread vendor OUI for vendor specific header or nested information elements,
     136             :  * see IEEE 802.15.4-2020, sections 7.4.2.2 and 7.4.4.30.
     137             :  *
     138             :  * in little endian
     139             :  */
     140           1 : #define IEEE802154_OPENTHREAD_THREAD_IE_VENDOR_OUI { 0x9b, 0xb8, 0xea }
     141             : 
     142             : /** length of IEEE 802.15.4-2020 vendor OUIs */
     143           1 : #define IEEE802154_OPENTHREAD_VENDOR_OUI_LEN 3
     144             : 
     145             : /** OpenThread specific configuration data of ieee802154 driver. */
     146           1 : struct ieee802154_openthread_config {
     147             :         union {
     148             :                 /** Common configuration */
     149           1 :                 struct ieee802154_config common;
     150             : 
     151             :                 /** ``IEEE802154_OPENTHREAD_CONFIG_MAX_EXTRA_CCA_ATTEMPTS``
     152             :                  *
     153             :                  *  The maximum number of extra CCAs to be performed when transmission is
     154             :                  *  requested with mode @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA.
     155             :                  */
     156           1 :                 uint8_t max_extra_cca_attempts;
     157             : 
     158             :                 /** ``IEEE802154_OPENTHREAD_CONFIG_CST_PERIOD``
     159             :                  *
     160             :                  *  The CST period (in CPU byte order).
     161             :                  */
     162           1 :                 uint32_t cst_period;
     163             : 
     164             :                 /** ``IEEE802154_OPENTHREAD_CONFIG_EXPECTED_TX_TIME``
     165             :                  *
     166             :                  *  A point in time at which a TX frame is expected to be transmitted.
     167             :                  */
     168           1 :                 net_time_t expected_tx_time;
     169           0 :         };
     170             : };
     171             : 
     172             : /**
     173             :  *  OpenThread specific attributes of ieee802154 driver.
     174             :  *  This type extends @ref ieee802154_attr
     175             :  */
     176           1 : enum ieee802154_openthread_attr {
     177             : 
     178             :         /** Attribute: Maximum time between consecutive CCAs performed back-to-back.
     179             :          *
     180             :          *  This is attribute for T_recca parameter mentioned for
     181             :          *  @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA.
     182             :          *  Time is expressed in microseconds.
     183             :          */
     184             :         IEEE802154_OPENTHREAD_ATTR_T_RECCA = IEEE802154_ATTR_PRIV_START,
     185             : 
     186             :         /** Attribute: Maximum time between detection of CCA idle channel and the moment of
     187             :          *  start of SHR at the local antenna.
     188             :          *
     189             :          *  This is attribute for T_ccatx parameter mentioned for
     190             :          *  @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA.
     191             :          *  Time is expressed in microseconds.
     192             :          */
     193             :         IEEE802154_OPENTHREAD_ATTR_T_CCATX
     194             : };
     195             : 
     196             : /**
     197             :  *  OpenThread specific attribute value data of ieee802154 driver.
     198             :  *  This type extends @ref ieee802154_attr_value
     199             :  */
     200           1 : struct ieee802154_openthread_attr_value {
     201             :         union {
     202             :                 /** Common attribute value */
     203           1 :                 struct ieee802154_attr_value common;
     204             : 
     205             :                 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_RECCA */
     206           1 :                 uint16_t t_recca;
     207             : 
     208             :                 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_CCATX */
     209           1 :                 uint16_t t_ccatx;
     210             : 
     211           0 :         };
     212             : };
     213             : 
     214             : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_OPENTHREAD_H_ */