LCOV - code coverage report
Current view: top level - zephyr/net - ieee802154.h Coverage Total Hit
Test: new.info Lines: 100.0 % 39 39
Test Date: 2025-09-05 22:20:39

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2016 Intel Corporation.
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief IEEE 802.15.4 native L2 stack public header
      10              :  *
      11              :  * @note All references to the standard in this file cite IEEE 802.15.4-2020.
      12              :  */
      13              : 
      14              : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_H_
      15              : #define ZEPHYR_INCLUDE_NET_IEEE802154_H_
      16              : 
      17              : #include <limits.h>
      18              : #include <zephyr/net/net_l2.h>
      19              : #include <zephyr/net/net_mgmt.h>
      20              : #include <zephyr/crypto/cipher.h>
      21              : #include <zephyr/net/ieee802154_radio.h>
      22              : 
      23              : #ifdef __cplusplus
      24              : extern "C" {
      25              : #endif
      26              : 
      27              : /**
      28              :  * @defgroup ieee802154 IEEE 802.15.4 and Thread APIs
      29              :  * @since 1.0
      30              :  * @version 0.8.0
      31              :  * @ingroup connectivity
      32              :  *
      33              :  * @brief IEEE 802.15.4 native and OpenThread L2, configuration, management and
      34              :  * driver APIs
      35              :  *
      36              :  * @details The IEEE 802.15.4 and Thread subsystems comprise the OpenThread L2
      37              :  * subsystem, the native IEEE 802.15.4 L2 subsystem ("Soft" MAC), a mostly
      38              :  * vendor and protocol agnostic driver API shared between the OpenThread and
      39              :  * native L2 stacks ("Hard" MAC and PHY) as well as several APIs to configure
      40              :  * the subsystem (shell, net management, Kconfig, devicetree, etc.).
      41              :  *
      42              :  * The **OpenThread subsystem API** integrates the external <a
      43              :  * href="https://openthread.io">OpenThread</a> stack into Zephyr. It builds upon
      44              :  * Zephyr's native IEEE 802.15.4 driver API.
      45              :  *
      46              :  * The **native IEEE 802.15.4 subsystem APIs** are exposed at different levels
      47              :  * and address several audiences:
      48              :  *  - shell (end users, application developers):
      49              :  *    - a set of IEEE 802.15.4 shell commands (see `shell> ieee802154 help`)
      50              :  *  - application API (application developers):
      51              :  *    - IPv6, DGRAM and RAW sockets for actual peer-to-peer, multicast and
      52              :  *      broadcast data exchange between nodes including connection specific
      53              :  *      configuration (sample coming soon, see
      54              :  *      https://github.com/linux-wpan/wpan-tools/tree/master/examples for now
      55              :  *      which inspired our API and therefore has a similar socket API),
      56              :  *    - Kconfig and devicetree configuration options (net config library
      57              :  *      extension, subsystem-wide MAC and PHY Kconfig/DT options, driver/vendor
      58              :  *      specific Kconfig/DT options, watch out for options prefixed with
      59              :  *      IEEE802154/ieee802154),
      60              :  *    - Network Management: runtime configuration of the IEEE 802.15.4
      61              :  *      protocols stack at the MAC (L2) and PHY (L1) levels
      62              :  *      (see @ref ieee802154_mgmt),
      63              :  *  - L2 integration (subsystem contributors):
      64              :  *    - see @ref ieee802154_l2
      65              :  *    - implementation of Zephyr's internal L2-level socket and network context
      66              :  *      abstractions (context/socket operations, see @ref net_l2),
      67              :  *    - protocol-specific extension to the interface structure (see @ref net_if)
      68              :  *    - protocol-specific extensions to the network packet structure
      69              :  *      (see @ref net_pkt),
      70              :  *
      71              :  *  - OpenThread and native IEEE 802.15.4 share a common **driver API** (driver
      72              :  *    maintainers/contributors):
      73              :  *    - see @ref ieee802154_driver
      74              :  *    - a basic, mostly PHY-level driver API to be implemented by all drivers,
      75              :  *    - several "hard MAC" (hardware/firmware offloading) extension points for
      76              :  *      performance critical or timing sensitive aspects of the protocol
      77              :  */
      78              : 
      79              : /**
      80              :  * @defgroup ieee802154_l2 IEEE 802.15.4 L2
      81              :  * @since 1.0
      82              :  * @version 0.8.0
      83              :  * @ingroup ieee802154
      84              :  *
      85              :  * @brief IEEE 802.15.4 L2 APIs
      86              :  *
      87              :  * @details This API provides integration with Zephyr's sockets and network
      88              :  * contexts. **Application and driver developers should never interface directly
      89              :  * with this API.** It is of interest to subsystem maintainers only.
      90              :  *
      91              :  * The API implements and extends the following structures:
      92              :  *    - implements Zephyr's internal L2-level socket and network context
      93              :  *      abstractions (context/socket operations, see @ref net_l2),
      94              :  *    - protocol-specific extension to the interface structure (see @ref net_if)
      95              :  *    - protocol-specific extensions to the network packet structure
      96              :  *      (see @ref net_pkt),
      97              :  *
      98              :  * @note All section, table and figure references are to the IEEE 802.15.4-2020
      99              :  * standard.
     100              :  *
     101              :  * @{
     102              :  */
     103              : 
     104              : /**
     105              :  * @brief Represents the PHY constant aMaxPhyPacketSize, see section 11.3.
     106              :  *
     107              :  * @note Currently only 127 byte sized packets are supported although some PHYs
     108              :  * (e.g. SUN, MSK, LECIM, ...) support larger packet sizes. Needs to be changed
     109              :  * once those PHYs should be fully supported.
     110              :  */
     111            1 : #define IEEE802154_MAX_PHY_PACKET_SIZE  127
     112              : 
     113              : /**
     114              :  * @brief Represents the frame check sequence length, see section 7.2.1.1.
     115              :  *
     116              :  * @note Currently only a 2 byte FCS is supported although some PHYs (e.g. SUN,
     117              :  * TVWS, ...) optionally support a 4 byte FCS. Needs to be changed once those
     118              :  * PHYs should be fully supported.
     119              :  */
     120            1 : #define IEEE802154_FCS_LENGTH           2
     121              : 
     122              : /**
     123              :  * @brief IEEE 802.15.4 "hardware" MTU (not to be confused with L3/IP MTU), i.e.
     124              :  * the actual payload available to the next higher layer.
     125              :  *
     126              :  * @details This is equivalent to the IEEE 802.15.4 MAC frame length minus
     127              :  * checksum bytes which is again equivalent to the PHY payload aka PSDU length
     128              :  * minus checksum bytes. This definition exists for compatibility with the same
     129              :  * concept in Linux and Zephyr's L3. It is not a concept from the IEEE 802.15.4
     130              :  * standard.
     131              :  *
     132              :  * @note Currently only the original frame size from the 2006 standard version
     133              :  * and earlier is supported. The 2015+ standard introduced PHYs with larger PHY
     134              :  * payload. These are not (yet) supported in Zephyr.
     135              :  */
     136            1 : #define IEEE802154_MTU                  (IEEE802154_MAX_PHY_PACKET_SIZE - IEEE802154_FCS_LENGTH)
     137              : 
     138              : /* TODO: Support flexible MTU and FCS lengths for IEEE 802.15.4-2015ff */
     139              : 
     140              : /** IEEE 802.15.4 short address length. */
     141            1 : #define IEEE802154_SHORT_ADDR_LENGTH    2
     142              : 
     143              : /** IEEE 802.15.4 extended address length. */
     144            1 : #define IEEE802154_EXT_ADDR_LENGTH      8
     145              : 
     146              : /** IEEE 802.15.4 maximum address length. */
     147            1 : #define IEEE802154_MAX_ADDR_LENGTH      IEEE802154_EXT_ADDR_LENGTH
     148              : 
     149              : /**
     150              :  * A special channel value that symbolizes "all" channels or "any" channel -
     151              :  * depending on context.
     152              :  */
     153            1 : #define IEEE802154_NO_CHANNEL           USHRT_MAX
     154              : 
     155              : /**
     156              :  * Represents the IEEE 802.15.4 broadcast short address, see sections 6.1 and
     157              :  * 8.4.3, table 8-94, macShortAddress.
     158              :  */
     159            1 : #define IEEE802154_BROADCAST_ADDRESS         0xffff
     160              : 
     161              : /**
     162              :  * Represents a special IEEE 802.15.4 short address that indicates that a device
     163              :  * has been associated with a coordinator but did not receive a short address,
     164              :  * see sections 6.4.1 and 8.4.3, table 8-94, macShortAddress.
     165              :  */
     166            1 : #define IEEE802154_NO_SHORT_ADDRESS_ASSIGNED 0xfffe
     167              : 
     168              : /** Represents the IEEE 802.15.4 broadcast PAN ID, see section 6.1. */
     169            1 : #define IEEE802154_BROADCAST_PAN_ID 0xffff
     170              : 
     171              : /**
     172              :  * Represents a special value of the macShortAddress MAC PIB attribute, while the
     173              :  * device is not associated, see section 8.4.3, table 8-94.
     174              :  */
     175            1 : #define IEEE802154_SHORT_ADDRESS_NOT_ASSOCIATED IEEE802154_BROADCAST_ADDRESS
     176              : 
     177              : /**
     178              :  * Represents a special value of the macPanId MAC PIB attribute, while the
     179              :  * device is not associated, see section 8.4.3, table 8-94.
     180              :  */
     181            1 : #define IEEE802154_PAN_ID_NOT_ASSOCIATED        IEEE802154_BROADCAST_PAN_ID
     182              : 
     183              : /** Interface-level security attributes, see section 9.5. */
     184            1 : struct ieee802154_security_ctx {
     185              :         /**
     186              :          * Interface-level outgoing frame counter, section 9.5, table 9-8,
     187              :          * secFrameCounter.
     188              :          *
     189              :          * Only used when the driver does not implement key-specific frame
     190              :          * counters.
     191              :          */
     192            1 :         uint32_t frame_counter;
     193              : 
     194              :         /** @cond INTERNAL_HIDDEN */
     195              :         struct cipher_ctx enc;
     196              :         struct cipher_ctx dec;
     197              :         /** INTERNAL_HIDDEN @endcond */
     198              : 
     199              :         /**
     200              :          * @brief Interface-level frame encryption security key material
     201              :          *
     202              :          * @details Currently native L2 only supports a single secKeySource, see
     203              :          * section 9.5, table 9-9, in combination with secKeyMode zero (implicit
     204              :          * key mode), see section 9.4.2.3, table 9-7.
     205              :          *
     206              :          * @warning This is no longer in accordance with the 2015+ versions of
     207              :          * the standard and needs to be extended in the future for full security
     208              :          * procedure compliance.
     209              :          */
     210            1 :         uint8_t key[16];
     211              : 
     212              :         /** Length in bytes of the interface-level security key material. */
     213            1 :         uint8_t key_len;
     214              : 
     215              :         /**
     216              :          * @brief Frame security level, possible values are defined in section
     217              :          * 9.4.2.2, table 9-6.
     218              :          *
     219              :          * @warning Currently native L2 allows to configure one common security
     220              :          * level for all frame types, commands and information elements. This is
     221              :          * no longer in accordance with the 2015+ versions of the standard and
     222              :          * needs to be extended in the future for full security procedure
     223              :          * compliance.
     224              :          */
     225            1 :         uint8_t level   : 3;
     226              : 
     227              :         /**
     228              :          * @brief Frame security key mode
     229              :          *
     230              :          * @details Currently only implicit key mode is partially supported, see
     231              :          * section 9.4.2.3, table 9-7, secKeyMode.
     232              :          *
     233              :          * @warning This is no longer in accordance with the 2015+ versions of
     234              :          * the standard and needs to be extended in the future for full security
     235              :          * procedure compliance.
     236              :          */
     237            1 :         uint8_t key_mode        : 2;
     238              : 
     239              :         /** @cond INTERNAL_HIDDEN */
     240              :         uint8_t _unused : 3;
     241              :         /** INTERNAL_HIDDEN @endcond */
     242              : };
     243              : 
     244              : /** @brief IEEE 802.15.4 device role */
     245            1 : enum ieee802154_device_role {
     246              :         IEEE802154_DEVICE_ROLE_ENDDEVICE,       /**< End device */
     247              :         IEEE802154_DEVICE_ROLE_COORDINATOR,     /**< Coordinator */
     248              :         IEEE802154_DEVICE_ROLE_PAN_COORDINATOR, /**< PAN coordinator */
     249              : };
     250              : 
     251              : /** IEEE 802.15.4 L2 context. */
     252            1 : struct ieee802154_context {
     253              :         /**
     254              :          * @brief PAN ID
     255              :          *
     256              :          * @details The identifier of the PAN on which the device is operating.
     257              :          * If this value is 0xffff, the device is not associated. See section
     258              :          * 8.4.3.1, table 8-94, macPanId.
     259              :          *
     260              :          * in CPU byte order
     261              :          */
     262            1 :         uint16_t pan_id;
     263              : 
     264              :         /**
     265              :          * @brief Channel Number
     266              :          *
     267              :          * @details The RF channel to use for all transmissions and receptions,
     268              :          * see section 11.3, table 11-2, phyCurrentChannel. The allowable range
     269              :          * of values is PHY dependent as defined in section 10.1.3.
     270              :          *
     271              :          * in CPU byte order
     272              :          */
     273            1 :         uint16_t channel;
     274              : 
     275              :         /**
     276              :          * @brief Short Address (in CPU byte order)
     277              :          *
     278              :          * @details Range:
     279              :          *  * 0x0000–0xfffd: associated, short address was assigned
     280              :          *  * 0xfffe: associated but no short address assigned
     281              :          *  * 0xffff: not associated (default),
     282              :          *
     283              :          * See section 6.4.1, table 6-4 (Usage of the shart address) and
     284              :          * section 8.4.3.1, table 8-94, macShortAddress.
     285              :          */
     286            1 :         uint16_t short_addr;
     287              : 
     288              :         /**
     289              :          * @brief Extended Address (in little endian)
     290              :          *
     291              :          * @details The extended address is device specific, usually permanently
     292              :          * stored on the device and immutable.
     293              :          *
     294              :          * See section 8.4.3.1, table 8-94, macExtendedAddress.
     295              :          */
     296            1 :         uint8_t ext_addr[IEEE802154_MAX_ADDR_LENGTH];
     297              : 
     298              :         /** Link layer address (in big endian) */
     299            1 :         struct net_linkaddr linkaddr;
     300              : 
     301              : #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
     302              :         /** Security context */
     303            1 :         struct ieee802154_security_ctx sec_ctx;
     304              : #endif
     305              : 
     306              : #ifdef CONFIG_NET_L2_IEEE802154_MGMT
     307              :         /** Pointer to scanning parameters and results, guarded by scan_ctx_lock */
     308            1 :         struct ieee802154_req_params *scan_ctx;
     309              : 
     310              :         /**
     311              :          * Used to maintain integrity of data for all fields in this struct
     312              :          * unless otherwise documented on field level.
     313              :          */
     314            1 :         struct k_sem scan_ctx_lock;
     315              : 
     316              :         /**
     317              :          * @brief Coordinator extended address
     318              :          *
     319              :          * @details see section 8.4.3.1, table 8-94, macCoordExtendedAddress,
     320              :          * the address of the coordinator through which the device is
     321              :          * associated.
     322              :          *
     323              :          * A value of zero indicates that a coordinator extended address is
     324              :          * unknown (default).
     325              :          *
     326              :          * in little endian
     327              :          */
     328            1 :         uint8_t coord_ext_addr[IEEE802154_MAX_ADDR_LENGTH];
     329              : 
     330              :         /**
     331              :          * @brief Coordinator short address
     332              :          *
     333              :          * @details see section 8.4.3.1, table 8-94, macCoordShortAddress, the
     334              :          * short address assigned to the coordinator through which the device is
     335              :          * associated.
     336              :          *
     337              :          * A value of 0xfffe indicates that the coordinator is only using its
     338              :          * extended address. A value of 0xffff indicates that this value is
     339              :          * unknown.
     340              :          *
     341              :          * in CPU byte order
     342              :          */
     343            1 :         uint16_t coord_short_addr;
     344              : #endif
     345              : 
     346              :         /** Transmission power in dBm. */
     347            1 :         int16_t tx_power;
     348              : 
     349              :         /** L2 flags */
     350            1 :         enum net_l2_flags flags;
     351              : 
     352              :         /**
     353              :          * @brief Data sequence number
     354              :          *
     355              :          * @details The sequence number added to the transmitted Data frame or
     356              :          * MAC command, see section 8.4.3.1, table 8-94, macDsn.
     357              :          */
     358            1 :         uint8_t sequence;
     359              : 
     360              :         /**
     361              :          * @brief Device Role
     362              :          *
     363              :          * @details See section 6.1: A device may be operating as end device
     364              :          * (0), coordinator (1), or PAN coordinator (2). If no device role is
     365              :          * explicitly configured then the device will be treated as an end
     366              :          * device.
     367              :          *
     368              :          * A value of 3 is undefined.
     369              :          *
     370              :          * Can be read/set via @ref ieee802154_device_role.
     371              :          */
     372            1 :         uint8_t device_role : 2;
     373              : 
     374              :         /** @cond INTERNAL_HIDDEN */
     375              :         uint8_t _unused : 5;
     376              :         /** INTERNAL_HIDDEN @endcond */
     377              : 
     378              :         /**
     379              :          * ACK requested flag, guarded by ack_lock
     380              :          */
     381            1 :         uint8_t ack_requested: 1;
     382              : 
     383              :         /** ACK expected sequence number, guarded by ack_lock */
     384            1 :         uint8_t ack_seq;
     385              : 
     386              :         /** ACK lock, guards ack_* fields */
     387            1 :         struct k_sem ack_lock;
     388              : 
     389              :         /**
     390              :          * @brief Context lock
     391              :          *
     392              :          * @details This lock guards all mutable context attributes unless
     393              :          * otherwise mentioned on attribute level.
     394              :          */
     395            1 :         struct k_sem ctx_lock;
     396              : };
     397              : 
     398              : /** @cond INTERNAL_HIDDEN */
     399              : 
     400              : /* L2 context type to be used with NET_L2_GET_CTX_TYPE */
     401              : #define IEEE802154_L2_CTX_TYPE  struct ieee802154_context
     402              : 
     403              : /** INTERNAL_HIDDEN @endcond */
     404              : 
     405              : #ifdef __cplusplus
     406              : }
     407              : #endif
     408              : 
     409              : /**
     410              :  * @}
     411              :  */
     412              : 
     413              : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_H_ */
        

Generated by: LCOV version 2.0-1