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 #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 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 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 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 #define IEEE802154_OPENTHREAD_THREAD_IE_VENDOR_OUI { 0x9b, 0xb8, 0xea } 141 142 /** length of IEEE 802.15.4-2020 vendor OUIs */ 143 #define IEEE802154_OPENTHREAD_VENDOR_OUI_LEN 3 144 145 /** OpenThread specific configuration data of ieee802154 driver. */ 146 struct ieee802154_openthread_config { 147 union { 148 /** Common configuration */ 149 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 uint8_t max_extra_cca_attempts; 157 158 /** ``IEEE802154_OPENTHREAD_CONFIG_CST_PERIOD`` 159 * 160 * The CST period (in CPU byte order). 161 */ 162 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 net_time_t expected_tx_time; 169 }; 170 }; 171 172 /** 173 * OpenThread specific attributes of ieee802154 driver. 174 * This type extends @ref ieee802154_attr 175 */ 176 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 struct ieee802154_openthread_attr_value { 201 union { 202 /** Common attribute value */ 203 struct ieee802154_attr_value common; 204 205 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_RECCA */ 206 uint16_t t_recca; 207 208 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_CCATX */ 209 uint16_t t_ccatx; 210 211 }; 212 }; 213 214 #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_OPENTHREAD_H_ */ 215
