MAC: Implemented automatic CCA threshold (#2353)

* MAC: Implemented automatic CCA threshold

* WS bootstrap: Enable auto CCA threshold. Removed test API.

Author: Jarkko Paso

nanostack/mlme.h

@@ -264,6 +264,7 @@ typedef enum {
     macAutoRequestKeyIndex = 0x7b,  /*<The index of the key used for automatic data*/
     macDefaultKeySource = 0x7c,      /*<Default key source*/
     //NON standard extension
+    macCCAThresholdStart = 0xf4,    /*< Start automatic CCA threshold */
     macDevicePendingAckTrig = 0xf5, /*< Trig Pending ACK for Accepted Data packet for temporary neighbour */
     mac802_15_4Mode = 0xf6,         /*<IEEE 802.15.4 mode*/
     macDeviceDescriptionPanIDUpdate = 0xf7, /*<Thread pending link update case this will update device descrioton list pan-id to new one*/

nanostack/platform/arm_hal_phy.h

@@ -80,6 +80,7 @@ typedef enum {
     PHY_EXTENSION_FILTERING_SUPPORT, /**<  Return filtering modes that can be supported by the PHY driver. See phy_link_filters_e */
     PHY_EXTENSION_SET_TX_POWER, /**<  Set TX output power which is given as percentage of maximum. 0 is the lowest possible TX power and 100 is the highest possible TX power */
     PHY_EXTENSION_SET_CCA_THRESHOLD, /**<  Set CCA threshold which is given as percentage of maximum threshold. 0 is the lowest(strictest) possible threshold and 100 is the highest possible threshold */
+    PHY_EXTENSION_SET_CHANNEL_CCA_THRESHOLD, /**<  Set CCA threshold which is given as dBm. This value is set in PHY_LINK_CCA_PREPARE callback and PHY driver should update the CCA threshold configuration */
     PHY_EXTENSION_SET_802_15_4_MODE /**<  Set IEEE 802.15.4 mode as defined by phy_802_15_4_mode_t*/
 } phy_extension_type_e;
 

source/6LoWPAN/ws/ws_bootstrap.c

@@ -2099,6 +2099,12 @@ int ws_bootstrap_set_rf_config(protocol_interface_info_entry_t *cur, phy_rf_chan
     set_request.value_pointer = &multi_csma_params;
     set_request.value_size = sizeof(mlme_multi_csma_ca_param_t);
     cur->mac_api->mlme_req(cur->mac_api, MLME_SET, &set_request);
+    // Start automatic CCA threshold
+    uint8_t start_cca_thr[4] = {cur->ws_info->hopping_schdule.number_of_channels, CCA_DEFAULT_DBM, CCA_HIGH_LIMIT, CCA_LOW_LIMIT};
+    set_request.attr = macCCAThresholdStart;
+    set_request.value_pointer = &start_cca_thr;
+    set_request.value_size = sizeof(start_cca_thr);
+    cur->mac_api->mlme_req(cur->mac_api, MLME_SET, &set_request);
     return 0;
 }
 

source/6LoWPAN/ws/ws_common_defines.h

@@ -319,6 +319,14 @@ typedef struct ws_bs_ie {
 #warning "MAX frame retries set too low"
 #endif
 
+/*
+ * Automatic CCA threshold: default threshold and range in dBm.
+ */
+#define CCA_DEFAULT_DBM -85
+#define CCA_HIGH_LIMIT  -60
+#define CCA_LOW_LIMIT   -100
+
+
 /*
  * Config new version consistent filter period in 100ms periods
  */

source/6LoWPAN/ws/ws_test_api.c

@@ -23,7 +23,9 @@
 #include <net_ws_test.h>
 #include "fhss_config.h"
 #include "ws_management_api.h"
+#include "mac_api.h"
 #include "NWK_INTERFACE/Include/protocol.h"
+#include "6LoWPAN/MAC/mac_helper.h"
 #include "6LoWPAN/ws/ws_config.h"
 #include "6LoWPAN/ws/ws_common.h"
 #include "6LoWPAN/ws/ws_bbr_api_internal.h"

source/MAC/IEEE802_15_4/mac_cca_threshold.c

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2020, Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "string.h"
+#include "nsconfig.h"
+#include "ns_types.h"
+#include "ns_trace.h"
+#include "nsdynmemLIB.h"
+#include "MAC/IEEE802_15_4/mac_defines.h"
+#include "MAC/IEEE802_15_4/mac_cca_threshold.h"
+
+#define TRACE_GROUP "mcth"
+
+int8_t mac_cca_thr_init(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t number_of_channels, int8_t default_dbm, int8_t high_limit, int8_t low_limit)
+{
+    // No changes
+    if (rf_ptr->cca_threshold &&
+            (number_of_channels == rf_ptr->cca_threshold->number_of_channels) &&
+            (default_dbm == rf_ptr->cca_threshold->default_dbm) &&
+            (high_limit == rf_ptr->cca_threshold->high_limit) &&
+            (low_limit == rf_ptr->cca_threshold->low_limit)) {
+        return -1;
+    }
+    // Validate given dBm range. Default must be in between high and low limit.
+    if ((default_dbm > high_limit) || (default_dbm < low_limit)) {
+        return -1;
+    }
+    mac_cca_thr_deinit(rf_ptr);
+    rf_ptr->cca_threshold = ns_dyn_mem_alloc(sizeof(mac_cca_threshold_s));
+    if (!rf_ptr->cca_threshold) {
+        return -1;
+    }
+    rf_ptr->cca_threshold->ch_thresholds = ns_dyn_mem_alloc(number_of_channels);
+    if (!rf_ptr->cca_threshold->ch_thresholds) {
+        ns_dyn_mem_free(rf_ptr->cca_threshold);
+        rf_ptr->cca_threshold = 0;
+        return -1;
+    }
+    memset(rf_ptr->cca_threshold->ch_thresholds, default_dbm, number_of_channels);
+    rf_ptr->cca_threshold->high_limit = high_limit;
+    rf_ptr->cca_threshold->low_limit = low_limit;
+    rf_ptr->cca_threshold->default_dbm = default_dbm;
+    rf_ptr->cca_threshold->number_of_channels = number_of_channels;
+    tr_info("Initialized CCA threshold: %u, %i, %i, %i", number_of_channels, default_dbm, high_limit, low_limit);
+    return 0;
+}
+
+int8_t mac_cca_thr_deinit(protocol_interface_rf_mac_setup_s *rf_ptr)
+{
+    if (!rf_ptr->cca_threshold) {
+        return -1;
+    }
+    ns_dyn_mem_free(rf_ptr->cca_threshold->ch_thresholds);
+    ns_dyn_mem_free(rf_ptr->cca_threshold);
+    rf_ptr->cca_threshold = 0;
+    return 0;
+}
+
+int8_t mac_cca_thr_get_dbm(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel)
+{
+    if (!rf_ptr->cca_threshold) {
+        return CCA_FAILED_DBM;
+    }
+    return rf_ptr->cca_threshold->ch_thresholds[channel];
+}
+
+static int8_t mac_cca_thr_set_dbm(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel, int8_t dbm)
+{
+    if (rf_ptr->cca_threshold->ch_thresholds[channel] != dbm) {
+        rf_ptr->cca_threshold->ch_thresholds[channel] = dbm;
+        return 0;
+    }
+    return -1;
+}
+
+static int8_t mac_cca_thr_update_channel_threshold(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel, int8_t dbm)
+{
+    // Already on low limit
+    if (rf_ptr->cca_threshold->ch_thresholds[channel] == rf_ptr->cca_threshold->low_limit) {
+        return -1;
+    }
+    // Already using lower threshold
+    if (rf_ptr->cca_threshold->ch_thresholds[channel] <= (dbm - CCA_THRESHOLD_STEP)) {
+        return -1;
+    }
+    // Do not set below configured low limit
+    if ((dbm - CCA_THRESHOLD_STEP) < rf_ptr->cca_threshold->low_limit) {
+        return mac_cca_thr_set_dbm(rf_ptr, channel, rf_ptr->cca_threshold->low_limit);
+    }
+    return mac_cca_thr_set_dbm(rf_ptr, channel, dbm - CCA_THRESHOLD_STEP);
+}
+
+static int8_t mac_cca_thr_channel_failed(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel)
+{
+    // Already on high limit
+    if (rf_ptr->cca_threshold->ch_thresholds[channel] == rf_ptr->cca_threshold->high_limit) {
+        return -1;
+    }
+    // Do not set above configured high limit
+    if ((rf_ptr->cca_threshold->ch_thresholds[channel] + CCA_THRESHOLD_STEP) > rf_ptr->cca_threshold->high_limit) {
+        return mac_cca_thr_set_dbm(rf_ptr, channel, rf_ptr->cca_threshold->high_limit);
+    }
+    return mac_cca_thr_set_dbm(rf_ptr, channel, rf_ptr->cca_threshold->ch_thresholds[channel] + CCA_THRESHOLD_STEP);
+}
+
+int8_t mac_cca_threshold_update(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel, int8_t dbm)
+{
+    if (dbm == CCA_FAILED_DBM) {
+        if (mac_cca_thr_channel_failed(rf_ptr, channel)) {
+            return -1;
+        }
+    } else {
+        if (mac_cca_thr_update_channel_threshold(rf_ptr, channel, dbm)) {
+            return -1;
+        }
+    }
+    tr_debug("Channel %u CCA threshold to %i", channel, rf_ptr->cca_threshold->ch_thresholds[channel]);
+    return 0;
+}

source/MAC/IEEE802_15_4/mac_cca_threshold.h

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2020, Arm Limited and affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef MAC_CCA_THRESHOLD_H_
+#define MAC_CCA_THRESHOLD_H_
+
+#define CCA_THRESHOLD_STEP  1
+#define CCA_FAILED_DBM      0x7F
+
+typedef struct mac_cca_threshold {
+    int8_t *ch_thresholds;
+    int8_t high_limit;
+    int8_t low_limit;
+    int8_t default_dbm;
+    uint8_t number_of_channels;
+} mac_cca_threshold_s;
+
+/**
+ * @brief Initialize automatic CCA threshold.
+ * @param rf_ptr Pointer to MAC instance.
+ * @param number_of_channels Number of MAC channels.
+ * @param default_dbm Default threshold.
+ * @param high_limit Highest allowed CCA threshold.
+ * @param low_limit Lowest allowed CCA threshold.
+ * @return 0 Success, negative Failed.
+ */
+int8_t mac_cca_thr_init(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t number_of_channels, int8_t default_dbm, int8_t high_limit, int8_t low_limit);
+
+/**
+ * @brief Deinitialize automatic CCA threshold.
+ * @param rf_ptr Pointer to MAC instance.
+ * @return 0 Success, negative Not found.
+ */
+int8_t mac_cca_thr_deinit(protocol_interface_rf_mac_setup_s *rf_ptr);
+
+/**
+ * @brief Read CCA threshold of specific channel.
+ * @param channel Channel.
+ * @return CCA threshold (dBm), CCA_FAILED_DBM Feature not enabled.
+ */
+int8_t mac_cca_thr_get_dbm(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel);
+
+/**
+ * @brief Update CCA threshold of specific channel.
+ * @param channel Channel.
+ * @param dbm CCA threshold (dBm).
+ * @return 0 Updated, negative Already using this value.
+ */
+int8_t mac_cca_threshold_update(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel, int8_t dbm);
+
+#endif /* MAC_CCA_THRESHOLD_H_ */

source/MAC/IEEE802_15_4/mac_data_buffer.h

@@ -91,6 +91,7 @@ typedef struct mac_pre_build_frame {
     uint8_t csma_periods_left;
     uint8_t fhss_retry_count;
     uint8_t fhss_cca_retry_count;
+    uint16_t initial_tx_channel;
     uint32_t tx_time;
     bool upper_layer_request: 1;
     bool mac_allocated_payload_ptr: 1;

source/MAC/IEEE802_15_4/mac_defines.h

@@ -276,6 +276,7 @@ typedef struct protocol_interface_rf_mac_setup {
     struct arm_device_driver_list *tun_extension_rf_driver;
     /* End of API Control */
     struct mlme_scan_conf_s *mac_mlme_scan_resp;
+    struct mac_cca_threshold *cca_threshold;
     //beacon_join_priority_tx_cb *beacon_join_priority_tx_cb_ptr;
     struct mac_statistics_s *mac_statistics;
     /* FHSS API*/

source/MAC/IEEE802_15_4/mac_mcps_sap.c

@@ -45,6 +45,7 @@
 #include "MAC/IEEE802_15_4/mac_mcps_sap.h"
 #include "MAC/IEEE802_15_4/mac_header_helper_functions.h"
 #include "MAC/IEEE802_15_4/mac_indirect_data.h"
+#include "MAC/IEEE802_15_4/mac_cca_threshold.h"
 #include "MAC/rf_driver_storage.h"
 
 #include "sw_mac.h"
@@ -1196,6 +1197,9 @@ static void mac_mcps_sap_data_tasklet(arm_event_s *event)
         case MAC_MLME_SCAN_CONFIRM_HANDLER:
             mac_mlme_scan_confirmation_handle((protocol_interface_rf_mac_setup_s *) event->data_ptr);
             break;
+        case MAC_CCA_THR_UPDATE:
+            mac_cca_threshold_update((protocol_interface_rf_mac_setup_s *) event->data_ptr, event->event_data >> 8, (int8_t) event->event_data);
+            break;
         case MAC_SAP_TRIG_TX:
             mac_clear_active_event((protocol_interface_rf_mac_setup_s *) event->data_ptr, MAC_SAP_TRIG_TX);
             mac_mcps_trig_buffer_from_queue((protocol_interface_rf_mac_setup_s *) event->data_ptr);
@@ -1221,6 +1225,7 @@ mac_pre_build_frame_t *mcps_sap_prebuild_frame_buffer_get(uint16_t payload_size)
         return NULL;
     }
     memset(buffer, 0, sizeof(mac_pre_build_frame_t));
+    buffer->initial_tx_channel = 0xffff;
     buffer->aux_header.frameCounter = 0xffffffff;
     if (payload_size) {
         //Mac interlnal payload allocate
@@ -2255,6 +2260,25 @@ void mcps_sap_trig_tx(void *mac_ptr)
     }
 }
 
+void mac_cca_threshold_event_send(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t channel, int16_t dbm)
+{
+    // Return if feature is not initialized
+    if (!rf_ptr->cca_threshold) {
+        return;
+    }
+    uint16_t data = channel << 8 | (uint8_t) dbm;
+    arm_event_s event = {
+        .receiver = mac_tasklet_event_handler,
+        .sender = 0,
+        .event_id = 0,
+        .event_data = data,
+        .data_ptr = rf_ptr,
+        .event_type = MAC_CCA_THR_UPDATE,
+        .priority = ARM_LIB_LOW_PRIORITY_EVENT,
+    };
+
+    eventOS_event_send(&event);
+}
 
 void mac_generic_event_trig(uint8_t event_type, void *mac_ptr, bool low_latency)
 {

source/MAC/IEEE802_15_4/mac_mcps_sap.h

@@ -56,6 +56,7 @@ typedef enum {
 #define MAC_MLME_SCAN_CONFIRM_HANDLER   6
 #define MAC_SAP_TRIG_TX                 7
 #define MCPS_SAP_DATA_ACK_CNF_EVENT     8
+#define MAC_CCA_THR_UPDATE              9
 
 // Default number of CSMA-CA periods
 #define MAC_DEFAULT_NUMBER_OF_CSMA_PERIODS  1
@@ -142,4 +143,6 @@ uint32_t mac_mcps_sap_get_phy_timestamp(struct protocol_interface_rf_mac_setup *
 
 void mcps_pending_packet_counter_update_check(struct protocol_interface_rf_mac_setup *rf_mac_setup, mac_pre_build_frame_t *buffer);
 
+void mac_cca_threshold_event_send(struct protocol_interface_rf_mac_setup *rf_mac_setup, uint8_t channel, int16_t dbm);
+
 #endif /* MAC_IEEE802_15_4_MAC_MCPS_SAP_H_ */

source/MAC/IEEE802_15_4/mac_mlme.c

@@ -48,6 +48,7 @@
 #include "MAC/IEEE802_15_4/mac_timer.h"
 #include "MAC/IEEE802_15_4/mac_pd_sap.h"
 #include "MAC/IEEE802_15_4/mac_mcps_sap.h"
+#include "MAC/IEEE802_15_4/mac_cca_threshold.h"
 #include "MAC/virtual_rf/virtual_rf_defines.h"
 #include "MAC/rf_driver_storage.h"
 
@@ -806,6 +807,10 @@ int8_t mac_mlme_set_req(protocol_interface_rf_mac_setup_s *rf_mac_setup, const m
                 memcpy(rf_mac_setup->coord_long_address, set_req->value_pointer, 8);
             }
             return 0;
+        case macCCAThresholdStart:
+            pu8 = (uint8_t *) set_req->value_pointer;
+            mac_cca_thr_init(rf_mac_setup, *pu8, *((int8_t *)pu8 + 1), *((int8_t *)pu8 + 2), *((int8_t *)pu8 + 3));
+            return 0;
         case mac802_15_4Mode:
             pu8 = (uint8_t *) set_req->value_pointer;
             if (rf_mac_setup->current_mac_mode == *pu8) {
@@ -1097,6 +1102,7 @@ void mac_mlme_data_base_deallocate(struct protocol_interface_rf_mac_setup *rf_ma
         ns_dyn_mem_free(rf_mac->mac_beacon_payload);
 
         mac_sec_mib_deinit(rf_mac);
+        mac_cca_thr_deinit(rf_mac);
         ns_dyn_mem_free(rf_mac);
     }
 }