Lines Matching +full:long +full:- +full:frame +full:- +full:rx +full:- +full:support
5 * SPDX-License-Identifier: Apache-2.0
12 * @note All references to the standard in this file cite IEEE 802.15.4-2020.
38 * @details This API provides a common representation of vendor-specific
44 * - a basic, mostly PHY-level driver API to be implemented by all drivers,
45 * - several optional MAC-level extension points to offload performance
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
53 * subprotocols (e.g. fast enough ACK packages, precise timing of timed TX/RX in
56 * Whether or not MAC-level offloading extension points need to be implemented
60 * @note All section, table and figure references are to the IEEE 802.15.4-2020
67 * @name IEEE 802.15.4-2020, Section 6: MAC functional description
90 * @name IEEE 802.15.4-2020, Section 8: MAC services
96 * is equal to zero, see sections 8.4.2, table 8-93, aBaseSlotDuration and
103 * table 8-93, aNumSuperframeSlots.
109 * equal to zero, see section 8.4.2, table 8-93, aBaseSuperframeDuration.
115 * MAC PIB attribute aUnitBackoffPeriod, see section 8.4.2, table 8-93, in symbol
123 * defined in section 8.4.3.1, table 8-94.
131 * @name IEEE 802.15.4-2020, Section 10: General PHY requirements
138 * @details A device driver must support the mandatory channel pages, frequency
144 * - The 2006 version of the standard had a read-only phyChannelsSupported PHY
150 * - In the 2020 version of the standard, 13 channel pages are explicitly
154 * (section 8.4.3.4, table 8-100) or channel page fields used in the SRM
156 * - ASK PHY (channel page one) was deprecated in the 2015 version of the
158 * channel page one disappeared as well or should be interpreted as O-QPSK now
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.
171 * Channel page zero supports the 2.4G channels of the O-QPSK PHY and
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
185 /** Formerly ASK PHY - deprecated in IEEE 802.15.4-2015 */
188 /** O-QPSK PHY - 868 MHz and 915 MHz bands, see section 10.1.3.3 */
191 /** CSS PHY - 2450 MHz band, see section 10.1.3.4 */
194 /** UWB PHY - SubG, low and high bands, see section 10.1.3.5 */
197 /** O-QPSK PHY - 780 MHz band, see section 10.1.3.2 */
200 /** reserved - not currently assigned */
203 /** MSK PHY - 780 MHz and 2450 MHz bands, see sections 10.1.3.6, 10.1.3.7 */
210 * SUN FSK/OFDM/O-QPSK PHYs - predefined bands, operating modes and
216 * SUN FSK/OFDM/O-QPSK PHYs - generic modulation and channel
221 /** O-QPSK PHY - 2380 MHz band, see section 10.1.3.10 */
299 * @name IEEE 802.15.4-2020, Section 11: PHY services
305 * table 11-1.
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.
317 * PHY PIB attribute aCcaTime, in PHY symbols, all PHYs except for SUN O-QPSK,
318 * see section 11.3, table 11-1.
327 * @name IEEE 802.15.4-2020, Section 12: O-QPSK PHY
331 /** O-QPSK 868Mhz band symbol period, see section 12.3.3 */
335 * O-QPSK 780MHz, 915MHz, 2380MHz and 2450MHz bands symbol period,
344 * @name IEEE 802.15.4-2020, Section 13: BPSK PHY
358 * @name IEEE 802.15.4-2020, Section 15: HRP UWB PHY
361 * (T_psym), see section 11.3, table 11-1 and section 15.2.5, table 15-4
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).
382 /** standard modes, see section 8.3.2, table 8-88. */
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,
412 * @name IEEE 802.15.4-2020, Section 19: SUN FSK PHY
416 /** SUN FSK 863Mhz and 915MHz band symbol periods, see section 19.1, table 19-1 */
456 * these features in case the driver does not support them natively.
461 * required delays in the 2.4 GHz band without hard MAC support.
464 /** Frame checksum verification supported */
473 /** CSMA-CA procedure supported on TX */
482 /** Sends ACK on RX if AR bit is set in RX pkt */
493 * - "Sleeping" is a well defined term in Zephyr related to internal
494 * power and thread management and different from "RX off" as
496 * - Currently all OT-capable drivers have the "sleep to TX"
500 * - The `start()`/`stop()` API of a net device controls the
502 * -ENETDOWN when calling `tx()` while their operational state is
505 * - A migration path has been defined in #63670 for actual removal of
514 /** Timed RX window scheduling supported */
523 /** Support for timed transmissions on selective channel.
526 * @ref IEEE802154_TX_MODE_TXTIME and @ref IEEE802154_TX_MODE_TXTIME_CCA support
544 /** @brief This and higher values are specific to the protocol- or driver-specific extensions. */
563 * An RX slot ended, requires @ref IEEE802154_HW_RXTIME.
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
572 /** RX failed event reasons, see @ref IEEE802154_EVENT_RX_FAILED */
576 /** Frame had invalid checksum */
612 /** Initial value of frame counter associated with the key, see section 9.4.3 */
614 /** Indicates if per-key frame counter should be used, see section 9.4.3 */
616 /** Key Identifier Mode, see section 9.4.2.3, Table 9-7 */
661 /** This and higher values are specific to the protocol- or driver-specific extensions. */
665 /** IEEE 802.15.4 Frame Pending Bit table address matching mode. */
679 * Indicates how the driver should set the Frame Pending bit in ACK
683 * specified. Otherwise, Frame Pending bit should be set to ``1`` (see
692 * Indicates whether to set ACK Frame Pending bit for specific address
693 * or not. Disabling the Frame Pending bit with no address provided
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,
738 * Sets the current MAC frame counter value associated with the
740 * section 9.5, table 9-8, secFrameCounter.
742 * @warning The frame counter MUST NOT be accepted if it is not
743 * strictly greater than the current frame counter associated with the
745 * replay protection provided by the frame counter may be compromised.
746 * Drivers SHALL return -EINVAL in case the configured frame counter
755 * Sets the current MAC frame counter value if the provided value is greater than
769 * Set or unset a radio reception window (RX slot). This can be used for
772 * @details The start and duration parameters of the RX slot are
774 * parameter of the RX slot is -1 then any previously configured RX
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
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
789 * asynchronously and automatically around the RX slot. The driver
790 * SHALL resume power just before the RX slot and suspend it again
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
798 * If the driver is "UP" while configuring an RX slot, the driver SHALL
801 * start of the RX slot. If the driver is "UP" while the RX slot is
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
826 * disables CSL on the device. If the driver does not support CSL, the
827 * configuration call SHALL return -ENOTSUP.
829 * See section 7.4.2.3 and section 8.4.3.6, table 8-104, macCslPeriod.
839 * transmitters". Also note that at this time, we do NOT support
847 * appropriate pre-filled CSL IE and the CSL phase set to an
849 * injected on-the-fly by the driver at runtime as outlined in 2.
861 * configured RX slot) nor SHALL a frame be transmitted concurrently.
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,
869 * the given expected RX time as follows:
871 * cslAnchorPointNs = last expected RX time
872 * + PHY-specific PHR duration in ns
874 * startOfMhrNs = start of MHR of the frame containing the
877 * cslPhase = (startOfMhrNs - cslAnchorPointNs)
882 * inject that IE on-the-fly into outgoing enhanced ACK frames if the
890 * SHR of a legitimate RX frame is guaranteed to land inside the
893 * To this avail, the last configured expected RX time plus an
895 * RX slot (not necessarily its center):
897 * expectedRxTimeNs_N = last expected RX time
898 * + N * (cslPeriod * 10 * PHY-specific symbol period in ns)
900 * expectedRxTimeNs_N - rxSlot_N.start == const for all N
903 * SHOULD validate the offset of the expected RX time inside each RX
906 * nevertheless accept and schedule the RX slot with a zero success
914 * | EXPECTED_RX_TIME (end of SFD of a perfectly timed RX frame
920 * -----------------------------------------------[-CSL channel sample ]----+
923 * +--------------------- loop ---------+
930 * ---------------------
939 * -----------------------------------------------[-CSL channel sample ]----+
942 * +--------------------- loop ---------+
952 * Configure a timepoint at which an RX frame is expected to arrive.
955 * the network subsystem's local clock at which an RX frame's end of SFD
962 * (e.g. TSCH, beacon-enabled PAN including DSME), low-energy (e.g.
965 * arrival time of a frame can be predicted within a well-defined time
969 * The "expected RX time" MAY be interpreted slightly differently
971 * - CSL phase (i.e. time to the next expected CSL transmission) or anchor
973 * derived by adding the PHY header duration to the expected RX time
977 * - In TSCH the expected RX time MAY be set to macTsRxOffset +
979 * the expected RX time minus actual arrival timestamp, see section
981 * - In ranging applications, time difference of arrival (TDOA) MAY be
983 * against the assumed synchronized time at which the ranging frame
990 * subtracting multiples of the RX period. See e.g. the CSL
1014 * the standard. IEs for all other frame types SHALL be provided by L2.
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
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)
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.
1049 * configured IE/address combinations or return -ENOMEM if no
1077 * support header IEs but that may change in the future.
1088 * Enable/disable RxOnWhenIdle MAC PIB attribute (Table 8-94).
1092 * to determine next radio state (false --> off, true --> receive) in the following
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
1097 * - ACK is not requested or transmission of ACK is not possible due to internal
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
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
1119 /** This and higher values are specific to the protocol- or driver-specific extensions. */
1124 * Configuring an RX slot with the start parameter set to this value will cancel
1125 * and delete any previously configured RX slot.
1127 #define IEEE802154_CONFIG_RX_SLOT_NONE -1LL
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
1192 * the RX window during which the receiver is expected
1197 * to -1 will cancel and delete any previously active rx
1203 * Nanosecond resolution duration of the RX window
1204 * relative to the above RX window start time during
1236 * figure 7-21
1240 * on-the-fly, see the list in @ref
1302 * support channel page four (HRP UWB).
1309 /** This and higher values are specific to the protocol- or
1310 * driver-specific extensions.
1331 * need to support channel page switching at runtime.
1338 * supported pages are modeled as a bitmap to support drivers
1345 * attribute phyCurrentPage, section 11.3, table 11-2) is
1346 * considered to be read-only, fixed and "well known" via the
1365 * often zero-based, fixed channel range.
1373 * ranges each. Some of these ranges are not zero-based or
1376 * * UWB PHYs often support partial channel ranges on the same
1381 * switching between sub-ranges within the same channel page
1389 * drivers need to support PRF switching at runtime.
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,
1418 * @retval -ENOENT if the attribute could not be resolved
1428 value->phy_supported_channel_pages = phy_supported_channel_page; in ieee802154_attr_get_channel_page_and_range()
1432 value->phy_supported_channels = phy_supported_channels; in ieee802154_attr_get_channel_page_and_range()
1436 return -ENOENT; in ieee802154_attr_get_channel_page_and_range()
1446 * vendor-specific driver hardware or firmware offers offloading opportunities.
1448 * @details While L1-level driver features are exclusively implemented by
1449 * drivers and MAY be mandatory to support certain application requirements, L2
1453 * driver-independent L2 layer for all L2/MAC features especially if these
1455 * existing in-tree drivers. If, however, a driver offers offloading
1459 * All drivers SHALL support two externally observable interface operational
1460 * states: "UP" and "DOWN". Drivers MAY additionally support a "TESTING"
1471 * after a call to `start()` returned zero or `-EALREADY`. Upper layers assume
1473 * `-EALREADY`.
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
1490 * start of the RX slot or until a scheduled packet needs to be transmitted.
1496 * `stop()` is called. If `continuous_carrier()` returns a non-zero value then
1499 * `-EALREADY`, upper layers will consider the interface to be in a
1504 * the "UP" state and return `-ENETDOWN` in any other state. See the
1505 * function-level API documentation below for further details.
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
1528 * @note Implementations SHALL be **isr-ok** and MUST NOT **sleep**. MAY
1539 * @brief Clear Channel Assessment - Check channel's activity
1541 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1542 * return -ENETDOWN unless the interface is "UP".
1547 * @retval -EBUSY The channel is busy.
1548 * @retval -EWOULDBLOCK The operation is called from ISR context but
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.
1559 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1560 * return -EIO unless the interface is either "UP" or "DOWN".
1566 * @retval -EALREADY The previous channel is the same as the requested
1568 * @retval -EINVAL The given channel is not within the range of valid
1571 * @retval -EWOULDBLOCK The operation is called from ISR context but
1573 * @retval -ENOTSUP The given channel is within the range of valid
1576 * @retval -EIO The channel could not be set.
1585 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1586 * return -EIO unless the interface is either "UP" or "DOWN".
1595 * @retval -EINVAL The given filter entity or filter entity type
1597 * @retval -EWOULDBLOCK The operation is called from ISR context but
1599 * @retval -ENOTSUP Setting/removing this filter or filter type
1601 * @retval -EIO Error while setting/removing the filter.
1611 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1612 * return -EIO unless the interface is either "UP" or "DOWN".
1618 * @retval -EINVAL The given dbm value is invalid or not supported by
1620 * @retval -EWOULDBLOCK The operation is called from ISR context but
1622 * @retval -EIO The TX power could not be set.
1627 * @brief Transmit a packet fragment as a single frame
1630 * the driver, the frame MAY not be fully encrypted/authenticated or it
1632 * implementations to prepare the frame according to the offloading
1638 * pre-allocated and pre-filled such that the driver does not have to
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
1663 * packet and frame (fragment) buffer. Any data required by the driver
1664 * including the actual frame content must be read synchronously and
1666 * required for protocol configuration, states of frame counters,
1668 * re-used or released by upper layers immediately after the function
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
1683 * and receive an ACK on that channel if the frame requested it. After
1688 * This feature allows CSL transmissions as stated in IEEE 802.15.4-2020
1699 * with the frame data to be transmitted
1701 * @retval 0 The frame was successfully sent or scheduled. If the driver
1702 * supports ACK offloading and the frame requested acknowledgment (AR bit
1705 * @retval -EINVAL Invalid packet (e.g. an expected IE is missing or the
1707 * @retval -EBUSY The frame could not be sent because the medium was
1709 * @retval -ENOMSG The frame was not confirmed by an ACK packet (TX ACK
1711 * @retval -ENOBUFS The frame could not be scheduled due to missing
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
1725 * operation returns with zero or `-EALREADY`. The interface is placed
1726 * in receive mode before returning from this operation unless an RX
1730 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1737 * @retval -EALREADY The driver was already "UP".
1738 * @retval -EWOULDBLOCK The operation is called from ISR context but
1740 * @retval -EIO The driver could not be started.
1748 * operation returns with zero or `-EALREADY`. The driver switches off
1754 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1761 * @retval -EWOULDBLOCK The operation is called from ISR context but
1763 * @retval -EALREADY The driver was already "DOWN".
1764 * @retval -EIO The driver could not be stopped.
1778 * **isr-ok**. MAY be called in any interface state once the driver is
1784 * @retval -EALREADY The driver was already in "TESTING" state and
1786 * @retval -EIO not started
1799 * **isr-ok**. MAY be called in any interface state once the driver is
1807 * @retval -EALREADY The driver was already in "TESTING" state and
1809 * @retval -EIO not started
1821 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. MAY be
1825 * ieee802154_config_type. In this case the operation returns `-EACCES`.
1833 * @retval -EINVAL The configuration parameters are invalid for the
1835 * @retval -ENOTSUP The given configuration type is not supported by
1837 * @retval -EACCES The given configuration type is supported by this
1840 * @retval -ENOMEM The configuration cannot be saved due to missing
1842 * @retval -ENOENT The resource referenced in the configuration
1844 * @retval -EWOULDBLOCK The operation is called from ISR context but
1846 * @retval -EIO An internal error occurred while trying to configure the
1860 * @note Implementations SHALL be **isr-ok** and MAY **sleep**. SHALL
1861 * return `-ENETDOWN` unless the interface is "UP".
1869 * @retval -EBUSY the energy detection scan could not be scheduled at
1871 * @retval -EALREADY a previous energy detection scan has not finished
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.
1889 * capabilities. Implementations SHALL be **isr-ok** and MUST NOT
1896 * -1 if an error occurred or the operation is not supported
1913 * **isr-ok** and MUST NOT **sleep**. MAY be called in any interface
1926 * MAC (L2) layer. It is reserved to non-boolean (i.e. scalar or
1931 * @note Implementations SHALL be **isr-ok** and MUST NOT **sleep**. MAY
1939 * @retval -ENOENT The driver does not provide the requested attribute.
1965 * @brief Check if the AR flag is set on the frame inside the given @ref
1976 return (*frag->data & IEEE802154_AR_FLAG_SET); in ieee802154_is_ar_flag_set()
1995 * fast and re-usable generic implementation of this callback for
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
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