dect_net_l2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef DECT_NET_L2_H_
#define DECT_NET_L2_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <zephyr/net/net_if.h>
#include <zephyr/net/net_l2.h>
#include <zephyr/net/net_ip.h>
#include <zephyr/net/net_pkt.h>
 
#define DECT_MTU 1280
 
enum dect_status_values {
        DECT_STATUS_OK = 0x0000,
        DECT_STATUS_FAIL = 0x0001,
        DECT_STATUS_INVALID_PARAM = 0x0002,
        DECT_STATUS_NOT_ALLOWED = 0x0003,
        DECT_STATUS_NO_CONFIG = 0x0004,
        DECT_STATUS_RD_NOT_FOUND = 0x0005,
        DECT_STATUS_TEMP_FAILURE = 0x0006,
        DECT_STATUS_NO_RESOURCES = 0x0007,
        DECT_STATUS_NO_RESPONSE = 0x0008,
        DECT_STATUS_NW_REJECT = 0x0009,
        DECT_STATUS_NO_MEMORY = 0x000A,
        DECT_STATUS_NO_RSSI_RESULTS = 0x000B,
        DECT_STATUS_TX_TIMEOUT = 0x000C,
 
        DECT_STATUS_OS_ERROR = 0xFFFE,
 
        DECT_STATUS_UNKNOWN = 0xFFFF,
};
 
enum dect_nw_beacon_period {
        DECT_NW_BEACON_PERIOD_50MS = 0,
        DECT_NW_BEACON_PERIOD_100MS = 1,
        DECT_NW_BEACON_PERIOD_500MS = 2,
        DECT_NW_BEACON_PERIOD_1000MS = 3,
        DECT_NW_BEACON_PERIOD_1500MS = 4,
        DECT_NW_BEACON_PERIOD_2000MS = 5,
        DECT_NW_BEACON_PERIOD_4000MS = 6,
        /* rest are reserved */
};
 
enum dect_cluster_beacon_period {
        DECT_CLUSTER_BEACON_PERIOD_10MS = 0,
        DECT_CLUSTER_BEACON_PERIOD_50MS = 1,
        DECT_CLUSTER_BEACON_PERIOD_100MS = 2,
        DECT_CLUSTER_BEACON_PERIOD_500MS = 3,
        DECT_CLUSTER_BEACON_PERIOD_1000MS = 4,
        DECT_CLUSTER_BEACON_PERIOD_1500MS = 5,
        DECT_CLUSTER_BEACON_PERIOD_2000MS = 6,
        DECT_CLUSTER_BEACON_PERIOD_4000MS = 7,
        DECT_CLUSTER_BEACON_PERIOD_8000MS = 8,
        DECT_CLUSTER_BEACON_PERIOD_16000MS = 9,
        DECT_CLUSTER_BEACON_PERIOD_32000MS = 10,
        /* rest are reserved */
};
 
#define DECT_MAX_CHANNELS_IN_RSSI_SCAN     20
#define DECT_MAX_CHANNELS_IN_NETWORK_SCAN_REQ  20
#define DECT_MAX_ADDITIONAL_NW_BEACON_CHANNELS 3
 
struct dect_rssi_scan_params {
        uint8_t band;
        uint8_t frame_count_to_scan;
        uint8_t channel_count;
        uint16_t channel_list[DECT_MAX_CHANNELS_IN_RSSI_SCAN];
};
 
struct dect_scan_params {
        uint8_t band;
        uint8_t channel_count;
        uint16_t channel_list[DECT_MAX_CHANNELS_IN_NETWORK_SCAN_REQ];
        uint16_t channel_scan_time_ms;
};
 
enum dect_scan_result_evt_type {
        DECT_SCAN_RESULT_TYPE_CLUSTER_BEACON = 0,
        DECT_SCAN_RESULT_TYPE_NW_BEACON,
};
 
struct dect_network_beacon_data {
        uint16_t current_cluster_channel;
 
        uint16_t next_cluster_channel;
 
        uint8_t num_network_beacon_channels;
 
        uint16_t network_beacon_channels[DECT_MAX_ADDITIONAL_NW_BEACON_CHANNELS];
};
 
struct dect_rx_signal_info {
        uint8_t mcs;
        uint8_t transmit_power;
        int8_t rssi_2;
        int8_t snr;
};
 
struct dect_route_info {
        uint8_t route_cost;
        uint8_t application_sequence_number;
        uint32_t sink_address;
};
 
struct dect_scan_result_evt {
        enum dect_scan_result_evt_type beacon_type;
 
        uint16_t channel;
        uint16_t transmitter_short_rd_id;
        uint32_t transmitter_long_rd_id;
        uint32_t network_id;
 
        struct dect_rx_signal_info rx_signal_info;
 
        /* Network beacon data if beacon_type is DECT_SCAN_RESULT_TYPE_NW_BEACON. */
        struct dect_network_beacon_data network_beacon;
 
        bool has_route_info;
        struct dect_route_info route_info;
};
 
typedef void (*dect_scan_result_cb_t)(struct net_if *iface, enum dect_status_values status,
                                      struct dect_scan_result_evt *entry);
 
struct dect_associate_req_params {
        uint32_t target_long_rd_id;
};
 
struct dect_associate_rel_params {
        uint32_t target_long_rd_id;
};
 
#define DECT_CLUSTER_CHANNEL_ANY 0
 
struct dect_cluster_start_req_params {
        uint16_t channel;
};
 
struct dect_cluster_reconfig_req_params {
        uint16_t channel;
        int8_t max_beacon_tx_power_dbm;
        int8_t max_cluster_power_dbm;
        enum dect_cluster_beacon_period period;
};
 
struct dect_cluster_stop_req_params {
};
 
struct dect_neighbor_info_req_params {
        uint32_t long_rd_id;
};
struct dect_nw_beacon_start_req_params {
        uint16_t channel;
        uint8_t additional_ch_count;
        uint16_t additional_ch_list[DECT_MAX_ADDITIONAL_NW_BEACON_CHANNELS];
};
 
struct dect_nw_beacon_stop_req_params {
};
 
enum dect_association_reject_cause {
        DECT_ASSOCIATION_REJECT_CAUSE_NO_RADIO_CAPACITY = 0,
        DECT_ASSOCIATION_REJECT_CAUSE_NO_HW_CAPACITY = 1,
        DECT_ASSOCIATION_REJECT_CAUSE_CONFLICTED_SHORT_ID = 2,
        DECT_ASSOCIATION_REJECT_CAUSE_SECURITY_NEEDED = 3,
        DECT_ASSOCIATION_REJECT_CAUSE_OTHER_REASON = 5,
        DECT_ASSOCIATION_NO_RESPONSE = 6,
};
 
enum dect_association_reject_time {
        DECT_ASSOCIATION_REJECT_TIME_0S = 0,
        DECT_ASSOCIATION_REJECT_TIME_5S = 1,
        DECT_ASSOCIATION_REJECT_TIME_10S = 2,
        DECT_ASSOCIATION_REJECT_TIME_30S = 3,
        DECT_ASSOCIATION_REJECT_TIME_60S = 4,
        DECT_ASSOCIATION_REJECT_TIME_120S = 5,
        DECT_ASSOCIATION_REJECT_TIME_180S = 6,
        DECT_ASSOCIATION_REJECT_TIME_300S = 7,
        DECT_ASSOCIATION_REJECT_TIME_600S = 8,
};
 
enum dect_rssi_scan_result_verdict {
        DECT_RSSI_SCAN_VERDICT_UNKNOWN,
        DECT_RSSI_SCAN_VERDICT_FREE,
        DECT_RSSI_SCAN_VERDICT_POSSIBLE,
        DECT_RSSI_SCAN_VERDICT_BUSY,
};
 
struct dect_rssi_scan_result_data {
        uint16_t channel;
        enum dect_rssi_scan_result_verdict frame_subslot_verdicts[48];
        bool all_subslots_free;
        bool another_cluster_detected_in_channel;
        uint8_t scan_suitable_percent;
        uint8_t free_subslot_cnt;
        uint8_t possible_subslot_cnt;
        uint8_t busy_subslot_cnt;
 
        uint8_t busy_percentage;
 
};
 
struct dect_rssi_scan_result_evt {
        struct dect_rssi_scan_result_data rssi_scan_result;
};
 
enum dect_association_release_cause {
        DECT_RELEASE_CAUSE_CONNECTION_TERMINATION = 0,
        DECT_RELEASE_CAUSE_MOBILITY,
        DECT_RELEASE_CAUSE_LONG_INACTIVITY,
        DECT_RELEASE_CAUSE_INCOMPATIBLE_CONFIGURATION,
        DECT_RELEASE_CAUSE_INSUFFICIENT_HW_RESOURCES,
        DECT_RELEASE_CAUSE_INSUFFICIENT_RADIO_RESOURCES,
        DECT_RELEASE_CAUSE_BAD_RADIO_QUALITY,
        DECT_RELEASE_CAUSE_SECURITY_ERROR,
        DECT_RELEASE_CAUSE_OTHER_ERROR,
        DECT_RELEASE_CAUSE_OTHER_REASON,
        DECT_RELEASE_CAUSE_CUSTOM_RACH_RESOURCE_FAILURE,
};
 
struct dect_association_released_evt {
        uint32_t long_rd_id;
 
        enum dect_association_release_cause release_cause;
};
 
enum dect_neighbor_role {
        DECT_NEIGHBOR_ROLE_PARENT = 0,
        DECT_NEIGHBOR_ROLE_CHILD = 1,
};
 
enum dect_association_change_type {
        DECT_ASSOCIATION_CREATED = 0,
        DECT_ASSOCIATION_RELEASED = 1,
        DECT_ASSOCIATION_REQ_REJECTED = 2,
        DECT_ASSOCIATION_REQ_FAILED_MDM = 3,
};
 
struct dect_association_changed_evt {
        uint32_t long_rd_id;
 
        enum dect_neighbor_role neighbor_role;
 
        enum dect_association_change_type association_change_type;
 
        union {
                /* Valid if association_change_type is DECT_ASSOCIATION_RELEASED. */
                struct {
                        bool neighbor_initiated;
 
                        enum dect_association_release_cause release_cause;
                } association_released;
 
                /* Valid if association_change_type is DECT_ASSOCIATION_REQ_REJECTED. */
                struct {
                        enum dect_association_reject_cause reject_cause;
 
                        enum dect_association_reject_time reject_time;
                } association_req_rejected;
 
                /* Valid if association_change_type is DECT_ASSOCIATION_REQ_FAILED_MDM. */
                struct {
                        enum dect_status_values cause;
                } association_req_failed_mdm;
        };
};
 
struct dect_cluster_start_resp_evt {
        enum dect_status_values status;
        uint16_t cluster_channel;
};
 
struct dect_network_status_evt {
        enum dect_network_status {
                DECT_NETWORK_STATUS_FAILURE,
                DECT_NETWORK_STATUS_CREATED,
                DECT_NETWORK_STATUS_REMOVED,
                DECT_NETWORK_STATUS_JOINED,
                DECT_NETWORK_STATUS_UNJOINED,
        } network_status;
        enum dect_status_values dect_err_cause;
        int os_err_cause;
};
 
struct dect_sink_status_evt {
        enum dect_sink_status {
                DECT_SINK_STATUS_CONNECTED,
                DECT_SINK_STATUS_DISCONNECTED,
        } sink_status;
        struct net_if *br_iface;
};
 
/* Note: change also CONFIG_NET_MGMT_EVENT_INFO_DEFAULT_DATA_SIZE
 * if changing dect_neighbor_list_evt.
 */
#define DECT_L2_MAX_NEIGHBOR_LIST_ITEM_COUNT 50
 
BUILD_ASSERT(CONFIG_NET_MGMT_EVENT_INFO_DEFAULT_DATA_SIZE >=
                     (DECT_L2_MAX_NEIGHBOR_LIST_ITEM_COUNT * sizeof(uint32_t) + sizeof(uint8_t) +
                      sizeof(int)),
             "CONFIG_NET_MGMT_EVENT_INFO_DEFAULT_DATA_SIZE too small");
 
struct dect_neighbor_list_evt {
        enum dect_status_values status;
        uint8_t neighbor_count;
        uint32_t neighbor_long_rd_ids[DECT_L2_MAX_NEIGHBOR_LIST_ITEM_COUNT];
};
 
struct dect_neighbor_info_evt {
        enum dect_status_values status;
        uint32_t long_rd_id;
 
        bool associated;
        bool ft_mode;
 
        uint16_t channel;
 
        uint32_t network_id;
 
        uint32_t time_since_last_rx_ms;
 
        struct dect_rx_signal_info last_rx_signal_info;
        int8_t beacon_average_rx_txpower;
        int16_t beacon_average_rx_rssi_2;
        int8_t beacon_average_rx_snr;
 
        struct dect_neighbor_status_info {
                uint8_t total_missed_cluster_beacons;
                uint8_t current_consecutive_missed_cluster_beacons;
                uint8_t num_rx_paging;
                uint8_t average_tx_mcs;
                int8_t average_tx_txpower;
                uint8_t average_rx_mcs;
                int8_t average_rx_txpower;
                int8_t average_rx_snr;
                int16_t average_rx_rssi_2;
                uint16_t num_tx_attempts;
                uint16_t num_lbt_failures;
                uint16_t num_rx_pdc;
                uint16_t num_rx_pdc_crc_failures;
                uint16_t num_no_response;
                uint16_t num_harq_ack;
                uint16_t num_harq_nack;
                uint16_t num_arq_retx;
                uint32_t inactive_time_ms;
        } status_info;
};
 
struct dect_cluster_info_evt {
        enum dect_status_values status;
 
        struct dect_cluster_status_info {
                uint16_t num_association_requests;
                uint16_t num_association_failures;
                uint16_t num_neighbors;
                uint16_t num_ftpt_neighbors;
                uint32_t num_rach_rx_pdc;
                uint32_t num_rach_rx_pcc_crc_failures;
                struct dect_rssi_scan_result_data rssi_result;
        } status_info;
};
 
struct dect_common_resp_evt {
        enum dect_status_values status;
};
 
typedef uint32_t dect_device_type_t;
 
#define DECT_DEVICE_TYPE_FT 0x01U  
#define DECT_DEVICE_TYPE_PT 0x02U  
enum dect_settings_cmd_params_write_scope {
        DECT_SETTINGS_WRITE_SCOPE_ALL = 0xFFFF,
        DECT_SETTINGS_WRITE_SCOPE_AUTO_START = 0x0001,
        DECT_SETTINGS_WRITE_SCOPE_REGION = 0x0002,
        DECT_SETTINGS_WRITE_SCOPE_DEVICE_TYPE = 0x0004,
        DECT_SETTINGS_WRITE_SCOPE_IDENTITIES = 0x0008,
        DECT_SETTINGS_WRITE_SCOPE_TX = 0x0010,
        DECT_SETTINGS_WRITE_SCOPE_POWER_SAVE = 0x0020,
        DECT_SETTINGS_WRITE_SCOPE_BAND_NBR = 0x0040,
        DECT_SETTINGS_WRITE_SCOPE_RSSI_SCAN = 0x0080,
        DECT_SETTINGS_WRITE_SCOPE_CLUSTER = 0x0100,
        DECT_SETTINGS_WRITE_SCOPE_NW_BEACON = 0x0200,
        DECT_SETTINGS_WRITE_SCOPE_ASSOCIATION = 0x0400,
        DECT_SETTINGS_WRITE_SCOPE_NETWORK_JOIN = 0x0800,
        DECT_SETTINGS_WRITE_SCOPE_SECURITY_CONFIGURATION = 0x1000,
};
 
struct dect_settings_cmd_params {
        bool reset_to_driver_defaults;
 
        /* Bitmask of dect_settings_cmd_params_write_scope */
        uint16_t write_scope_bitmap;
        /* Returned bitmask of dect_settings_cmd_params_write_scope for failed scopes,
         * in success zero.
         */
        uint16_t failure_scope_bitmap_out;
};
 
#define DECT_NW_BEACON_CHANNEL_NOT_USED UINT16_MAX
 
struct dect_settings_cluster {
        int8_t max_beacon_tx_power_dbm;
        int8_t max_cluster_power_dbm;
        enum dect_cluster_beacon_period beacon_period;
        uint16_t max_num_neighbors;
        uint32_t neighbor_inactivity_disconnect_timer_ms;
 
        uint8_t channel_loaded_percent;
};
 
struct dect_settings_network_beacon {
        uint16_t channel;
        enum dect_nw_beacon_period beacon_period;
};
 
struct dect_settings_association {
        uint8_t max_beacon_rx_failures;
 
        int8_t min_sensitivity_dbm;
};
 
struct dect_settings_auto_start {
        bool activate; /* if true, then auto-activate DECT NR+ stack on bootup */
};
 
#define DECT_SETT_NETWORK_JOIN_TARGET_FT_ANY 0
 
struct dect_settings_network_join {
        uint32_t target_ft_long_rd_id;
};
 
struct dect_settings_rssi_scan {
        uint8_t scan_suitable_percent;
 
        uint32_t time_per_channel_ms;
 
        int32_t free_threshold_dbm; /* if equal or less considered as free */
        /* rssi_scanning_busy_threshold <= possible < rssi_scanning_free_threshold*/
        int32_t busy_threshold_dbm; /* if higher considered as busy */
};
 
enum dect_settings_region {
        DECT_SETTINGS_REGION_EU = 0,
        DECT_SETTINGS_REGION_US = 1,
        DECT_SETTINGS_REGION_GLOBAL,
};
 
struct dect_settings_identities {
        uint32_t network_id;
 
        uint32_t transmitter_long_rd_id;
};
 
struct dect_settings_common_tx {
        int8_t max_power_dbm;
 
        uint8_t max_mcs;
};
 
#define DECT_INTEGRITY_KEY_LENGTH 16
#define DECT_CIPHER_KEY_LENGTH    16
 
enum dect_security_mode {
        DECT_SECURITY_MODE_NONE = 0,
        DECT_SECURITY_MODE_1 = 1,
};
 
struct dect_settings_security_conf {
        enum dect_security_mode mode;
 
        uint8_t integrity_key[DECT_INTEGRITY_KEY_LENGTH];
        uint8_t cipher_key[DECT_CIPHER_KEY_LENGTH];
};
 
struct dect_settings {
        struct dect_settings_cmd_params cmd_params;
 
        /* Auto-start settings. */
        struct dect_settings_auto_start auto_start;
 
        enum dect_settings_region region;
 
        dect_device_type_t device_type;
 
        struct dect_settings_identities identities;
 
        struct dect_settings_common_tx tx;
 
        bool power_save;
 
        uint8_t band_nbr;
 
        struct dect_settings_rssi_scan rssi_scan;
 
        struct dect_settings_cluster cluster;
 
        struct dect_settings_network_beacon nw_beacon;
 
        struct dect_settings_association association;
 
        struct dect_settings_network_join network_join;
 
        struct dect_settings_security_conf sec_conf;
};
 
struct dect_association_data {
        uint32_t long_rd_id;
 
        struct in6_addr local_ipv6_addr;
 
        bool global_ipv6_addr_set;
 
        struct in6_addr global_ipv6_addr;
};
 
struct dect_status_info {
 
        bool mdm_activated;
 
        bool cluster_running;
        uint16_t cluster_channel;
 
        bool nw_beacon_running;
 
        uint8_t parent_count;
        struct dect_association_data parent_associations[1];
 
        uint8_t child_count;
        struct dect_association_data
                child_associations[CONFIG_DECT_CLUSTER_MAX_CHILD_ASSOCIATION_COUNT];
 
        struct net_if *br_net_iface;
        bool br_global_ipv6_addr_prefix_set;
        struct in6_addr br_global_ipv6_addr_prefix;
        int br_global_ipv6_addr_prefix_len;
 
        char fw_version_str[100];
};
 
struct dect_nr_hal_api {
        struct net_if_api iface_api;
 
        int (*status_info_get)(const struct device *dev, struct dect_status_info *status_info_out);
 
        int (*settings_read)(const struct device *dev, struct dect_settings *settings_out);
 
        int (*settings_write)(const struct device *dev, struct dect_settings *settings_in);
 
        int (*activate_req)(const struct device *dev);
 
        int (*deactivate_req)(const struct device *dev);
 
        int (*rssi_scan)(const struct device *dev, struct dect_rssi_scan_params *params);
 
        int (*scan)(const struct device *dev, struct dect_scan_params *params,
                    dect_scan_result_cb_t cb);
 
        int (*associate_req)(const struct device *dev, struct dect_associate_req_params *params);
 
        int (*associate_release)(const struct device *dev,
                                 struct dect_associate_rel_params *params);
 
        int (*cluster_start_req)(const struct device *dev,
                                 struct dect_cluster_start_req_params *params);
 
        int (*cluster_reconfig_req)(const struct device *dev,
                                    struct dect_cluster_reconfig_req_params *params);
 
        int (*cluster_stop_req)(const struct device *dev,
                                struct dect_cluster_stop_req_params *params);
 
        int (*nw_beacon_start_req)(const struct device *dev,
                                   struct dect_nw_beacon_start_req_params *params);
 
        int (*nw_beacon_stop_req)(const struct device *dev,
                                  struct dect_nw_beacon_stop_req_params *params);
 
        int (*send)(const struct device *dev, struct net_pkt *pkt);
 
        int (*neighbor_list_req)(const struct device *dev);
 
        int (*neighbor_info_req)(const struct device *dev,
                                 struct dect_neighbor_info_req_params *params);
 
        int (*cluster_info_req)(const struct device *dev);
 
        int (*network_create_req)(const struct device *dev);
 
        int (*network_remove_req)(const struct device *dev);
 
        int (*network_join_req)(const struct device *dev);
 
        int (*network_unjoin_req)(const struct device *dev);
};
 
struct dect_net_ipv6_prefix_config {
        int prefix_len;
        struct in6_addr prefix;
};
 
struct dect_net_l2_context {
        enum net_l2_flags flags;
 
        dect_device_type_t device_type;
 
        uint32_t network_id;
 
        uint32_t transmitter_long_rd_id;
 
        struct dect_net_ipv6_prefix_config ipv6_prefix_cfg;
        struct in6_addr local_ipv6_addr;
        bool global_ipv6_addr_set;
        struct in6_addr global_ipv6_addr;
};
 
#define DECT_L2 DECT
NET_L2_DECLARE_PUBLIC(DECT_L2);
 
#define DECT_L2_CTX_TYPE struct dect_net_l2_context
 
void dect_net_l2_init(struct net_if *iface, struct dect_settings *driver_initial_settings);
 
void dect_net_l2_settings_changed(struct net_if *iface,
                                  struct dect_settings *driver_current_settings);
 
void dect_net_l2_parent_association_created(struct net_if *iface, uint32_t parent_long_rd_id,
                                            struct dect_net_ipv6_prefix_config *ipv6_prefix_config);
 
void dect_net_l2_child_association_created(struct net_if *iface, uint32_t target_long_rd_id);
 
void dect_net_l2_association_removed(struct net_if *iface, uint32_t long_rd_id,
                                     enum dect_association_release_cause cause,
                                     bool neighbor_initiated);
 
void dect_net_l2_parent_ipv6_config_changed(struct net_if *iface, uint32_t parent_long_rd_id,
                                            struct dect_net_ipv6_prefix_config *ipv6_prefix_config);
 
 #ifdef __cplusplus
}
#endif
 
#endif /* DECT_NET_L2_H_ */