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 /** 18 * OpenThread specific capabilities of ieee802154 driver. 19 * This type extends @ref ieee802154_hw_caps. 20 */ 21 enum ieee802154_openthread_hw_caps { 22 /** Capability to transmit with @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA 23 * mode. 24 */ 25 IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA = BIT(IEEE802154_HW_CAPS_BITS_PRIV_START), 26 }; 27 28 enum ieee802154_openthread_tx_mode { 29 /** 30 * The @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA mode allows to send 31 * a scheduled packet if the channel is reported idle after at most 32 * 1 + max_extra_cca_attempts CCAs performed back-to-back. 33 * 34 * This mode is a non-standard experimental OpenThread feature. It allows transmission 35 * of a packet within a certain time window. 36 * The earliest transmission time is specified as in the other TXTIME modes: 37 * When the first CCA reports an idle channel then the first symbol of the packet's PHR 38 * SHALL be present at the local antenna at the time represented by the scheduled 39 * TX timestamp (referred to as T_tx below). 40 * 41 * If the first CCA reports a busy channel, then additional CCAs up to 42 * max_extra_cca_attempts will be done until one of them reports an idle channel and 43 * the packet is sent out or the max number of attempts is reached in which case 44 * the transmission fails. 45 * 46 * The timing of these additional CCAs depends on the capabilities of the driver 47 * which reports them in the T_recca and T_ccatx driver attributes 48 * (see @ref IEEE802154_OPENTHREAD_ATTR_T_RECCA and 49 * @ref IEEE802154_OPENTHREAD_ATTR_T_CCATX). Based on these attributes the upper layer 50 * can calculate the latest point in time (T_txmax) that the first symbol of the scheduled 51 * packet's PHR SHALL be present at the local antenna: 52 * 53 * T_maxtxdelay = max_extra_cca_attempts * (aCcaTime + T_recca) - T_recca + T_ccatx 54 * T_txmax = T_tx + T_maxtxdelay 55 * 56 * See IEEE 802.15.4-2020, section 11.3, table 11-1 for the definition of aCcaTime. 57 * 58 * Drivers implementing this TX mode SHOULD keep T_recca and T_ccatx as short as possible. 59 * T_ccatx SHALL be less than or equal aTurnaroundTime as defined in ibid., 60 * section 11.3, table 11-1. 61 * 62 * CCA SHALL be executed as defined by the phyCcaMode PHY PIB attribute (see ibid., 63 * section 11.3, table 11-2). 64 * 65 * Requires IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA capability. 66 */ 67 IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA = IEEE802154_TX_MODE_PRIV_START 68 }; 69 70 /** 71 * OpenThread specific configuration types of ieee802154 driver. 72 * This type extends @ref ieee802154_config_type. 73 */ 74 enum ieee802154_openthread_config_type { 75 /** Allows to configure extra CCA for transmission requested with mode 76 * @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA. 77 * Requires IEEE802154_OPENTHREAD_HW_MULTIPLE_CCA capability. 78 */ 79 IEEE802154_OPENTHREAD_CONFIG_MAX_EXTRA_CCA_ATTEMPTS = IEEE802154_CONFIG_PRIV_START 80 }; 81 82 /** 83 * Thread vendor OUI for vendor specific header or nested information elements, 84 * see IEEE 802.15.4-2020, sections 7.4.2.2 and 7.4.4.30. 85 * 86 * in little endian 87 */ 88 #define IEEE802154_OPENTHREAD_THREAD_IE_VENDOR_OUI { 0x9b, 0xb8, 0xea } 89 90 /** length of IEEE 802.15.4-2020 vendor OUIs */ 91 #define IEEE802154_OPENTHREAD_VENDOR_OUI_LEN 3 92 93 /** OpenThread specific configuration data of ieee802154 driver. */ 94 struct ieee802154_openthread_config { 95 union { 96 struct ieee802154_config common; 97 98 /** ``IEEE802154_OPENTHREAD_CONFIG_MAX_EXTRA_CCA_ATTEMPTS`` 99 * 100 * The maximum number of extra CCAs to be performed when transmission is 101 * requested with mode @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA. 102 */ 103 uint8_t max_extra_cca_attempts; 104 }; 105 }; 106 107 /** 108 * OpenThread specific attributes of ieee802154 driver. 109 * This type extends @ref ieee802154_attr 110 */ 111 enum ieee802154_openthread_attr { 112 113 /** Attribute: Maximum time between consecutive CCAs performed back-to-back. 114 * 115 * This is attribute for T_recca parameter mentioned for 116 * @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA. 117 * Time is expressed in microseconds. 118 */ 119 IEEE802154_OPENTHREAD_ATTR_T_RECCA = IEEE802154_ATTR_PRIV_START, 120 121 /** Attribute: Maximum time between detection of CCA idle channel and the moment of 122 * start of SHR at the local antenna. 123 * 124 * This is attribute for T_ccatx parameter mentioned for 125 * @ref IEEE802154_OPENTHREAD_TX_MODE_TXTIME_MULTIPLE_CCA. 126 * Time is expressed in microseconds. 127 */ 128 IEEE802154_OPENTHREAD_ATTR_T_CCATX 129 }; 130 131 /** 132 * OpenThread specific attribute value data of ieee802154 driver. 133 * This type extends @ref ieee802154_attr_value 134 */ 135 struct ieee802154_openthread_attr_value { 136 union { 137 struct ieee802154_attr_value common; 138 139 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_RECCA */ 140 uint16_t t_recca; 141 142 /** @brief Attribute value for @ref IEEE802154_OPENTHREAD_ATTR_T_CCATX */ 143 uint16_t t_ccatx; 144 145 }; 146 }; 147 148 #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_OPENTHREAD_H_ */ 149
