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_ */
|
