Line data Source code
1 1 : /*
2 : * Copyright (c) 2016 Intel Corporation.
3 : * Copyright (c) 2023 F. Grandel, Zephyr Project
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @brief Public IEEE 802.15.4 Driver API
11 : *
12 : * @note All references to the standard in this file cite IEEE 802.15.4-2020.
13 : */
14 :
15 : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_
16 : #define ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_
17 :
18 : #include <zephyr/device.h>
19 : #include <zephyr/net/net_if.h>
20 : #include <zephyr/net/net_pkt.h>
21 : #include <zephyr/net/net_time.h>
22 : #include <zephyr/net/ieee802154.h>
23 : #include <zephyr/net/ieee802154_ie.h>
24 : #include <zephyr/sys/util.h>
25 :
26 : #ifdef __cplusplus
27 : extern "C" {
28 : #endif
29 :
30 : /**
31 : * @defgroup ieee802154_driver IEEE 802.15.4 Drivers
32 : * @since 1.0
33 : * @version 0.8.0
34 : * @ingroup ieee802154
35 : *
36 : * @brief IEEE 802.15.4 driver API
37 : *
38 : * @details This API provides a common representation of vendor-specific
39 : * hardware and firmware to the native IEEE 802.15.4 L2 and OpenThread stacks.
40 : * **Application developers should never interface directly with this API.** It
41 : * is of interest to driver maintainers only.
42 : *
43 : * The IEEE 802.15.4 driver API consists of two separate parts:
44 : * - a basic, mostly PHY-level driver API to be implemented by all drivers,
45 : * - several optional MAC-level extension points to offload performance
46 : * critical or timing sensitive aspects at MAC level to the driver hardware
47 : * or firmware ("hard" MAC).
48 : *
49 : * Implementing the basic driver API will ensure integration with the native L2
50 : * stack as well as basic support for OpenThread. Depending on the hardware,
51 : * offloading to vendor-specific hardware or firmware features may be required
52 : * to achieve full compliance with the Thread protocol or IEEE 802.15.4
53 : * subprotocols (e.g. fast enough ACK packages, precise timing of timed TX/RX in
54 : * the TSCH or CSL subprotocols).
55 : *
56 : * Whether or not MAC-level offloading extension points need to be implemented
57 : * is to be decided by individual driver maintainers. Upper layers SHOULD
58 : * provide a "soft" MAC fallback whenever possible.
59 : *
60 : * @note All section, table and figure references are to the IEEE 802.15.4-2020
61 : * standard.
62 : *
63 : * @{
64 : */
65 :
66 : /**
67 : * @name IEEE 802.15.4-2020, Section 6: MAC functional description
68 : * @{
69 : */
70 :
71 : /**
72 : * The symbol period (and therefore symbol rate) is defined in section 6.1: "Some
73 : * of the timing parameters in definition of the MAC are in units of PHY symbols.
74 : * For PHYs that have multiple symbol periods, the duration to be used for the
75 : * MAC parameters is defined in that PHY clause."
76 : *
77 : * This is not necessarily the true physical symbol period, so take care to use
78 : * this macro only when either the symbol period used for MAC timing is the same
79 : * as the physical symbol period or if you actually mean the MAC timing symbol
80 : * period.
81 : *
82 : * PHY specific symbol periods are defined in PHY specific sections below.
83 : */
84 1 : #define IEEE802154_PHY_SYMBOLS_PER_SECOND(symbol_period_ns) (NSEC_PER_SEC / symbol_period_ns)
85 :
86 : /** @} */
87 :
88 :
89 : /**
90 : * @name IEEE 802.15.4-2020, Section 8: MAC services
91 : * @{
92 : */
93 :
94 : /**
95 : * The number of PHY symbols forming a superframe slot when the superframe order
96 : * is equal to zero, see sections 8.4.2, table 8-93, aBaseSlotDuration and
97 : * section 6.2.1.
98 : */
99 1 : #define IEEE802154_MAC_A_BASE_SLOT_DURATION 60U
100 :
101 : /**
102 : * The number of slots contained in any superframe, see section 8.4.2,
103 : * table 8-93, aNumSuperframeSlots.
104 : */
105 1 : #define IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS 16U
106 :
107 : /**
108 : * The number of PHY symbols forming a superframe when the superframe order is
109 : * equal to zero, see section 8.4.2, table 8-93, aBaseSuperframeDuration.
110 : */
111 1 : #define IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION \
112 : (IEEE802154_MAC_A_BASE_SLOT_DURATION * IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS)
113 :
114 : /**
115 : * MAC PIB attribute aUnitBackoffPeriod, see section 8.4.2, table 8-93, in symbol
116 : * periods, valid for all PHYs except SUN PHY in the 920 MHz band.
117 : */
118 1 : #define IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD(turnaround_time) \
119 : (turnaround_time + IEEE802154_PHY_A_CCA_TIME)
120 :
121 : /**
122 : * Default macResponseWaitTime in multiples of aBaseSuperframeDuration as
123 : * defined in section 8.4.3.1, table 8-94.
124 : */
125 1 : #define IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT 32U
126 :
127 : /** @} */
128 :
129 :
130 : /**
131 : * @name IEEE 802.15.4-2020, Section 10: General PHY requirements
132 : * @{
133 : */
134 :
135 : /**
136 : * @brief PHY channel pages, see section 10.1.3
137 : *
138 : * @details A device driver must support the mandatory channel pages, frequency
139 : * bands and channels of at least one IEEE 802.15.4 PHY.
140 : *
141 : * Channel page and number assignments have developed over several versions of
142 : * the standard and are not particularly well documented. Therefore some notes
143 : * about peculiarities of channel pages and channel numbering:
144 : * - The 2006 version of the standard had a read-only phyChannelsSupported PHY
145 : * PIB attribute that represented channel page/number combinations as a
146 : * bitmap. This attribute was removed in later versions of the standard as the
147 : * number of channels increased beyond what could be represented by a bit map.
148 : * That's the reason why it was decided to represent supported channels as a
149 : * combination of channel pages and ranges instead.
150 : * - In the 2020 version of the standard, 13 channel pages are explicitly
151 : * defined, but up to 32 pages could in principle be supported. This was a
152 : * hard requirement in the 2006 standard. In later standards it is implicit
153 : * from field specifications, e.g. the MAC PIB attribute macChannelPage
154 : * (section 8.4.3.4, table 8-100) or channel page fields used in the SRM
155 : * protocol (see section 8.2.26.5).
156 : * - ASK PHY (channel page one) was deprecated in the 2015 version of the
157 : * standard. The 2020 version of the standard is a bit ambivalent whether
158 : * channel page one disappeared as well or should be interpreted as O-QPSK now
159 : * (see section 10.1.3.3). In Zephyr this ambivalence is resolved by
160 : * deprecating channel page one.
161 : * - For some PHYs the standard doesn't clearly specify a channel page, namely
162 : * the GFSK, RS-GFSK, CMB and TASK PHYs. These are all rather new and left out
163 : * in our list as long as no driver wants to implement them.
164 : *
165 : * @warning The bit numbers are not arbitrary but represent the channel
166 : * page numbers as defined by the standard. Therefore do not change the
167 : * bit numbering.
168 : */
169 1 : enum ieee802154_phy_channel_page {
170 : /**
171 : * Channel page zero supports the 2.4G channels of the O-QPSK PHY and
172 : * all channels from the BPSK PHYs initially defined in the 2003
173 : * editions of the standard. For channel page zero, 16 channels are
174 : * available in the 2450 MHz band (channels 11-26, O-QPSK), 10 in the
175 : * 915 MHz band (channels 1-10, BPSK), and 1 in the 868 MHz band
176 : * (channel 0, BPSK).
177 : *
178 : * You can retrieve the channels supported by a specific driver on this
179 : * page via @ref IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES attribute.
180 : *
181 : * see section 10.1.3.3
182 : */
183 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_ZERO_OQPSK_2450_BPSK_868_915 = BIT(0),
184 :
185 : /** Formerly ASK PHY - deprecated in IEEE 802.15.4-2015 */
186 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_ONE_DEPRECATED = BIT(1),
187 :
188 : /** O-QPSK PHY - 868 MHz and 915 MHz bands, see section 10.1.3.3 */
189 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWO_OQPSK_868_915 = BIT(2),
190 :
191 : /** CSS PHY - 2450 MHz band, see section 10.1.3.4 */
192 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_THREE_CSS = BIT(3),
193 :
194 : /** UWB PHY - SubG, low and high bands, see section 10.1.3.5 */
195 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_FOUR_HRP_UWB = BIT(4),
196 :
197 : /** O-QPSK PHY - 780 MHz band, see section 10.1.3.2 */
198 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_FIVE_OQPSK_780 = BIT(5),
199 :
200 : /** reserved - not currently assigned */
201 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_SIX_RESERVED = BIT(6),
202 :
203 : /** MSK PHY - 780 MHz and 2450 MHz bands, see sections 10.1.3.6, 10.1.3.7 */
204 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_SEVEN_MSK = BIT(7),
205 :
206 : /** LRP UWB PHY, see sections 10.1.3.8 */
207 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_EIGHT_LRP_UWB = BIT(8),
208 :
209 : /**
210 : * SUN FSK/OFDM/O-QPSK PHYs - predefined bands, operating modes and
211 : * channels, see sections 10.1.3.9
212 : */
213 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_NINE_SUN_PREDEFINED = BIT(9),
214 :
215 : /**
216 : * SUN FSK/OFDM/O-QPSK PHYs - generic modulation and channel
217 : * description, see sections 10.1.3.9, 7.4.4.11
218 : */
219 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_TEN_SUN_FSK_GENERIC = BIT(10),
220 :
221 : /** O-QPSK PHY - 2380 MHz band, see section 10.1.3.10 */
222 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_ELEVEN_OQPSK_2380 = BIT(11),
223 :
224 : /** LECIM DSSS/FSK PHYs, see section 10.1.3.11 */
225 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWELVE_LECIM = BIT(12),
226 :
227 : /** RCC PHY, see section 10.1.3.12 */
228 : IEEE802154_ATTR_PHY_CHANNEL_PAGE_THIRTEEN_RCC = BIT(13),
229 : };
230 :
231 : /**
232 : * Represents a supported channel range, see @ref
233 : * ieee802154_phy_supported_channels.
234 : */
235 1 : struct ieee802154_phy_channel_range {
236 1 : uint16_t from_channel; /**< From channel range */
237 1 : uint16_t to_channel; /**< To channel range */
238 : };
239 :
240 : /**
241 : * Represents a list channels supported by a driver for a given interface, see
242 : * @ref IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES.
243 : */
244 1 : struct ieee802154_phy_supported_channels {
245 : /**
246 : * @brief Pointer to an array of channel range structures.
247 : *
248 : * @warning The pointer must be valid and constant throughout the life
249 : * of the interface.
250 : */
251 1 : const struct ieee802154_phy_channel_range *const ranges;
252 :
253 : /** @brief The number of currently available channel ranges. */
254 1 : const uint8_t num_ranges;
255 : };
256 :
257 : /**
258 : * @brief Allocate memory for the supported channels driver attribute with a
259 : * single channel range constant across all driver instances. This is what most
260 : * IEEE 802.15.4 drivers need.
261 : *
262 : * @details Example usage:
263 : *
264 : * @code{.c}
265 : * IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, 11, 26);
266 : * @endcode
267 : *
268 : * The attribute may then be referenced like this:
269 : *
270 : * @code{.c}
271 : * ... &drv_attr.phy_supported_channels ...
272 : * @endcode
273 : *
274 : * See @ref ieee802154_attr_get_channel_page_and_range() for a further shortcut
275 : * that can be combined with this macro.
276 : *
277 : * @param drv_attr name of the local static variable to be declared for the
278 : * local attributes structure
279 : * @param from the first channel to be supported
280 : * @param to the last channel to be supported
281 : */
282 1 : #define IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, from, to) \
283 : static const struct { \
284 : const struct ieee802154_phy_channel_range phy_channel_range; \
285 : const struct ieee802154_phy_supported_channels phy_supported_channels; \
286 : } drv_attr = { \
287 : .phy_channel_range = {.from_channel = (from), .to_channel = (to)}, \
288 : .phy_supported_channels = \
289 : { \
290 : .ranges = &drv_attr.phy_channel_range, \
291 : .num_ranges = 1U, \
292 : }, \
293 : }
294 :
295 : /** @} */
296 :
297 :
298 : /**
299 : * @name IEEE 802.15.4-2020, Section 11: PHY services
300 : * @{
301 : */
302 :
303 : /**
304 : * Default PHY PIB attribute aTurnaroundTime, in PHY symbols, see section 11.3,
305 : * table 11-1.
306 : */
307 1 : #define IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT 12U
308 :
309 : /**
310 : * PHY PIB attribute aTurnaroundTime for SUN, RS-GFSK, TVWS, and LECIM FSK PHY,
311 : * in PHY symbols, see section 11.3, table 11-1.
312 : */
313 1 : #define IEEE802154_PHY_A_TURNAROUND_TIME_1MS(symbol_period_ns) \
314 : DIV_ROUND_UP(NSEC_PER_MSEC, symbol_period_ns)
315 :
316 : /**
317 : * PHY PIB attribute aCcaTime, in PHY symbols, all PHYs except for SUN O-QPSK,
318 : * see section 11.3, table 11-1.
319 : */
320 1 : #define IEEE802154_PHY_A_CCA_TIME 8U
321 :
322 : /** @} */
323 :
324 :
325 :
326 : /**
327 : * @name IEEE 802.15.4-2020, Section 12: O-QPSK PHY
328 : * @{
329 : */
330 :
331 : /** O-QPSK 868Mhz band symbol period, see section 12.3.3 */
332 1 : #define IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS 40000LL
333 :
334 : /**
335 : * O-QPSK 780MHz, 915MHz, 2380MHz and 2450MHz bands symbol period,
336 : * see section 12.3.3
337 : */
338 1 : #define IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS 16000LL
339 :
340 : /** @} */
341 :
342 :
343 : /**
344 : * @name IEEE 802.15.4-2020, Section 13: BPSK PHY
345 : * @{
346 : */
347 :
348 : /** BPSK 868MHz band symbol period, see section 13.3.3 */
349 1 : #define IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS 50000LL
350 :
351 : /** BPSK 915MHz band symbol period, see section 13.3.3 */
352 1 : #define IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS 25000LL
353 :
354 : /** @} */
355 :
356 :
357 : /**
358 : * @name IEEE 802.15.4-2020, Section 15: HRP UWB PHY
359 : *
360 : * @details For HRP UWB the symbol period is derived from the preamble symbol period
361 : * (T_psym), see section 11.3, table 11-1 and section 15.2.5, table 15-4
362 : * (confirmed in IEEE 802.15.4z, section 15.1). Choosing among those periods
363 : * cannot be done based on channel page and channel alone. The mean pulse
364 : * repetition frequency must also be known, see the 'UwbPrf' parameter of the
365 : * MCPS-DATA.request primitive (section 8.3.2, table 8-88) and the preamble
366 : * parameters for HRP-ERDEV length 91 codes (IEEE 802.15.4z, section 15.2.6.2,
367 : * table 15-7b).
368 : * @{
369 : */
370 :
371 : /** Nominal PRF 4MHz symbol period */
372 1 : #define IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS 3974.36F
373 : /** Nominal PRF 16MHz symbol period */
374 1 : #define IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS 993.59F
375 : /** Nominal PRF 64MHz symbol period */
376 1 : #define IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS 1017.63F
377 : /** ERDEV symbol period */
378 1 : #define IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS 729.17F
379 :
380 : /** @brief represents the nominal pulse rate frequency of an HRP UWB PHY */
381 0 : enum ieee802154_phy_hrp_uwb_nominal_prf {
382 : /** standard modes, see section 8.3.2, table 8-88. */
383 : IEEE802154_PHY_HRP_UWB_PRF_OFF = 0,
384 : IEEE802154_PHY_HRP_UWB_NOMINAL_4_M = BIT(0),
385 : IEEE802154_PHY_HRP_UWB_NOMINAL_16_M = BIT(1),
386 : IEEE802154_PHY_HRP_UWB_NOMINAL_64_M = BIT(2),
387 :
388 : /**
389 : * enhanced ranging device (ERDEV) modes not specified in table 8-88,
390 : * see IEEE 802.15.4z, section 15.1, section 15.2.6.2, table 15-7b,
391 : * section 15.3.4.2 and section 15.3.4.3.
392 : */
393 : IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF = BIT(3),
394 : IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF = BIT(4),
395 : IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF = BIT(5),
396 : };
397 :
398 : /** RDEV device mask */
399 1 : #define IEEE802154_PHY_HRP_UWB_RDEV \
400 : (IEEE802154_PHY_HRP_UWB_NOMINAL_4_M | IEEE802154_PHY_HRP_UWB_NOMINAL_16_M | \
401 : IEEE802154_PHY_HRP_UWB_NOMINAL_64_M)
402 :
403 : /** ERDEV device mask */
404 1 : #define IEEE802154_PHY_HRP_UWB_ERDEV \
405 : (IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF | IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF | \
406 : IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF)
407 :
408 : /** @} */
409 :
410 :
411 : /**
412 : * @name IEEE 802.15.4-2020, Section 19: SUN FSK PHY
413 : * @{
414 : */
415 :
416 : /** SUN FSK 863Mhz and 915MHz band symbol periods, see section 19.1, table 19-1 */
417 1 : #define IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS 20000LL
418 :
419 : /** SUN FSK PHY header length, in bytes, see section 19.2.4 */
420 1 : #define IEEE802154_PHY_SUN_FSK_PHR_LEN 2
421 :
422 : /** @} */
423 :
424 : /**
425 : * @name IEEE 802.15.4 Driver API
426 : * @{
427 : */
428 :
429 : /**
430 : * IEEE 802.15.4 driver capabilities
431 : *
432 : * Any driver properties that can be represented in binary form should be
433 : * modeled as capabilities. These are called "hardware" capabilities for
434 : * historical reasons but may also represent driver firmware capabilities (e.g.
435 : * MAC offloading features).
436 : */
437 1 : enum ieee802154_hw_caps {
438 :
439 : /*
440 : * PHY capabilities
441 : *
442 : * The following capabilities describe features of the underlying radio
443 : * hardware (PHY/L1).
444 : */
445 :
446 : /** Energy detection (ED) supported (optional) */
447 : IEEE802154_HW_ENERGY_SCAN = BIT(0),
448 :
449 : /*
450 : * MAC offloading capabilities (optional)
451 : *
452 : * The following MAC/L2 features may optionally be offloaded to
453 : * specialized hardware or proprietary driver firmware ("hard MAC").
454 : *
455 : * L2 implementations will have to provide a "soft MAC" fallback for
456 : * these features in case the driver does not support them natively.
457 : *
458 : * Note: Some of these offloading capabilities may be mandatory in
459 : * practice to stay within timing requirements of certain IEEE 802.15.4
460 : * protocols, e.g. CPUs may not be fast enough to send ACKs within the
461 : * required delays in the 2.4 GHz band without hard MAC support.
462 : */
463 :
464 : /** Frame checksum verification supported */
465 : IEEE802154_HW_FCS = BIT(1),
466 :
467 : /** Filtering of PAN ID, extended and short address supported */
468 : IEEE802154_HW_FILTER = BIT(2),
469 :
470 : /** Promiscuous mode supported */
471 : IEEE802154_HW_PROMISC = BIT(3),
472 :
473 : /** CSMA-CA procedure supported on TX */
474 : IEEE802154_HW_CSMA = BIT(4),
475 :
476 : /** Waits for ACK on TX if AR bit is set in TX pkt */
477 : IEEE802154_HW_TX_RX_ACK = BIT(5),
478 :
479 : /** Supports retransmission on TX ACK timeout */
480 : IEEE802154_HW_RETRANSMISSION = BIT(6),
481 :
482 : /** Sends ACK on RX if AR bit is set in RX pkt */
483 : IEEE802154_HW_RX_TX_ACK = BIT(7),
484 :
485 : /** TX at specified time supported */
486 : IEEE802154_HW_TXTIME = BIT(8),
487 :
488 : /** TX directly from sleep supported
489 : *
490 : * @note This HW capability does not conform to the requirements
491 : * specified in #61227 as it closely couples the driver to OpenThread's
492 : * capability and device model which is different from Zephyr's:
493 : * - "Sleeping" is a well defined term in Zephyr related to internal
494 : * power and thread management and different from "RX off" as
495 : * defined in OT.
496 : * - Currently all OT-capable drivers have the "sleep to TX"
497 : * capability anyway plus we expect future drivers to implement it
498 : * ootb as well, so no information is actually conveyed by this
499 : * capability.
500 : * - The `start()`/`stop()` API of a net device controls the
501 : * interface's operational state. Drivers MUST respond with
502 : * -ENETDOWN when calling `tx()` while their operational state is
503 : * "DOWN", only devices in the "UP" state MAY transmit packets (RFC
504 : * 2863).
505 : * - A migration path has been defined in #63670 for actual removal of
506 : * this capability in favor of a standard compliant
507 : * `configure(rx_on/rx_off)` call, see there for details.
508 : *
509 : * @deprecated Drivers and L2 SHALL not introduce additional references
510 : * to this capability and remove existing ones as outlined in #63670.
511 : */
512 : IEEE802154_HW_SLEEP_TO_TX = BIT(9),
513 :
514 : /** Timed RX window scheduling supported */
515 : IEEE802154_HW_RXTIME = BIT(10),
516 :
517 : /** TX security supported (key management, encryption and authentication) */
518 : IEEE802154_HW_TX_SEC = BIT(11),
519 :
520 : /** RxOnWhenIdle handling supported */
521 : IEEE802154_RX_ON_WHEN_IDLE = BIT(12),
522 :
523 : /** Support for timed transmissions on selective channel.
524 : *
525 : * This capability informs that transmissions with modes
526 : * @ref IEEE802154_TX_MODE_TXTIME and @ref IEEE802154_TX_MODE_TXTIME_CCA support
527 : * scheduling of timed transmissions on selective tx channel.
528 : * The driver MAY have this capability only if the Kconfig option
529 : * `CONFIG_IEEE802154_SELECTIVE_TXCHANNEL` is set, otherwise the driver MUST
530 : * NOT have this capability.
531 : *
532 : * Please refer to the `ieee802154_radio_api::tx` documentation for details.
533 : */
534 : IEEE802154_HW_SELECTIVE_TXCHANNEL = BIT(13),
535 :
536 : /* Note: Update also IEEE802154_HW_CAPS_BITS_COMMON_COUNT when changing
537 : * the ieee802154_hw_caps type.
538 : */
539 : };
540 :
541 : /** @brief Number of bits used by ieee802154_hw_caps type. */
542 1 : #define IEEE802154_HW_CAPS_BITS_COMMON_COUNT (14)
543 :
544 : /** @brief This and higher values are specific to the protocol- or driver-specific extensions. */
545 1 : #define IEEE802154_HW_CAPS_BITS_PRIV_START IEEE802154_HW_CAPS_BITS_COMMON_COUNT
546 :
547 : /** Filter type, see @ref ieee802154_radio_api::filter */
548 1 : enum ieee802154_filter_type {
549 : IEEE802154_FILTER_TYPE_IEEE_ADDR, /**< Address type filter */
550 : IEEE802154_FILTER_TYPE_SHORT_ADDR, /**< Short address type filter */
551 : IEEE802154_FILTER_TYPE_PAN_ID, /**< PAN id type filter */
552 : IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR, /**< Source address type filter */
553 : IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR, /**< Source short address type filter */
554 : };
555 :
556 : /** Driver events, see @ref IEEE802154_CONFIG_EVENT_HANDLER */
557 1 : enum ieee802154_event {
558 : /** Data transmission started */
559 : IEEE802154_EVENT_TX_STARTED,
560 : /** Data reception failed */
561 : IEEE802154_EVENT_RX_FAILED,
562 : /**
563 : * An RX slot ended, requires @ref IEEE802154_HW_RXTIME.
564 : *
565 : * @note This event SHALL not be triggered by drivers when RX is
566 : * synchronously switched of due to a call to `stop()` or an RX slot
567 : * being configured.
568 : */
569 : IEEE802154_EVENT_RX_OFF,
570 : };
571 :
572 : /** RX failed event reasons, see @ref IEEE802154_EVENT_RX_FAILED */
573 1 : enum ieee802154_rx_fail_reason {
574 : /** Nothing received */
575 : IEEE802154_RX_FAIL_NOT_RECEIVED,
576 : /** Frame had invalid checksum */
577 : IEEE802154_RX_FAIL_INVALID_FCS,
578 : /** Address did not match */
579 : IEEE802154_RX_FAIL_ADDR_FILTERED,
580 : /** General reason */
581 : IEEE802154_RX_FAIL_OTHER
582 : };
583 :
584 : /** Energy scan callback */
585 1 : typedef void (*energy_scan_done_cb_t)(const struct device *dev,
586 : int16_t max_ed);
587 :
588 : /** Driver event callback */
589 1 : typedef void (*ieee802154_event_cb_t)(const struct device *dev,
590 : enum ieee802154_event evt,
591 : void *event_params);
592 :
593 : /** Filter value, see @ref ieee802154_radio_api::filter */
594 1 : struct ieee802154_filter {
595 : union {
596 : /** Extended address, in little endian */
597 1 : uint8_t *ieee_addr;
598 : /** Short address, in CPU byte order */
599 1 : uint16_t short_addr;
600 : /** PAN ID, in CPU byte order */
601 1 : uint16_t pan_id;
602 0 : };
603 : };
604 :
605 : /**
606 : * Key configuration for transmit security offloading, see @ref
607 : * IEEE802154_CONFIG_MAC_KEYS.
608 : */
609 1 : struct ieee802154_key {
610 : /** Key material */
611 1 : uint8_t *key_value;
612 : /** Initial value of frame counter associated with the key, see section 9.4.3 */
613 1 : uint32_t key_frame_counter;
614 : /** Indicates if per-key frame counter should be used, see section 9.4.3 */
615 1 : bool frame_counter_per_key;
616 : /** Key Identifier Mode, see section 9.4.2.3, Table 9-7 */
617 1 : uint8_t key_id_mode;
618 : /** Key Identifier, see section 9.4.4 */
619 1 : uint8_t *key_id;
620 : };
621 :
622 : /** IEEE 802.15.4 Transmission mode. */
623 1 : enum ieee802154_tx_mode {
624 : /** Transmit packet immediately, no CCA. */
625 : IEEE802154_TX_MODE_DIRECT,
626 :
627 : /** Perform CCA before packet transmission. */
628 : IEEE802154_TX_MODE_CCA,
629 :
630 : /**
631 : * Perform full CSMA/CA procedure before packet transmission.
632 : *
633 : * @note requires IEEE802154_HW_CSMA capability.
634 : */
635 : IEEE802154_TX_MODE_CSMA_CA,
636 :
637 : /**
638 : * Transmit packet in the future, at the specified time, no CCA.
639 : *
640 : * @note requires IEEE802154_HW_TXTIME capability.
641 : *
642 : * @note capability IEEE802154_HW_SELECTIVE_TXCHANNEL may apply.
643 : */
644 : IEEE802154_TX_MODE_TXTIME,
645 :
646 : /**
647 : * Transmit packet in the future, perform CCA before transmission.
648 : *
649 : * @note requires IEEE802154_HW_TXTIME capability.
650 : *
651 : * @note Required for Thread 1.2 Coordinated Sampled Listening feature
652 : * (see Thread specification 1.2.0, ch. 3.2.6.3).
653 : *
654 : * @note capability IEEE802154_HW_SELECTIVE_TXCHANNEL may apply.
655 : */
656 : IEEE802154_TX_MODE_TXTIME_CCA,
657 :
658 : /** Number of modes defined in ieee802154_tx_mode. */
659 : IEEE802154_TX_MODE_COMMON_COUNT,
660 :
661 : /** This and higher values are specific to the protocol- or driver-specific extensions. */
662 : IEEE802154_TX_MODE_PRIV_START = IEEE802154_TX_MODE_COMMON_COUNT,
663 : };
664 :
665 : /** IEEE 802.15.4 Frame Pending Bit table address matching mode. */
666 1 : enum ieee802154_fpb_mode {
667 : /** The pending bit shall be set only for addresses found in the list. */
668 : IEEE802154_FPB_ADDR_MATCH_THREAD,
669 :
670 : /** The pending bit shall be cleared for short addresses found in the
671 : * list.
672 : */
673 : IEEE802154_FPB_ADDR_MATCH_ZIGBEE,
674 : };
675 :
676 : /** IEEE 802.15.4 driver configuration types. */
677 1 : enum ieee802154_config_type {
678 : /**
679 : * Indicates how the driver should set the Frame Pending bit in ACK
680 : * responses for Data Requests. If enabled, the driver should determine
681 : * whether to set the bit or not based on the information provided with
682 : * @ref IEEE802154_CONFIG_ACK_FPB config and FPB address matching mode
683 : * specified. Otherwise, Frame Pending bit should be set to ``1`` (see
684 : * section 6.7.3).
685 : *
686 : * @note requires @ref IEEE802154_HW_TX_RX_ACK capability and is
687 : * available in any interface operational state.
688 : */
689 : IEEE802154_CONFIG_AUTO_ACK_FPB,
690 :
691 : /**
692 : * Indicates whether to set ACK Frame Pending bit for specific address
693 : * or not. Disabling the Frame Pending bit with no address provided
694 : * (NULL pointer) should disable it for all enabled addresses.
695 : *
696 : * @note requires @ref IEEE802154_HW_TX_RX_ACK capability and is
697 : * available in any interface operational state.
698 : */
699 : IEEE802154_CONFIG_ACK_FPB,
700 :
701 : /**
702 : * Indicates whether the device is a PAN coordinator. This influences
703 : * packet filtering.
704 : *
705 : * @note Available in any interface operational state.
706 : */
707 : IEEE802154_CONFIG_PAN_COORDINATOR,
708 :
709 : /**
710 : * Enable/disable promiscuous mode.
711 : *
712 : * @note Available in any interface operational state.
713 : */
714 : IEEE802154_CONFIG_PROMISCUOUS,
715 :
716 : /**
717 : * Specifies new IEEE 802.15.4 driver event handler. Specifying NULL as
718 : * a handler will disable events notification.
719 : *
720 : * @note Available in any interface operational state.
721 : */
722 : IEEE802154_CONFIG_EVENT_HANDLER,
723 :
724 : /**
725 : * Updates MAC keys, key index and the per-key frame counter for drivers
726 : * supporting transmit security offloading, see section 9.5, tables 9-9
727 : * and 9-10. The key configuration SHALL NOT be accepted if the frame
728 : * counter (in case frame counter per key is true) is not strictly
729 : * larger than the current frame counter associated with the same key,
730 : * see sections 8.2.2, 9.2.4 g/h) and 9.4.3.
731 : *
732 : * @note Requires @ref IEEE802154_HW_TX_SEC capability and is available
733 : * in any interface operational state.
734 : */
735 : IEEE802154_CONFIG_MAC_KEYS,
736 :
737 : /**
738 : * Sets the current MAC frame counter value associated with the
739 : * interface for drivers supporting transmit security offloading, see
740 : * section 9.5, table 9-8, secFrameCounter.
741 : *
742 : * @warning The frame counter MUST NOT be accepted if it is not
743 : * strictly greater than the current frame counter associated with the
744 : * interface, see sections 8.2.2, 9.2.4 g/h) and 9.4.3. Otherwise the
745 : * replay protection provided by the frame counter may be compromised.
746 : * Drivers SHALL return -EINVAL in case the configured frame counter
747 : * does not conform to this requirement.
748 : *
749 : * @note Requires @ref IEEE802154_HW_TX_SEC capability and is available
750 : * in any interface operational state.
751 : */
752 : IEEE802154_CONFIG_FRAME_COUNTER,
753 :
754 : /**
755 : * Sets the current MAC frame counter value if the provided value is greater than
756 : * the current one.
757 : *
758 : * @note Requires @ref IEEE802154_HW_TX_SEC capability and is available
759 : * in any interface operational state.
760 : *
761 : * @warning This configuration option does not conform to the
762 : * requirements specified in #61227 as it is redundant with @ref
763 : * IEEE802154_CONFIG_FRAME_COUNTER, and will therefore be deprecated in
764 : * the future.
765 : */
766 : IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER,
767 :
768 : /**
769 : * Set or unset a radio reception window (RX slot). This can be used for
770 : * any scheduled reception, e.g.: Zigbee GP device, CSL, TSCH, etc.
771 : *
772 : * @details The start and duration parameters of the RX slot are
773 : * relative to the network subsystem's local clock. If the start
774 : * parameter of the RX slot is -1 then any previously configured RX
775 : * slot SHALL be canceled immediately. If the start parameter is any
776 : * value in the past (including 0) or the duration parameter is zero
777 : * then the receiver SHALL remain off forever until the RX slot has
778 : * either been removed or re-configured to point to a future start
779 : * time. If an RX slot is configured while the previous RX slot is
780 : * still scheduled, then the previous slot SHALL be cancelled and the
781 : * new slot scheduled instead.
782 : *
783 : * RX slots MAY be programmed while the driver is "DOWN". If any past
784 : * or future RX slot is configured when calling `start()` then the
785 : * interface SHALL be placed in "UP" state but the receiver SHALL not
786 : * be started.
787 : *
788 : * The driver SHALL take care to start/stop the receiver autonomously,
789 : * asynchronously and automatically around the RX slot. The driver
790 : * SHALL resume power just before the RX slot and suspend it again
791 : * after the slot unless another programmed event forces the driver not
792 : * to suspend. The driver SHALL switch to the programmed channel
793 : * before the RX slot and back to the channel set with set_channel()
794 : * after the RX slot. If the driver interface is "DOWN" when the start
795 : * time of an RX slot arrives, then the RX slot SHALL not be observed
796 : * and the receiver SHALL remain off.
797 : *
798 : * If the driver is "UP" while configuring an RX slot, the driver SHALL
799 : * turn off the receiver immediately and (possibly asynchronously) put
800 : * the driver into the lowest possible power saving mode until the
801 : * start of the RX slot. If the driver is "UP" while the RX slot is
802 : * deleted, then the driver SHALL enable the receiver immediately. The
803 : * receiver MUST be ready to receive packets before returning from the
804 : * `configure()` operation in this case.
805 : *
806 : * This behavior means that setting an RX slot implicitly sets the MAC
807 : * PIB attribute macRxOnWhenIdle (see section 8.4.3.1, table 8-94) to
808 : * "false" while deleting the RX slot implicitly sets macRxOnWhenIdle to
809 : * "true".
810 : *
811 : * @note requires @ref IEEE802154_HW_RXTIME capability and is available
812 : * in any interface operational state.
813 : *
814 : * @note Required for Thread 1.2 Coordinated Sampled Listening feature
815 : * (see Thread specification 1.2.0, ch. 3.2.6.3).
816 : */
817 : IEEE802154_CONFIG_RX_SLOT,
818 :
819 : /**
820 : * Enables or disables a device as a CSL receiver and configures its CSL
821 : * period.
822 : *
823 : * @details Configures the CSL period in units of 10 symbol periods.
824 : * Values greater than zero enable CSL if the driver supports it and the
825 : * device starts to operate as a CSL receiver. Setting this to zero
826 : * disables CSL on the device. If the driver does not support CSL, the
827 : * configuration call SHALL return -ENOTSUP.
828 : *
829 : * See section 7.4.2.3 and section 8.4.3.6, table 8-104, macCslPeriod.
830 : *
831 : * @note Confusingly the standard calls the CSL receiver "CSL
832 : * coordinator" (i.e. "coordinating the CSL protocol timing", see
833 : * section 6.12.2.2), although, typically, a CSL coordinator is NOT also
834 : * an IEEE 802.15.4 FFD coordinator or PAN coordintor but a simple RFD
835 : * end device (compare the device roles outlined in sections 5.1, 5.3,
836 : * 5.5 and 6.1). To avoid confusion we therefore prefer calling CSL
837 : * coordinators (typically an RFD end device) "CSL receivers" and CSL
838 : * peer devices (typically FFD coordinators or PAN coordinators) "CSL
839 : * transmitters". Also note that at this time, we do NOT support
840 : * unsynchronized transmission with CSL wake up frames as specified in
841 : * section 6.12.2.4.4.
842 : *
843 : * To offload CSL receiver timing to the driver the upper layer SHALL
844 : * combine several configuration options in the following way:
845 : *
846 : * 1. Use @ref IEEE802154_CONFIG_ENH_ACK_HEADER_IE once with an
847 : * appropriate pre-filled CSL IE and the CSL phase set to an
848 : * arbitrary value or left uninitialized. The CSL phase SHALL be
849 : * injected on-the-fly by the driver at runtime as outlined in 2.
850 : * below. Adding a short and extended address will inform the driver
851 : * of the specific CSL receiver to which it SHALL inject CSL IEs. If
852 : * no addresses are given then the CSL IE will be injected into all
853 : * enhanced ACK frames as soon as CSL is enabled. This configuration
854 : * SHALL be done before enabling CSL by setting a CSL period greater
855 : * than zero.
856 : *
857 : * 2. Configure @ref IEEE802154_CONFIG_EXPECTED_RX_TIME immediately
858 : * followed by @ref IEEE802154_CONFIG_CSL_PERIOD. To prevent race
859 : * conditions, the upper layer SHALL ensure that the receiver is not
860 : * enabled during or between the two calls (e.g. by a previously
861 : * configured RX slot) nor SHALL a frame be transmitted concurrently.
862 : *
863 : * The expected RX time SHALL point to the end of SFD of an ideally
864 : * timed RX frame in an arbitrary past or future CSL channel sample,
865 : * i.e. whose "end of SFD" arrives exactly at the locally predicted
866 : * time inside the CSL channel sample.
867 : *
868 : * The driver SHALL derive CSL anchor points and the CSL phase from
869 : * the given expected RX time as follows:
870 : *
871 : * cslAnchorPointNs = last expected RX time
872 : * + PHY-specific PHR duration in ns
873 : *
874 : * startOfMhrNs = start of MHR of the frame containing the
875 : * CSL IE relative to the local network clock
876 : *
877 : * cslPhase = (startOfMhrNs - cslAnchorPointNs)
878 : * / (10 * PHY specific symbol period in ns)
879 : * % cslPeriod
880 : *
881 : * The driver SHALL set the CSL phase in the IE configured in 1. and
882 : * inject that IE on-the-fly into outgoing enhanced ACK frames if the
883 : * destination address conforms to the IE's address filter.
884 : *
885 : * 3. Use @ref IEEE802154_CONFIG_RX_SLOT periodically to schedule
886 : * each CSL channel sample early enough before its start time. The
887 : * size of the CSL channel sample SHALL take relative clock drift and
888 : * scheduling uncertainties with respect to CSL transmitters into
889 : * account as specified by the standard such that at least the full
890 : * SHR of a legitimate RX frame is guaranteed to land inside the
891 : * channel sample.
892 : *
893 : * To this avail, the last configured expected RX time plus an
894 : * integer number of CSL periods SHALL point to a fixed offset of the
895 : * RX slot (not necessarily its center):
896 : *
897 : * expectedRxTimeNs_N = last expected RX time
898 : * + N * (cslPeriod * 10 * PHY-specific symbol period in ns)
899 : *
900 : * expectedRxTimeNs_N - rxSlot_N.start == const for all N
901 : *
902 : * While the configured CSL period is greater than zero, drivers
903 : * SHOULD validate the offset of the expected RX time inside each RX
904 : * slot accordingly. If the driver finds that the offset varies from
905 : * slot to slot, drivers SHOULD log the difference but SHALL
906 : * nevertheless accept and schedule the RX slot with a zero success
907 : * value to work around minor implementation or rounding errors in
908 : * upper layers.
909 : *
910 : * Configure and start a CSL receiver:
911 : *
912 : * ENH_ACK_HEADER_IE
913 : * |
914 : * | EXPECTED_RX_TIME (end of SFD of a perfectly timed RX frame
915 : * | | in any past or future channel sample)
916 : * | |
917 : * | | CSL_PERIOD (>0) RX_SLOT
918 : * | | | |
919 : * v v v v
920 : * -----------------------------------------------[-CSL channel sample ]----+
921 : * ^ |
922 : * | |
923 : * +--------------------- loop ---------+
924 : *
925 : * Disable CSL on the receiver:
926 : *
927 : * CSL_PERIOD (=0)
928 : * |
929 : * v
930 : * ---------------------
931 : *
932 : * Update the CSL period to a new value:
933 : *
934 : * EXPECTED_RX_TIME (based on updated period)
935 : * |
936 : * | CSL_PERIOD (>0, updated) RX_SLOT
937 : * | | |
938 : * v v v
939 : * -----------------------------------------------[-CSL channel sample ]----+
940 : * ^ |
941 : * | |
942 : * +--------------------- loop ---------+
943 : *
944 : * @note Available in any interface operational state.
945 : *
946 : * @note Required for Thread 1.2 Coordinated Sampled Listening feature
947 : * (see Thread specification 1.2.0, ch. 3.2.6.3).
948 : */
949 : IEEE802154_CONFIG_CSL_PERIOD,
950 :
951 : /**
952 : * Configure a timepoint at which an RX frame is expected to arrive.
953 : *
954 : * @details Configure the nanosecond resolution timepoint relative to
955 : * the network subsystem's local clock at which an RX frame's end of SFD
956 : * (i.e. equivalently its end of SHR, start of PHR, or in the case of
957 : * PHYs with RDEV or ERDEV capability the RMARKER) is expected to arrive
958 : * at the local antenna assuming perfectly synchronized local and remote
959 : * network clocks and zero distance between antennas.
960 : *
961 : * This parameter MAY be used to offload parts of timing sensitive TDMA
962 : * (e.g. TSCH, beacon-enabled PAN including DSME), low-energy (e.g.
963 : * CSL, RIT) or ranging (TDoA) protocols to the driver. In these
964 : * protocols, medium access is tightly controlled such that the expected
965 : * arrival time of a frame can be predicted within a well-defined time
966 : * window. This feature will typically be combined with @ref
967 : * IEEE802154_CONFIG_RX_SLOT although this is not a hard requirement.
968 : *
969 : * The "expected RX time" MAY be interpreted slightly differently
970 : * depending on the protocol context:
971 : * - CSL phase (i.e. time to the next expected CSL transmission) or anchor
972 : * time (i.e. any arbitrary timepoint with "zero CSL phase") SHALL be
973 : * derived by adding the PHY header duration to the expected RX time
974 : * to calculate the "start of MHR" ("first symbol of MAC", see section
975 : * 6.12.2.1) required by the CSL protocol, compare @ref
976 : * IEEE802154_CONFIG_CSL_PERIOD.
977 : * - In TSCH the expected RX time MAY be set to macTsRxOffset +
978 : * macTsRxWait / 2. Then the time correction SHALL be calculated as
979 : * the expected RX time minus actual arrival timestamp, see section
980 : * 6.5.4.3.
981 : * - In ranging applications, time difference of arrival (TDOA) MAY be
982 : * calculated inside the driver comparing actual RMARKER timestamps
983 : * against the assumed synchronized time at which the ranging frame
984 : * was sent, see IEEE 802.15.4z.
985 : *
986 : * In case of periodic protocols (e.g. CSL channel samples, periodic
987 : * beacons of a single PAN, periodic ranging "blinks"), a single
988 : * timestamp at any time in the past or in the future may be given from
989 : * which other expected timestamps can be derived by adding or
990 : * subtracting multiples of the RX period. See e.g. the CSL
991 : * documentation in this API.
992 : *
993 : * Additionally this parameter MAY be used by drivers to discipline
994 : * their local representation of a distributed network clock by deriving
995 : * synchronization instants related to a remote representation of the
996 : * same clock (as in PTP).
997 : *
998 : * @note Available in any interface operational state.
999 : *
1000 : * @note Required for Thread 1.2 Coordinated Sampled Listening feature
1001 : * (see Thread specification 1.2.0, ch. 3.2.6.3).
1002 : */
1003 : IEEE802154_CONFIG_EXPECTED_RX_TIME,
1004 :
1005 : /**
1006 : * Adds a header information element (IE) to be injected into enhanced
1007 : * ACK frames generated by the driver if the given destination address
1008 : * filter matches.
1009 : *
1010 : * @details Drivers implementing the @ref IEEE802154_HW_RX_TX_ACK
1011 : * capability generate ACK frames autonomously. Setting this
1012 : * configuration will ask the driver to inject the given preconfigured
1013 : * header IE when generating enhanced ACK frames where appropriate by
1014 : * the standard. IEs for all other frame types SHALL be provided by L2.
1015 : *
1016 : * The driver shall return -ENOTSUP in the following cases:
1017 : * - It does not support the @ref IEEE802154_HW_RX_TX_ACK,
1018 : * - It does not support header IE injection,
1019 : * - It cannot inject the runtime fields on-the-fly required for the
1020 : * given IE element ID (see list below).
1021 : *
1022 : * Enhanced ACK header IEs (element IDs in parentheses) that either
1023 : * need to be rejected or explicitly supported and parsed by the driver
1024 : * because they require on-the-fly timing information injection are:
1025 : * - CSL IE (0x1a)
1026 : * - Rendezvous Time IE (0x1d)
1027 : * - Time Correction IE (0x1e)
1028 : *
1029 : * Drivers accepting this configuration option SHALL check the list of
1030 : * configured IEs for each outgoing enhanced ACK frame, select the ones
1031 : * appropriate for the received frame based on their element ID, inject
1032 : * any required runtime information on-the-fly and include the selected
1033 : * IEs into the enhanced ACK frame's MAC header.
1034 : *
1035 : * Drivers supporting enhanced ACK header IE injection SHALL
1036 : * autonomously inject header termination IEs as required by the
1037 : * standard.
1038 : *
1039 : * A destination short address and extended address MAY be given by L2
1040 : * to filter the devices to which the given IE is included. Setting the
1041 : * short address to the broadcast address and the extended address to
1042 : * NULL will inject the given IE into all ACK frames unless a more
1043 : * specific filter is also present for any given destination device
1044 : * (fallback configuration). L2 SHALL take care to either set both
1045 : * address fields to valid device addresses or none.
1046 : *
1047 : * This configuration type may be called several times with distinct
1048 : * element IDs and/or addresses. The driver SHALL either store all
1049 : * configured IE/address combinations or return -ENOMEM if no
1050 : * additional configuration can be stored.
1051 : *
1052 : * Configuring a header IE with a previously configured element ID and
1053 : * address filter SHALL override the previous configuration. This
1054 : * implies that repetition of the same header IE/address combination is
1055 : * NOT supported.
1056 : *
1057 : * Configuring an existing element ID/address filter combination with
1058 : * the header IE's length field set to zero SHALL remove that
1059 : * configuration. SHALL remove the fallback configuration if no address
1060 : * is given.
1061 : *
1062 : * Configuring a header IE for an address filter with the header IE
1063 : * pointer set to NULL SHALL remove all header IE's for that address
1064 : * filter. SHALL remove ALL header IE configuration (including but not
1065 : * limited to fallbacks) if no address is given.
1066 : *
1067 : * If any of the deleted configurations didn't previously exist, then
1068 : * the call SHALL be ignored. Whenever the length field is set to zero,
1069 : * the content fields MUST NOT be accessed by the driver.
1070 : *
1071 : * L2 SHALL minimize the space required to keep IE configuration inside
1072 : * the driver by consolidating address filters and by removing
1073 : * configuration that is no longer required.
1074 : *
1075 : * @note requires @ref IEEE802154_HW_RX_TX_ACK capability and is
1076 : * available in any interface operational state. Currently we only
1077 : * support header IEs but that may change in the future.
1078 : *
1079 : * @note Required for Thread 1.2 Coordinated Sampled Listening feature
1080 : * (see Thread specification 1.2.0, ch. 3.2.6.3).
1081 : *
1082 : * @note Required for Thread 1.2 Link Metrics feature (see Thread
1083 : * specification 1.2.0, ch. 4.11.3.3).
1084 : */
1085 : IEEE802154_CONFIG_ENH_ACK_HEADER_IE,
1086 :
1087 : /**
1088 : * Enable/disable RxOnWhenIdle MAC PIB attribute (Table 8-94).
1089 : *
1090 : * Since there is no clear guidance in IEEE 802.15.4 specification about the definition of
1091 : * an "idle period", this implementation expects that drivers use the RxOnWhenIdle attribute
1092 : * to determine next radio state (false --> off, true --> receive) in the following
1093 : * scenarios:
1094 : * - Finalization of a regular frame reception task, provided that:
1095 : * - The frame is received without errors and passes the filtering and it's not an
1096 : * spurious ACK.
1097 : * - ACK is not requested or transmission of ACK is not possible due to internal
1098 : * conditions.
1099 : * - Finalization of a frame transmission or transmission of an ACK frame, when ACK is not
1100 : * requested in the transmitted frame.
1101 : * - Finalization of the reception operation of a requested ACK due to:
1102 : * - ACK timeout expiration.
1103 : * - Reception of an invalid ACK or not an ACK frame.
1104 : * - Reception of the proper ACK, unless the transmitted frame was a Data Request Command
1105 : * and the frame pending bit on the received ACK is set to true. In this case the radio
1106 : * platform implementation SHOULD keep the receiver on until a determined timeout which
1107 : * triggers an idle period start.
1108 : * - Finalization of a stand alone CCA task.
1109 : * - Finalization of a CCA operation with busy result during CSMA/CA procedure.
1110 : * - Finalization of an Energy Detection task.
1111 : * - Finalization of a scheduled radio reception window
1112 : * (see @ref IEEE802154_CONFIG_RX_SLOT).
1113 : */
1114 : IEEE802154_CONFIG_RX_ON_WHEN_IDLE,
1115 :
1116 : /** Number of types defined in ieee802154_config_type. */
1117 : IEEE802154_CONFIG_COMMON_COUNT,
1118 :
1119 : /** This and higher values are specific to the protocol- or driver-specific extensions. */
1120 : IEEE802154_CONFIG_PRIV_START = IEEE802154_CONFIG_COMMON_COUNT,
1121 : };
1122 :
1123 : /**
1124 : * Configuring an RX slot with the start parameter set to this value will cancel
1125 : * and delete any previously configured RX slot.
1126 : */
1127 1 : #define IEEE802154_CONFIG_RX_SLOT_NONE -1LL
1128 :
1129 : /**
1130 : * Configuring an RX slot with this start parameter while the driver is "down",
1131 : * will keep RX off when the driver is being started. Configuring an RX slot
1132 : * with this start value while the driver is "up" will immediately switch RX off
1133 : * until either the slot is deleted, see @ref IEEE802154_CONFIG_RX_SLOT_NONE or
1134 : * a slot with a future start parameter is configured and that start time
1135 : * arrives.
1136 : */
1137 1 : #define IEEE802154_CONFIG_RX_SLOT_OFF 0LL
1138 :
1139 : /** IEEE 802.15.4 driver configuration data. */
1140 1 : struct ieee802154_config {
1141 : /** Configuration data. */
1142 : union {
1143 : /** see @ref IEEE802154_CONFIG_AUTO_ACK_FPB */
1144 : struct {
1145 1 : bool enabled; /**< Is auto ACK FPB enabled */
1146 1 : enum ieee802154_fpb_mode mode; /**< Auto ACK FPB mode */
1147 1 : } auto_ack_fpb;
1148 :
1149 : /** see @ref IEEE802154_CONFIG_ACK_FPB */
1150 : struct {
1151 1 : uint8_t *addr; /**< little endian for both short and extended address */
1152 1 : bool extended; /**< Is extended address */
1153 : bool enabled; /**< Is enabled */
1154 1 : } ack_fpb;
1155 :
1156 : /** see @ref IEEE802154_CONFIG_PAN_COORDINATOR */
1157 1 : bool pan_coordinator;
1158 :
1159 : /** see @ref IEEE802154_CONFIG_PROMISCUOUS */
1160 1 : bool promiscuous;
1161 :
1162 : /** see @ref IEEE802154_CONFIG_RX_ON_WHEN_IDLE */
1163 1 : bool rx_on_when_idle;
1164 :
1165 : /** see @ref IEEE802154_CONFIG_EVENT_HANDLER */
1166 1 : ieee802154_event_cb_t event_handler;
1167 :
1168 : /**
1169 : * @brief see @ref IEEE802154_CONFIG_MAC_KEYS
1170 : *
1171 : * @details Pointer to an array containing a list of keys used
1172 : * for MAC encryption. Refer to secKeyIdLookupDescriptor and
1173 : * secKeyDescriptor in IEEE 802.15.4
1174 : *
1175 : * The key_value field points to a buffer containing the 16 byte
1176 : * key. The buffer SHALL be copied by the driver before
1177 : * returning from the call.
1178 : *
1179 : * The variable length array is terminated by key_value field
1180 : * set to NULL.
1181 : */
1182 1 : struct ieee802154_key *mac_keys;
1183 :
1184 : /** see @ref IEEE802154_CONFIG_FRAME_COUNTER */
1185 1 : uint32_t frame_counter;
1186 :
1187 : /** see @ref IEEE802154_CONFIG_RX_SLOT */
1188 : struct {
1189 : /**
1190 : * Nanosecond resolution timestamp relative to the
1191 : * network subsystem's local clock defining the start of
1192 : * the RX window during which the receiver is expected
1193 : * to be listening (i.e. not including any driver
1194 : * startup times).
1195 : *
1196 : * Configuring an rx_slot with the start attribute set
1197 : * to -1 will cancel and delete any previously active rx
1198 : * slot.
1199 : */
1200 1 : net_time_t start;
1201 :
1202 : /**
1203 : * Nanosecond resolution duration of the RX window
1204 : * relative to the above RX window start time during
1205 : * which the receiver is expected to be listening (i.e.
1206 : * not including any shutdown times). Only positive
1207 : * values larger than or equal zero are allowed.
1208 : *
1209 : * Setting the duration to zero will disable the
1210 : * receiver, no matter what the start parameter.
1211 : */
1212 1 : net_time_t duration;
1213 :
1214 : /**
1215 : * Used channel
1216 : */
1217 1 : uint8_t channel;
1218 1 : } rx_slot;
1219 :
1220 : /**
1221 : * see @ref IEEE802154_CONFIG_CSL_PERIOD
1222 : *
1223 : * in CPU byte order
1224 : */
1225 1 : uint32_t csl_period;
1226 :
1227 : /**
1228 : * see @ref IEEE802154_CONFIG_EXPECTED_RX_TIME
1229 : */
1230 1 : net_time_t expected_rx_time;
1231 :
1232 : /** see @ref IEEE802154_CONFIG_ENH_ACK_HEADER_IE */
1233 : struct {
1234 : /**
1235 : * Pointer to the header IE, see section 7.4.2.1,
1236 : * figure 7-21
1237 : *
1238 : * Certain header IEs may be incomplete if they require
1239 : * timing information to be injected at runtime
1240 : * on-the-fly, see the list in @ref
1241 : * IEEE802154_CONFIG_ENH_ACK_HEADER_IE.
1242 : */
1243 1 : struct ieee802154_header_ie *header_ie;
1244 :
1245 : /**
1246 : * Filters the devices that will receive this IE by
1247 : * extended address. MAY be set to NULL to configure a
1248 : * fallback for all devices (implies that short_addr
1249 : * MUST also be set to @ref
1250 : * IEEE802154_BROADCAST_ADDRESS).
1251 : *
1252 : * in big endian
1253 : */
1254 1 : const uint8_t *ext_addr;
1255 :
1256 : /**
1257 : * Filters the devices that will receive this IE by
1258 : * short address. MAY be set to @ref
1259 : * IEEE802154_BROADCAST_ADDRESS to configure a fallback
1260 : * for all devices (implies that ext_addr MUST also set
1261 : * to NULL in this case).
1262 : *
1263 : * in CPU byte order
1264 : */
1265 1 : uint16_t short_addr;
1266 :
1267 : /**
1268 : * Flag for purging enh ACK header IEs.
1269 : * When flag is set to true, driver should remove all existing
1270 : * header IEs, and all other entries in config should be ignored.
1271 : * This means that purging current header IEs and
1272 : * configuring a new one in the same call is not allowed.
1273 : */
1274 1 : bool purge_ie;
1275 1 : } ack_ie;
1276 1 : };
1277 : };
1278 :
1279 : /**
1280 : * @brief IEEE 802.15.4 driver attributes.
1281 : *
1282 : * See @ref ieee802154_attr_value and @ref ieee802154_radio_api for usage
1283 : * details.
1284 : */
1285 1 : enum ieee802154_attr {
1286 : /**
1287 : * Retrieves a bit field with supported channel pages. This attribute
1288 : * SHALL be implemented by all drivers.
1289 : */
1290 : IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES,
1291 :
1292 : /**
1293 : * Retrieves a pointer to the array of supported channel ranges within
1294 : * the currently configured channel page. This attribute SHALL be
1295 : * implemented by all drivers.
1296 : */
1297 : IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES,
1298 :
1299 : /**
1300 : * Retrieves a bit field with supported HRP UWB nominal pulse repetition
1301 : * frequencies. This attribute SHALL be implemented by all devices that
1302 : * support channel page four (HRP UWB).
1303 : */
1304 : IEEE802154_ATTR_PHY_HRP_UWB_SUPPORTED_PRFS,
1305 :
1306 : /** Number of attributes defined in ieee802154_attr. */
1307 : IEEE802154_ATTR_COMMON_COUNT,
1308 :
1309 : /** This and higher values are specific to the protocol- or
1310 : * driver-specific extensions.
1311 : */
1312 : IEEE802154_ATTR_PRIV_START = IEEE802154_ATTR_COMMON_COUNT,
1313 : };
1314 :
1315 : /**
1316 : * @brief IEEE 802.15.4 driver attribute values.
1317 : *
1318 : * @details This structure is reserved to scalar and structured attributes that
1319 : * originate in the driver implementation and can neither be implemented as
1320 : * boolean @ref ieee802154_hw_caps nor be derived directly or indirectly by the
1321 : * MAC (L2) layer. In particular this structure MUST NOT be used to return
1322 : * configuration data that originate from L2.
1323 : *
1324 : * @note To keep this union reasonably small, any attribute requiring a large
1325 : * memory area, SHALL be provided pointing to static memory allocated by the
1326 : * driver and valid throughout the lifetime of the driver instance.
1327 : */
1328 1 : struct ieee802154_attr_value {
1329 : union {
1330 : /* TODO: Implement configuration of phyCurrentPage once drivers
1331 : * need to support channel page switching at runtime.
1332 : */
1333 : /**
1334 : * @brief A bit field that represents the supported channel
1335 : * pages, see @ref ieee802154_phy_channel_page.
1336 : *
1337 : * @note To keep the API extensible as required by the standard,
1338 : * supported pages are modeled as a bitmap to support drivers
1339 : * that implement runtime switching between multiple channel
1340 : * pages.
1341 : *
1342 : * @note Currently none of the Zephyr drivers implements more
1343 : * than one channel page at runtime, therefore only one bit will
1344 : * be set and the current channel page (see the PHY PIB
1345 : * attribute phyCurrentPage, section 11.3, table 11-2) is
1346 : * considered to be read-only, fixed and "well known" via the
1347 : * supported channel pages attribute.
1348 : */
1349 1 : uint32_t phy_supported_channel_pages;
1350 :
1351 : /**
1352 : * @brief Pointer to a structure representing channel ranges
1353 : * currently available on the selected channel page.
1354 : *
1355 : * @warning The pointer must be valid and constant throughout
1356 : * the life of the interface.
1357 : *
1358 : * @details The selected channel page corresponds to the
1359 : * phyCurrentPage PHY PIB attribute, see the description of
1360 : * phy_supported_channel_pages above. Currently it can be
1361 : * retrieved via the @ref
1362 : * IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES attribute.
1363 : *
1364 : * Most drivers will expose a single channel page with a single,
1365 : * often zero-based, fixed channel range.
1366 : *
1367 : * Some notable exceptions:
1368 : * * The legacy channel page (zero) exposes ranges in different
1369 : * bands and even PHYs that are usually not implemented by a
1370 : * single driver.
1371 : * * SUN and LECIM PHYs specify a large number of bands and
1372 : * operating modes on a single page with overlapping channel
1373 : * ranges each. Some of these ranges are not zero-based or
1374 : * contain "holes". This explains why several ranges may be
1375 : * necessary to represent all available channels.
1376 : * * UWB PHYs often support partial channel ranges on the same
1377 : * channel page depending on the supported bands.
1378 : *
1379 : * In these cases, drivers may expose custom configuration
1380 : * attributes (Kconfig, devicetree, runtime, ...) that allow
1381 : * switching between sub-ranges within the same channel page
1382 : * (e.g. switching between SubG and 2.4G bands on channel page
1383 : * zero or switching between multiple operating modes in the SUN
1384 : * or LECIM PHYs.
1385 : */
1386 1 : const struct ieee802154_phy_supported_channels *phy_supported_channels;
1387 :
1388 : /* TODO: Allow the PRF to be configured for each TX call once
1389 : * drivers need to support PRF switching at runtime.
1390 : */
1391 : /**
1392 : * @brief A bit field representing supported HRP UWB pulse
1393 : * repetition frequencies (PRF), see enum
1394 : * ieee802154_phy_hrp_uwb_nominal_prf.
1395 : *
1396 : * @note Currently none of the Zephyr HRP UWB drivers implements
1397 : * more than one nominal PRF at runtime, therefore only one bit
1398 : * will be set and the current PRF (UwbPrf, MCPS-DATA.request,
1399 : * section 8.3.2, table 8-88) is considered to be read-only,
1400 : * fixed and "well known" via the supported PRF attribute.
1401 : */
1402 1 : uint32_t phy_hrp_uwb_supported_nominal_prfs;
1403 0 : };
1404 : };
1405 :
1406 : /**
1407 : * @brief Helper function to handle channel page and range to be called from
1408 : * drivers' attr_get() implementation. This only applies to drivers with a
1409 : * single channel page.
1410 : *
1411 : * @param attr The attribute to be retrieved.
1412 : * @param phy_supported_channel_page The driver's unique channel page.
1413 : * @param phy_supported_channels Pointer to the structure that contains the
1414 : * driver's channel range or ranges.
1415 : * @param value The pointer to the value struct provided by the user.
1416 : *
1417 : * @retval 0 if the attribute could be resolved
1418 : * @retval -ENOENT if the attribute could not be resolved
1419 : */
1420 1 : static inline int ieee802154_attr_get_channel_page_and_range(
1421 : enum ieee802154_attr attr,
1422 : const enum ieee802154_phy_channel_page phy_supported_channel_page,
1423 : const struct ieee802154_phy_supported_channels *phy_supported_channels,
1424 : struct ieee802154_attr_value *value)
1425 : {
1426 : switch (attr) {
1427 : case IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES:
1428 : value->phy_supported_channel_pages = phy_supported_channel_page;
1429 : return 0;
1430 :
1431 : case IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES:
1432 : value->phy_supported_channels = phy_supported_channels;
1433 : return 0;
1434 :
1435 : default:
1436 : return -ENOENT;
1437 : }
1438 : }
1439 :
1440 : /**
1441 : * @brief IEEE 802.15.4 driver interface API.
1442 : *
1443 : * @note This structure is called "radio" API for backwards compatibility. A
1444 : * better name would be "IEEE 802.15.4 driver API" as typical drivers will not
1445 : * only implement L1/radio (PHY) features but also L2 (MAC) features if the
1446 : * vendor-specific driver hardware or firmware offers offloading opportunities.
1447 : *
1448 : * @details While L1-level driver features are exclusively implemented by
1449 : * drivers and MAY be mandatory to support certain application requirements, L2
1450 : * features SHOULD be optional by default and only need to be implemented for
1451 : * performance optimization or precise timing as deemed necessary by driver
1452 : * maintainers. Fallback implementations ("Soft MAC") SHOULD be provided in the
1453 : * driver-independent L2 layer for all L2/MAC features especially if these
1454 : * features are not implemented in vendor hardware/firmware by a majority of
1455 : * existing in-tree drivers. If, however, a driver offers offloading
1456 : * opportunities then L2 implementations SHALL delegate performance critical or
1457 : * resource intensive tasks to the driver.
1458 : *
1459 : * All drivers SHALL support two externally observable interface operational
1460 : * states: "UP" and "DOWN". Drivers MAY additionally support a "TESTING"
1461 : * interface state (see `continuous_carrier()`).
1462 : *
1463 : * The following rules apply:
1464 : * * An interface is considered "UP" when it is able to transmit and receive
1465 : * packets, "DOWN" otherwise (see precise definitions of the corresponding
1466 : * ifOperStatus values in RFC 2863, section 3.1.14, @ref net_if_oper_state and
1467 : * the `continuous_carrier()` exception below). A device that has its receiver
1468 : * temporarily disabled during "UP" state due to an active receive window
1469 : * configuration is still considered "UP".
1470 : * * Upper layers will assume that the interface managed by the driver is "UP"
1471 : * after a call to `start()` returned zero or `-EALREADY`. Upper layers assume
1472 : * that the interface is "DOWN" after calling `stop()` returned zero or
1473 : * `-EALREADY`.
1474 : * * The driver SHALL block `start()`/`stop()` calls until the interface fully
1475 : * transitioned to the new state (e.g. the receiver is operational, ongoing
1476 : * transmissions were finished, etc.). Drivers SHOULD yield the calling thread
1477 : * (i.e. "sleep") if waiting for the new state without CPU interaction is
1478 : * possible.
1479 : * * Drivers are responsible of guaranteeing atomicity of state changes.
1480 : * Appropriate means of synchronization SHALL be implemented (locking, atomic
1481 : * flags, ...).
1482 : * * While the interface is "DOWN", the driver SHALL be placed in the lowest
1483 : * possible power state. The driver MAY return from a call to `stop()` before
1484 : * it reaches the lowest possible power state, i.e. manage power
1485 : * asynchronously. While the interface is "UP", the driver SHOULD
1486 : * autonomously and asynchronously transition to lower power states whenever
1487 : * possible. If the driver claims to support timed RX/TX capabilities and the
1488 : * upper layers configure an RX slot, then the driver SHALL immediately
1489 : * transition (asynchronously) to the lowest possible power state until the
1490 : * start of the RX slot or until a scheduled packet needs to be transmitted.
1491 : * * The driver SHALL NOT change the interface's "UP"/"DOWN" state on its own.
1492 : * Initially, the interface SHALL be in the "DOWN" state.
1493 : * * Drivers that implement the optional `continuous_carrier()` operation will
1494 : * be considered to be in the RFC 2863 "testing" ifOperStatus state if that
1495 : * operation returns zero. This state is active until either `start()` or
1496 : * `stop()` is called. If `continuous_carrier()` returns a non-zero value then
1497 : * the previous state is assumed by upper layers.
1498 : * * If calls to `start()`/`stop()` return any other value than zero or
1499 : * `-EALREADY`, upper layers will consider the interface to be in a
1500 : * "lowerLayerDown" state as defined in RFC 2863.
1501 : * * The RFC 2863 "dormant", "unknown" and "notPresent" ifOperStatus states are
1502 : * currently not supported. The "lowerLevelUp" state.
1503 : * * The `ed_scan()`, `cca()` and `tx()` operations SHALL only be supported in
1504 : * the "UP" state and return `-ENETDOWN` in any other state. See the
1505 : * function-level API documentation below for further details.
1506 : *
1507 : * @note In case of devices that support timed RX/TX, the "UP" state is not
1508 : * equal to "receiver enabled". If a receive window (i.e. RX slot, see @ref
1509 : * IEEE802154_CONFIG_RX_SLOT) is configured before calling `start()` then the
1510 : * receiver will not be enabled when transitioning to the "UP" state.
1511 : * Configuring a receive window while the interface is "UP" will cause the
1512 : * receiver to be disabled immediately until the configured reception time has
1513 : * arrived.
1514 : */
1515 1 : struct ieee802154_radio_api {
1516 : /**
1517 : * @brief network interface API
1518 : *
1519 : * @note Network devices must extend the network interface API. It is
1520 : * therefore mandatory to place it at the top of the driver API struct so
1521 : * that it can be cast to a network interface.
1522 : */
1523 1 : struct net_if_api iface_api;
1524 :
1525 : /**
1526 : * @brief Get the device driver capabilities.
1527 : *
1528 : * @note Implementations SHALL be **isr-ok** and MUST NOT **sleep**. MAY
1529 : * be called in any interface state once the driver is fully initialized
1530 : * ("ready").
1531 : *
1532 : * @param dev pointer to IEEE 802.15.4 driver device
1533 : *
1534 : * @return Bit field with all supported device driver capabilities.
1535 : */
1536 : enum ieee802154_hw_caps (*get_capabilities)(const struct device *dev);
1537 :
1538 : /**
1539 : * @brief Clear Channel Assessment - Check channel's activity
1540 : *
1541 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1542 : * return -ENETDOWN unless the interface is "UP".
1543 : *
1544 : * @param dev pointer to IEEE 802.15.4 driver device
1545 : *
1546 : * @retval 0 the channel is available
1547 : * @retval -EBUSY The channel is busy.
1548 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1549 : * temporarily cannot be executed without blocking.
1550 : * @retval -ENETDOWN The interface is not "UP".
1551 : * @retval -ENOTSUP CCA is not supported by this driver.
1552 : * @retval -EIO The CCA procedure could not be executed.
1553 : */
1554 1 : int (*cca)(const struct device *dev);
1555 :
1556 : /**
1557 : * @brief Set current channel
1558 : *
1559 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1560 : * return -EIO unless the interface is either "UP" or "DOWN".
1561 : *
1562 : * @param dev pointer to IEEE 802.15.4 driver device
1563 : * @param channel the number of the channel to be set in CPU byte order
1564 : *
1565 : * @retval 0 channel was successfully set
1566 : * @retval -EALREADY The previous channel is the same as the requested
1567 : * channel.
1568 : * @retval -EINVAL The given channel is not within the range of valid
1569 : * channels of the driver's current channel page, see the
1570 : * IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES driver attribute.
1571 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1572 : * temporarily cannot be executed without blocking.
1573 : * @retval -ENOTSUP The given channel is within the range of valid
1574 : * channels of the driver's current channel page but unsupported by the
1575 : * current driver.
1576 : * @retval -EIO The channel could not be set.
1577 : */
1578 1 : int (*set_channel)(const struct device *dev, uint16_t channel);
1579 :
1580 : /**
1581 : * @brief Set/Unset PAN ID, extended or short address filters.
1582 : *
1583 : * @note requires IEEE802154_HW_FILTER capability.
1584 : *
1585 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1586 : * return -EIO unless the interface is either "UP" or "DOWN".
1587 : *
1588 : * @param dev pointer to IEEE 802.15.4 driver device
1589 : * @param set true to set the filter, false to remove it
1590 : * @param type the type of entity to be added/removed from the filter
1591 : * list (a PAN ID or a source/destination address)
1592 : * @param filter the entity to be added/removed from the filter list
1593 : *
1594 : * @retval 0 The filter was successfully added/removed.
1595 : * @retval -EINVAL The given filter entity or filter entity type
1596 : * was not valid.
1597 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1598 : * temporarily cannot be executed without blocking.
1599 : * @retval -ENOTSUP Setting/removing this filter or filter type
1600 : * is not supported by this driver.
1601 : * @retval -EIO Error while setting/removing the filter.
1602 : */
1603 1 : int (*filter)(const struct device *dev,
1604 : bool set,
1605 : enum ieee802154_filter_type type,
1606 : const struct ieee802154_filter *filter);
1607 :
1608 : /**
1609 : * @brief Set TX power level in dbm
1610 : *
1611 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1612 : * return -EIO unless the interface is either "UP" or "DOWN".
1613 : *
1614 : * @param dev pointer to IEEE 802.15.4 driver device
1615 : * @param dbm TX power in dbm
1616 : *
1617 : * @retval 0 The TX power was successfully set.
1618 : * @retval -EINVAL The given dbm value is invalid or not supported by
1619 : * the driver.
1620 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1621 : * temporarily cannot be executed without blocking.
1622 : * @retval -EIO The TX power could not be set.
1623 : */
1624 1 : int (*set_txpower)(const struct device *dev, int16_t dbm);
1625 :
1626 : /**
1627 : * @brief Transmit a packet fragment as a single frame
1628 : *
1629 : * @details Depending on the level of offloading features supported by
1630 : * the driver, the frame MAY not be fully encrypted/authenticated or it
1631 : * MAY not contain an FCS. It is the responsibility of L2
1632 : * implementations to prepare the frame according to the offloading
1633 : * capabilities announced by the driver and to decide whether CCA,
1634 : * CSMA/CA, ACK or retransmission procedures need to be executed outside
1635 : * ("soft MAC") or inside ("hard MAC") the driver .
1636 : *
1637 : * All frames originating from L2 SHALL have all required IEs
1638 : * pre-allocated and pre-filled such that the driver does not have to
1639 : * parse and manipulate IEs at all. This includes ACK packets if the
1640 : * driver does not have the @ref IEEE802154_HW_RX_TX_ACK capability.
1641 : * Also see @ref IEEE802154_CONFIG_ENH_ACK_HEADER_IE for drivers that
1642 : * have the @ref IEEE802154_HW_RX_TX_ACK capability.
1643 : *
1644 : * IEs that cannot be prepared by L2 unless the TX time is known (e.g.
1645 : * CSL IE, Rendezvous Time IE, Time Correction IE, ...) SHALL be sent in
1646 : * any of the timed TX modes with appropriate timing information
1647 : * pre-filled in the IE such that drivers do not have to parse and
1648 : * manipulate IEs at all unless the frame is generated by the driver
1649 : * itself.
1650 : *
1651 : * In case any of the timed TX modes is supported and used (see @ref
1652 : * ieee802154_hw_caps and @ref ieee802154_tx_mode), the driver SHALL
1653 : * take responsibility of scheduling and sending the packet at the
1654 : * precise programmed time autonomously without further interaction by
1655 : * upper layers. The call to `tx()` will block until the package has
1656 : * either been sent successfully (possibly including channel acquisition
1657 : * and packet acknowledgment) or a terminal transmission error occurred.
1658 : * The driver SHALL sleep and keep power consumption to the lowest
1659 : * possible level until the scheduled transmission time arrives or
1660 : * during any other idle waiting time.
1661 : *
1662 : * @warning The driver SHALL NOT take ownership of the given network
1663 : * packet and frame (fragment) buffer. Any data required by the driver
1664 : * including the actual frame content must be read synchronously and
1665 : * copied internally if needed at a later time (e.g. the contents of IEs
1666 : * required for protocol configuration, states of frame counters,
1667 : * sequence numbers, etc). Both, the packet and the buffer MAY be
1668 : * re-used or released by upper layers immediately after the function
1669 : * returns.
1670 : *
1671 : * @note Implementations MAY **sleep** and will usually NOT be
1672 : * **isr-ok** - especially when timed TX, CSMA/CA, retransmissions,
1673 : * auto-ACK or any other offloading feature is supported that implies
1674 : * considerable idle waiting time. SHALL return `-ENETDOWN` unless the
1675 : * interface is "UP".
1676 : *
1677 : * @note The transmission occurs on the radio channel set by the call to
1678 : * `set_channel()`. However, if the `CONFIG_IEEE802154_SELECTIVE_TXCHANNEL`
1679 : * is set and the driver has the capability `IEEE802154_HW_SELECTIVE_TXCHANNEL`
1680 : * then the transmissions requested with `mode` IEEE802154_TX_MODE_TXTIME
1681 : * or `IEEE802154_TX_MODE_TXTIME_CCA` SHALL use the radio channel
1682 : * returned by `net_pkt_ieee802154_txchannel()` to transmit the packet
1683 : * and receive an ACK on that channel if the frame requested it. After
1684 : * the operation the driver should return to the channel set previously by
1685 : * `set_channel()` call.
1686 : * It is responsibility of an upper layer to set the required radio channel
1687 : * for the packet by a call to `net_pkt_set_ieee802154_txchannel()`.
1688 : * This feature allows CSL transmissions as stated in IEEE 802.15.4-2020
1689 : * chapter 6.12.2.7 CSL over multiple channels. This feature allows to perform
1690 : * a switch of the radio channel as late as possible before transmission without
1691 : * interrupting possible reception that could occur if separate `set_channel()`
1692 : * was called.
1693 : *
1694 : * @param dev pointer to IEEE 802.15.4 driver device
1695 : * @param mode the transmission mode, some of which require specific
1696 : * offloading capabilities.
1697 : * @param pkt pointer to the network packet to be transmitted.
1698 : * @param frag pointer to a network buffer containing a single fragment
1699 : * with the frame data to be transmitted
1700 : *
1701 : * @retval 0 The frame was successfully sent or scheduled. If the driver
1702 : * supports ACK offloading and the frame requested acknowledgment (AR bit
1703 : * set), this means that the packet was successfully acknowledged by its
1704 : * peer.
1705 : * @retval -EINVAL Invalid packet (e.g. an expected IE is missing or the
1706 : * encryption/authentication state is not as expected).
1707 : * @retval -EBUSY The frame could not be sent because the medium was
1708 : * busy (CSMA/CA or CCA offloading feature only).
1709 : * @retval -ENOMSG The frame was not confirmed by an ACK packet (TX ACK
1710 : * offloading feature only) or the received ACK packet was invalid.
1711 : * @retval -ENOBUFS The frame could not be scheduled due to missing
1712 : * internal resources (timed TX offloading feature only).
1713 : * @retval -ENETDOWN The interface is not "UP".
1714 : * @retval -ENOTSUP The given TX mode is not supported.
1715 : * @retval -EIO The frame could not be sent due to some unspecified
1716 : * driver error (e.g. the driver being busy).
1717 : */
1718 1 : int (*tx)(const struct device *dev, enum ieee802154_tx_mode mode,
1719 : struct net_pkt *pkt, struct net_buf *frag);
1720 :
1721 : /**
1722 : * @brief Start the device.
1723 : *
1724 : * @details Upper layers will assume the interface is "UP" if this
1725 : * operation returns with zero or `-EALREADY`. The interface is placed
1726 : * in receive mode before returning from this operation unless an RX
1727 : * slot has been configured (even if it lies in the past, see @ref
1728 : * IEEE802154_CONFIG_RX_SLOT).
1729 : *
1730 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1731 : * called in any interface state once the driver is fully initialized
1732 : * ("ready").
1733 : *
1734 : * @param dev pointer to IEEE 802.15.4 driver device
1735 : *
1736 : * @retval 0 The driver was successfully started.
1737 : * @retval -EALREADY The driver was already "UP".
1738 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1739 : * temporarily cannot be executed without blocking.
1740 : * @retval -EIO The driver could not be started.
1741 : */
1742 1 : int (*start)(const struct device *dev);
1743 :
1744 : /**
1745 : * @brief Stop the device.
1746 : *
1747 : * @details Upper layers will assume the interface is "DOWN" if this
1748 : * operation returns with zero or `-EALREADY`. The driver switches off
1749 : * the receiver before returning if it was previously on. The driver
1750 : * enters the lowest possible power mode after this operation is called.
1751 : * This MAY happen asynchronously (i.e. after the operation already
1752 : * returned control).
1753 : *
1754 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1755 : * called in any interface state once the driver is fully initialized
1756 : * ("ready").
1757 : *
1758 : * @param dev pointer to IEEE 802.15.4 driver device
1759 : *
1760 : * @retval 0 The driver was successfully stopped.
1761 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1762 : * temporarily cannot be executed without blocking.
1763 : * @retval -EALREADY The driver was already "DOWN".
1764 : * @retval -EIO The driver could not be stopped.
1765 : */
1766 1 : int (*stop)(const struct device *dev);
1767 :
1768 : #if defined(CONFIG_IEEE802154_CARRIER_FUNCTIONS)
1769 : /**
1770 : * @brief Start continuous carrier wave transmission.
1771 : *
1772 : * @details The method blocks until the interface has started to emit a
1773 : * continuous carrier. To leave this mode, `start()` or `stop()` should
1774 : * be called, which will put the driver back into the "UP" or "DOWN"
1775 : * states, respectively.
1776 : *
1777 : * @note Implementations MAY **sleep** and will usually NOT be
1778 : * **isr-ok**. MAY be called in any interface state once the driver is
1779 : * fully initialized ("ready").
1780 : *
1781 : * @param dev pointer to IEEE 802.15.4 driver device
1782 : *
1783 : * @retval 0 continuous carrier wave transmission started
1784 : * @retval -EALREADY The driver was already in "TESTING" state and
1785 : * emitting a continuous carrier.
1786 : * @retval -EIO not started
1787 : */
1788 : int (*continuous_carrier)(const struct device *dev);
1789 :
1790 : /**
1791 : * @brief Start modulated carrier wave transmission.
1792 : *
1793 : * @details When the radio is emitting modulated carrier signals, it
1794 : * blocks all transmissions on the selected channel.
1795 : * This function is to be called only during radio
1796 : * tests. Do not use it during normal device operation.
1797 : *
1798 : * @note Implementations MAY **sleep** and will usually NOT be
1799 : * **isr-ok**. MAY be called in any interface state once the driver is
1800 : * fully initialized ("ready").
1801 : *
1802 : * @param dev pointer to IEEE 802.15.4 driver device
1803 : * @param data Pointer to a buffer to modulate the carrier with.
1804 : * The first byte is the data length.
1805 : *
1806 : * @retval 0 modulated carrier wave transmission started
1807 : * @retval -EALREADY The driver was already in "TESTING" state and
1808 : * emitting a modulated carrier.
1809 : * @retval -EIO not started
1810 : */
1811 : int (*modulated_carrier)(const struct device *dev, const uint8_t *data);
1812 : #endif /* CONFIG_IEEE802154_CARRIER_FUNCTIONS */
1813 :
1814 : /**
1815 : * @brief Set or update driver configuration.
1816 : *
1817 : * @details The method blocks until the interface has been reconfigured
1818 : * atomically with respect to ongoing package reception, transmission or
1819 : * any other ongoing driver operation.
1820 : *
1821 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1822 : * called in any interface state once the driver is fully initialized
1823 : * ("ready"). Some configuration options may not be supported in all
1824 : * interface operational states, see the detailed specifications in @ref
1825 : * ieee802154_config_type. In this case the operation returns `-EACCES`.
1826 : *
1827 : * @param dev pointer to IEEE 802.15.4 driver device
1828 : * @param type the configuration type to be set
1829 : * @param config the configuration parameters to be set for the given
1830 : * configuration type
1831 : *
1832 : * @retval 0 configuration successful
1833 : * @retval -EINVAL The configuration parameters are invalid for the
1834 : * given configuration type.
1835 : * @retval -ENOTSUP The given configuration type is not supported by
1836 : * this driver.
1837 : * @retval -EACCES The given configuration type is supported by this
1838 : * driver but cannot be configured in the current interface operational
1839 : * state.
1840 : * @retval -ENOMEM The configuration cannot be saved due to missing
1841 : * memory resources.
1842 : * @retval -ENOENT The resource referenced in the configuration
1843 : * parameters cannot be found in the configuration.
1844 : * @retval -EWOULDBLOCK The operation is called from ISR context but
1845 : * temporarily cannot be executed without blocking.
1846 : * @retval -EIO An internal error occurred while trying to configure the
1847 : * given configuration parameter.
1848 : */
1849 1 : int (*configure)(const struct device *dev,
1850 : enum ieee802154_config_type type,
1851 : const struct ieee802154_config *config);
1852 :
1853 : /**
1854 : * @brief Run an energy detection scan.
1855 : *
1856 : * @note requires IEEE802154_HW_ENERGY_SCAN capability
1857 : *
1858 : * @note The radio channel must be set prior to calling this function.
1859 : *
1860 : * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1861 : * return `-ENETDOWN` unless the interface is "UP".
1862 : *
1863 : * @param dev pointer to IEEE 802.15.4 driver device
1864 : * @param duration duration of energy scan in ms
1865 : * @param done_cb function called when the energy scan has finished
1866 : *
1867 : * @retval 0 the energy detection scan was successfully scheduled
1868 : *
1869 : * @retval -EBUSY the energy detection scan could not be scheduled at
1870 : * this time
1871 : * @retval -EALREADY a previous energy detection scan has not finished
1872 : * yet.
1873 : * @retval -ENETDOWN The interface is not "UP".
1874 : * @retval -ENOTSUP This driver does not support energy scans.
1875 : * @retval -EIO The energy detection procedure could not be executed.
1876 : */
1877 1 : int (*ed_scan)(const struct device *dev,
1878 : uint16_t duration,
1879 : energy_scan_done_cb_t done_cb);
1880 :
1881 : /**
1882 : * @brief Get the current time in nanoseconds relative to the network
1883 : * subsystem's local uptime clock as represented by this network
1884 : * interface.
1885 : *
1886 : * See @ref net_time_t for semantic details.
1887 : *
1888 : * @note requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME
1889 : * capabilities. Implementations SHALL be **isr-ok** and MUST NOT
1890 : * **sleep**. MAY be called in any interface state once the driver is
1891 : * fully initialized ("ready").
1892 : *
1893 : * @param dev pointer to IEEE 802.15.4 driver device
1894 : *
1895 : * @return nanoseconds relative to the network subsystem's local clock,
1896 : * -1 if an error occurred or the operation is not supported
1897 : */
1898 1 : net_time_t (*get_time)(const struct device *dev);
1899 :
1900 : /**
1901 : * @brief Get the current estimated worst case accuracy (maximum ±
1902 : * deviation from the nominal frequency) of the network subsystem's
1903 : * local clock used to calculate tolerances and guard times when
1904 : * scheduling delayed receive or transmit radio operations.
1905 : *
1906 : * The deviation is given in units of PPM (parts per million).
1907 : *
1908 : * @note requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME
1909 : * capabilities.
1910 : *
1911 : * @note Implementations may estimate this value based on current
1912 : * operating conditions (e.g. temperature). Implementations SHALL be
1913 : * **isr-ok** and MUST NOT **sleep**. MAY be called in any interface
1914 : * state once the driver is fully initialized ("ready").
1915 : *
1916 : * @param dev pointer to IEEE 802.15.4 driver device
1917 : *
1918 : * @return current estimated clock accuracy in PPM
1919 : */
1920 1 : uint8_t (*get_sch_acc)(const struct device *dev);
1921 :
1922 : /**
1923 : * @brief Get the value of a driver specific attribute.
1924 : *
1925 : * @note This function SHALL NOT return any values configurable by the
1926 : * MAC (L2) layer. It is reserved to non-boolean (i.e. scalar or
1927 : * structured) attributes that originate from the driver implementation
1928 : * and cannot be directly or indirectly derived by L2. Boolean
1929 : * attributes SHALL be implemented as @ref ieee802154_hw_caps.
1930 : *
1931 : * @note Implementations SHALL be **isr-ok** and MUST NOT **sleep**. MAY
1932 : * be called in any interface state once the driver is fully initialized
1933 : * ("ready").
1934 : *
1935 : * @retval 0 The requested attribute is supported by the driver and the
1936 : * value can be retrieved from the corresponding @ref ieee802154_attr_value
1937 : * member.
1938 : *
1939 : * @retval -ENOENT The driver does not provide the requested attribute.
1940 : * The value structure has not been updated with attribute data. The
1941 : * content of the value attribute is undefined.
1942 : */
1943 1 : int (*attr_get)(const struct device *dev,
1944 : enum ieee802154_attr attr,
1945 : struct ieee802154_attr_value *value);
1946 : };
1947 :
1948 : /* Make sure that the network interface API is properly setup inside
1949 : * IEEE 802.15.4 driver API struct (it is the first one).
1950 : */
1951 : BUILD_ASSERT(offsetof(struct ieee802154_radio_api, iface_api) == 0);
1952 :
1953 : /** @} */
1954 :
1955 : /**
1956 : * @name IEEE 802.15.4 driver utils
1957 : * @{
1958 : */
1959 :
1960 : /** @cond INTERNAL_HIDDEN */
1961 : #define IEEE802154_AR_FLAG_SET (0x20)
1962 : /** INTERNAL_HIDDEN @endcond */
1963 :
1964 : /**
1965 : * @brief Check if the AR flag is set on the frame inside the given @ref
1966 : * net_pkt.
1967 : *
1968 : * @param frag A valid pointer on a net_buf structure, must not be NULL,
1969 : * and its length should be at least 1 byte (ImmAck frames are the
1970 : * shortest supported frames with 3 bytes excluding FCS).
1971 : *
1972 : * @return true if AR flag is set, false otherwise
1973 : */
1974 1 : static inline bool ieee802154_is_ar_flag_set(struct net_buf *frag)
1975 : {
1976 : return (*frag->data & IEEE802154_AR_FLAG_SET);
1977 : }
1978 :
1979 : /** @} */
1980 :
1981 : /**
1982 : * @name IEEE 802.15.4 driver callbacks
1983 : * @{
1984 : */
1985 :
1986 : /* TODO: Fix drivers to either unref the packet before they return NET_OK or to
1987 : * return NET_CONTINUE instead. See note below.
1988 : */
1989 : /**
1990 : * @brief IEEE 802.15.4 driver ACK handling callback into L2 that drivers must
1991 : * call when receiving an ACK package.
1992 : *
1993 : * @details The IEEE 802.15.4 standard prescribes generic procedures for ACK
1994 : * handling on L2 (MAC) level. L2 stacks therefore have to provides a
1995 : * fast and re-usable generic implementation of this callback for
1996 : * drivers to call when receiving an ACK packet.
1997 : *
1998 : * Note: This function is part of Zephyr's 802.15.4 stack driver -> L2
1999 : * "inversion-of-control" adaptation API and must be implemented by all
2000 : * IEEE 802.15.4 L2 stacks.
2001 : *
2002 : * @param iface A valid pointer on a network interface that received the packet
2003 : * @param pkt A valid pointer on a packet to check
2004 : *
2005 : * @return NET_OK if L2 handles the ACK package, NET_CONTINUE or NET_DROP otherwise.
2006 : *
2007 : * @warning Deviating from other functions in the net stack returning
2008 : * net_verdict, this function will not unref the package even if it returns
2009 : * NET_OK.
2010 : */
2011 1 : extern enum net_verdict ieee802154_handle_ack(struct net_if *iface, struct net_pkt *pkt);
2012 :
2013 : /**
2014 : * @brief IEEE 802.15.4 driver initialization callback into L2 called by drivers
2015 : * to initialize the active L2 stack for a given interface.
2016 : *
2017 : * @details Drivers must call this function as part of their own initialization
2018 : * routine.
2019 : *
2020 : * Note: This function is part of Zephyr's 802.15.4 stack driver -> L2
2021 : * "inversion-of-control" adaptation API and must be implemented by all
2022 : * IEEE 802.15.4 L2 stacks.
2023 : *
2024 : * @param iface A valid pointer on a network interface
2025 : */
2026 : #ifndef CONFIG_IEEE802154_RAW_MODE
2027 1 : extern void ieee802154_init(struct net_if *iface);
2028 : #else
2029 : #define ieee802154_init(_iface_)
2030 : #endif /* CONFIG_IEEE802154_RAW_MODE */
2031 :
2032 : /** @} */
2033 :
2034 : #ifdef __cplusplus
2035 : }
2036 : #endif
2037 :
2038 : /**
2039 : * @}
2040 : */
2041 :
2042 : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_ */
|
