ieee802154_radio.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016 Intel Corporation.
 * Copyright (c) 2023 F. Grandel, Zephyr Project
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_
#define ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_
 
#include <zephyr/device.h>
#include <zephyr/net/net_if.h>
#include <zephyr/net/net_pkt.h>
#include <zephyr/net/net_time.h>
#include <zephyr/net/ieee802154.h>
#include <zephyr/sys/util.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define IEEE802154_PHY_SYMBOLS_PER_SECOND(symbol_period_ns) (NSEC_PER_SEC / symbol_period_ns)
 
#define IEEE802154_MAC_A_BASE_SLOT_DURATION 60U
 
#define IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS 16U
 
#define IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION                                                  \
        (IEEE802154_MAC_A_BASE_SLOT_DURATION * IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS)
 
#define IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD(turnaround_time)                                      \
        (turnaround_time + IEEE802154_PHY_A_CCA_TIME)
 
#define IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT 32U
 
enum ieee802154_phy_channel_page {
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_ZERO_OQPSK_2450_BPSK_868_915 = BIT(0),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_ONE_DEPRECATED = BIT(1),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWO_OQPSK_868_915 = BIT(2),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_THREE_CSS = BIT(3),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_FOUR_HRP_UWB = BIT(4),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_FIVE_OQPSK_780 = BIT(5),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_SIX_RESERVED = BIT(6),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_SEVEN_MSK = BIT(7),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_EIGHT_LRP_UWB = BIT(8),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_NINE_SUN_PREDEFINED = BIT(9),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_TEN_SUN_FSK_GENERIC = BIT(10),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_ELEVEN_OQPSK_2380 = BIT(11),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWELVE_LECIM = BIT(12),
 
        IEEE802154_ATTR_PHY_CHANNEL_PAGE_THIRTEEN_RCC = BIT(13),
};
 
struct ieee802154_phy_channel_range {
        uint16_t from_channel;
        uint16_t to_channel;
};
 
struct ieee802154_phy_supported_channels {
        const struct ieee802154_phy_channel_range *const ranges;
 
        const uint8_t num_ranges;
};
 
#define IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, from, to)                               \
        static const struct {                                                                      \
                const struct ieee802154_phy_channel_range phy_channel_range;                       \
                const struct ieee802154_phy_supported_channels phy_supported_channels;             \
        } drv_attr = {                                                                             \
                .phy_channel_range = {.from_channel = (from), .to_channel = (to)},                 \
                .phy_supported_channels =                                                          \
                        {                                                                          \
                                .ranges = &drv_attr.phy_channel_range,                             \
                                .num_ranges = 1U,                                                  \
                        },                                                                         \
        }
 
#define IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT 12U
 
#define IEEE802154_PHY_A_TURNAROUND_TIME_1MS(symbol_period_ns)                                     \
        DIV_ROUND_UP(NSEC_PER_MSEC, symbol_period_ns)
 
#define IEEE802154_PHY_A_CCA_TIME 8U
 
#define IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS         40000LL
 
#define IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS 16000LL
 
#define IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS 50000LL
 
#define IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS 25000LL
 
#define IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS  3974.36F
#define IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS 993.59F
#define IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS 1017.63F
#define IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS 729.17F
 
enum ieee802154_phy_hrp_uwb_nominal_prf {
        IEEE802154_PHY_HRP_UWB_PRF_OFF = 0,
        IEEE802154_PHY_HRP_UWB_NOMINAL_4_M = BIT(0),
        IEEE802154_PHY_HRP_UWB_NOMINAL_16_M = BIT(1),
        IEEE802154_PHY_HRP_UWB_NOMINAL_64_M = BIT(2),
 
        IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF = BIT(3),
        IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF = BIT(4),
        IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF = BIT(5),
};
 
#define IEEE802154_PHY_HRP_UWB_RDEV                                                                \
        (IEEE802154_PHY_HRP_UWB_NOMINAL_4_M | IEEE802154_PHY_HRP_UWB_NOMINAL_16_M |                \
         IEEE802154_PHY_HRP_UWB_NOMINAL_64_M)
 
#define IEEE802154_PHY_HRP_UWB_ERDEV                                                               \
        (IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF | IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF |    \
         IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF)
 
#define IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS 20000LL
 
#define IEEE802154_PHY_SUN_FSK_PHR_LEN 2
 
enum ieee802154_hw_caps {
 
        /*
         * PHY capabilities
         *
         * The following capabilities describe features of the underlying radio
         * hardware (PHY/L1).
         */
 
        IEEE802154_HW_ENERGY_SCAN = BIT(0),
 
        /*
         * MAC offloading capabilities (optional)
         *
         * The following MAC/L2 features may optionally be offloaded to
         * specialized hardware or proprietary driver firmware ("hard MAC").
         *
         * L2 implementations will have to provide a "soft MAC" fallback for
         * these features in case the driver does not support them natively.
         *
         * Note: Some of these offloading capabilities may be mandatory in
         * practice to stay within timing requirements of certain IEEE 802.15.4
         * protocols, e.g. CPUs may not be fast enough to send ACKs within the
         * required delays in the 2.4 GHz band without hard MAC support.
         */
 
        IEEE802154_HW_FCS = BIT(1),
 
        IEEE802154_HW_FILTER = BIT(2),
 
        IEEE802154_HW_PROMISC = BIT(3),
 
        IEEE802154_HW_CSMA = BIT(4),
 
        IEEE802154_HW_TX_RX_ACK = BIT(5),
 
        IEEE802154_HW_RETRANSMISSION = BIT(6),
 
        IEEE802154_HW_RX_TX_ACK = BIT(7),
 
        IEEE802154_HW_TXTIME = BIT(8),
 
        IEEE802154_HW_SLEEP_TO_TX = BIT(9),
 
        IEEE802154_HW_RXTIME = BIT(10),
 
        IEEE802154_HW_TX_SEC = BIT(11),
 
        /* Note: Update also IEEE802154_HW_CAPS_BITS_COMMON_COUNT when changing
         * the ieee802154_hw_caps type.
         */
};
 
#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT (12)
 
#define IEEE802154_HW_CAPS_BITS_PRIV_START IEEE802154_HW_CAPS_BITS_COMMON_COUNT
 
enum ieee802154_filter_type {
        IEEE802154_FILTER_TYPE_IEEE_ADDR,
        IEEE802154_FILTER_TYPE_SHORT_ADDR,
        IEEE802154_FILTER_TYPE_PAN_ID,
        IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR,
        IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR,
};
 
enum ieee802154_event {
        IEEE802154_EVENT_TX_STARTED,
        IEEE802154_EVENT_RX_FAILED,
        IEEE802154_EVENT_SLEEP,
};
 
enum ieee802154_rx_fail_reason {
        IEEE802154_RX_FAIL_NOT_RECEIVED,
        IEEE802154_RX_FAIL_INVALID_FCS,
        IEEE802154_RX_FAIL_ADDR_FILTERED,
        IEEE802154_RX_FAIL_OTHER
};
 
typedef void (*energy_scan_done_cb_t)(const struct device *dev,
                                      int16_t max_ed);
 
typedef void (*ieee802154_event_cb_t)(const struct device *dev,
                                      enum ieee802154_event evt,
                                      void *event_params);
 
struct ieee802154_filter {
        union {
                uint8_t *ieee_addr;
                uint16_t short_addr;
                uint16_t pan_id;
        };
};
 
struct ieee802154_key {
        uint8_t *key_value;
        uint32_t key_frame_counter;
        bool frame_counter_per_key;
        uint8_t key_id_mode;
        uint8_t key_index;
};
 
enum ieee802154_tx_mode {
        IEEE802154_TX_MODE_DIRECT,
 
        IEEE802154_TX_MODE_CCA,
 
        IEEE802154_TX_MODE_CSMA_CA,
 
        IEEE802154_TX_MODE_TXTIME,
 
        IEEE802154_TX_MODE_TXTIME_CCA,
 
        IEEE802154_TX_MODE_COMMON_COUNT,
 
        IEEE802154_TX_MODE_PRIV_START = IEEE802154_TX_MODE_COMMON_COUNT,
};
 
enum ieee802154_fpb_mode {
        IEEE802154_FPB_ADDR_MATCH_THREAD,
 
        IEEE802154_FPB_ADDR_MATCH_ZIGBEE,
};
 
enum ieee802154_config_type {
        IEEE802154_CONFIG_AUTO_ACK_FPB,
 
        IEEE802154_CONFIG_ACK_FPB,
 
        IEEE802154_CONFIG_PAN_COORDINATOR,
 
        IEEE802154_CONFIG_PROMISCUOUS,
 
        IEEE802154_CONFIG_EVENT_HANDLER,
 
        IEEE802154_CONFIG_MAC_KEYS,
 
        IEEE802154_CONFIG_FRAME_COUNTER,
 
        IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER,
 
        IEEE802154_CONFIG_RX_SLOT,
 
        IEEE802154_CONFIG_CSL_PERIOD,
 
        IEEE802154_CONFIG_CSL_RX_TIME,
 
        IEEE802154_CONFIG_ENH_ACK_HEADER_IE,
 
        IEEE802154_CONFIG_COMMON_COUNT,
 
        IEEE802154_CONFIG_PRIV_START = IEEE802154_CONFIG_COMMON_COUNT,
};
 
#define IEEE802154_CONFIG_RX_SLOT_NONE -1LL
 
#define IEEE802154_CONFIG_RX_SLOT_OFF  0LL
 
struct ieee802154_config {
        union {
                struct {
                        bool enabled;
                        enum ieee802154_fpb_mode mode;
                } auto_ack_fpb;
 
                struct {
                        uint8_t *addr; /* in little endian for both, short and extended address */
                        bool extended;
                        bool enabled;
                } ack_fpb;
 
                bool pan_coordinator;
 
                bool promiscuous;
 
                ieee802154_event_cb_t event_handler;
 
                struct ieee802154_key *mac_keys;
 
                uint32_t frame_counter;
 
                struct {
                        net_time_t start;
 
                        net_time_t duration;
 
                        uint8_t channel;
                } rx_slot;
 
                uint32_t csl_period;
 
                net_time_t csl_rx_time;
 
                struct {
                        const uint8_t *data;
 
                        uint16_t data_len;
 
                        uint16_t short_addr;
 
                        const uint8_t *ext_addr;
                } ack_ie;
        };
};
 
enum ieee802154_attr {
        IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES,
 
        IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES,
 
        IEEE802154_ATTR_PHY_HRP_UWB_SUPPORTED_PRFS,
 
        IEEE802154_ATTR_COMMON_COUNT,
 
        IEEE802154_ATTR_PRIV_START = IEEE802154_ATTR_COMMON_COUNT,
};
 
struct ieee802154_attr_value {
        union {
                /* TODO: Implement configuration of phyCurrentPage once drivers
                 * need to support channel page switching at runtime.
                 */
                uint32_t phy_supported_channel_pages;
 
                const struct ieee802154_phy_supported_channels *phy_supported_channels;
 
                /* TODO: Allow the PRF to be configured for each TX call once
                 * drivers need to support PRF switching at runtime.
                 */
                uint32_t phy_hrp_uwb_supported_nominal_prfs;
        };
};
 
static inline int 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)
{
        switch (attr) {
        case IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES:
                value->phy_supported_channel_pages = phy_supported_channel_page;
                return 0;
 
        case IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES:
                value->phy_supported_channels = phy_supported_channels;
                return 0;
 
        default:
                return -ENOENT;
        }
}
 
struct ieee802154_radio_api {
        struct net_if_api iface_api;
 
        enum ieee802154_hw_caps (*get_capabilities)(const struct device *dev);
 
        int (*cca)(const struct device *dev);
 
        int (*set_channel)(const struct device *dev, uint16_t channel);
 
        int (*filter)(const struct device *dev,
                      bool set,
                      enum ieee802154_filter_type type,
                      const struct ieee802154_filter *filter);
 
        int (*set_txpower)(const struct device *dev, int16_t dbm);
 
        int (*tx)(const struct device *dev, enum ieee802154_tx_mode mode,
                  struct net_pkt *pkt, struct net_buf *frag);
 
        int (*start)(const struct device *dev);
 
        int (*stop)(const struct device *dev);
 
        int (*continuous_carrier)(const struct device *dev);
 
        int (*configure)(const struct device *dev,
                         enum ieee802154_config_type type,
                         const struct ieee802154_config *config);
 
        int (*ed_scan)(const struct device *dev,
                       uint16_t duration,
                       energy_scan_done_cb_t done_cb);
 
        net_time_t (*get_time)(const struct device *dev);
 
        uint8_t (*get_sch_acc)(const struct device *dev);
 
        int (*attr_get)(const struct device *dev,
                        enum ieee802154_attr attr,
                        struct ieee802154_attr_value *value);
};
 
/* Make sure that the network interface API is properly setup inside
 * IEEE 802.15.4 driver API struct (it is the first one).
 */
BUILD_ASSERT(offsetof(struct ieee802154_radio_api, iface_api) == 0);
 
#define IEEE802154_AR_FLAG_SET (0x20)
static inline bool ieee802154_is_ar_flag_set(struct net_buf *frag)
{
        return (*frag->data & IEEE802154_AR_FLAG_SET);
}
 
/* TODO: Fix drivers to either unref the packet before they return NET_OK or to
 * return NET_CONTINUE instead. See note below.
 */
extern enum net_verdict ieee802154_handle_ack(struct net_if *iface, struct net_pkt *pkt);
 
#ifndef CONFIG_IEEE802154_RAW_MODE
extern void ieee802154_init(struct net_if *iface);
#else
#define ieee802154_init(_iface_)
#endif /* CONFIG_IEEE802154_RAW_MODE */
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_NET_IEEE802154_RADIO_H_ */