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