Merge pull request ARMmbed#2030 from ARMmbed/IOTTHD-3340

Iotthd 3340

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
+    macMultiCSMAParameters = 0xfa,  /*<Multi CSMA parameters*/
     macRfConfiguration = 0xfb,      /*<RF channel configuration parameters*/
     macAcceptByPassUnknowDevice = 0xfc,  /*< Accept data trough MAC if packet is data can be authenticated by group key nad MIC. Security enforsment point must be handled carefully these packets */
     macLoadBalancingBeaconTx = 0xfd,  /*< Trig Beacon from load balance module periodic */
@@ -499,4 +500,14 @@ typedef struct mlme_poll_conf_s {
     uint8_t status;             /**< Status of Poll operation */
 } mlme_poll_conf_t;
 
+/**
+ * @brief struct mlme_multi_csma_ca_param_s Set multi CSMA-CA parameters
+ *
+ * Non standard extension to perform CCA multiple times before transmission
+ */
+typedef struct mlme_multi_csma_ca_s {
+    uint8_t number_of_csma_ca_periods;  /**< Number of CSMA-CA periods */
+    uint16_t multi_cca_interval;        /**< Length of the additional CSMA-CA period(s) in microseconds */
+} mlme_multi_csma_ca_param_t;
+
 #endif /* MLME_H_ */

nanostack/platform/arm_hal_phy.h

@@ -29,6 +29,11 @@
 extern "C" {
 #endif
 
+/** PHY_LINK_CCA_PREPARE status definitions */
+#define PHY_TX_NOT_ALLOWED  -1      /**< TX not allowed. Do not continue to CCA process. */
+#define PHY_TX_ALLOWED      0       /**< TX allowed. Continue to CCA process. */
+#define PHY_RESTART_CSMA    1       /**< Restart CSMA-CA timer. CSMA-CA period must be calculated using given backoff time (PHY_EXTENSION_SET_CSMA_PARAMETERS) */
+
 /** Interface states */
 typedef enum {
     PHY_INTERFACE_RESET,            /**< Reset PHY driver and set to idle. */
@@ -45,7 +50,8 @@ typedef enum {
     PHY_LINK_TX_SUCCESS,        /**< MAC TX complete. MAC will a make decision to enter wait ACK or TX done state. */
     PHY_LINK_TX_FAIL,           /**< Link TX process fail. */
     PHY_LINK_CCA_FAIL,          /**< RF link CCA process fail. */
-    PHY_LINK_CCA_PREPARE,       /**< RX Tx timeout prepare operation like channel switch to Tx channel from Receive one If operation fail must return not zero*/
+    PHY_LINK_CCA_OK,            /**< RF link CCA process ok. */
+    PHY_LINK_CCA_PREPARE,       /**< Prepare for CCA after CSMA-CA: changes to CCA channel and gives permission to TX. See PHY_LINK_CCA_PREPARE status definitions for return values */
 } phy_link_tx_status_e;
 
 /** Extension types */

source/6LoWPAN/ws/ws_bootstrap.c

@@ -1580,6 +1580,12 @@ int ws_bootstrap_set_rf_config(protocol_interface_info_entry_t *cur, phy_rf_chan
     set_request.value_pointer = &ack_wait_symbols;
     set_request.value_size = sizeof(ack_wait_symbols);
     cur->mac_api->mlme_req(cur->mac_api, MLME_SET, &set_request);
+    // Set multi CSMA-CA configuration
+    mlme_multi_csma_ca_param_t multi_csma_params = {WS_NUMBER_OF_CSMA_PERIODS, WS_CSMA_MULTI_CCA_INTERVAL};
+    set_request.attr = macMultiCSMAParameters;
+    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);
     return 0;
 }
 

source/6LoWPAN/ws/ws_common_defines.h

@@ -232,6 +232,11 @@ typedef struct ws_bs_ie {
  */
 #define WS_TACK_MAX_MS 5
 
+// With FHSS we need to check CCA twice on TX channel
+#define WS_NUMBER_OF_CSMA_PERIODS  1
+// Interval between two CCA checks
+#define WS_CSMA_MULTI_CCA_INTERVAL 1000
+
 /* Default FHSS timing information
  *
  */

source/MAC/IEEE802_15_4/mac_defines.h

@@ -219,6 +219,8 @@ typedef struct protocol_interface_rf_mac_setup {
     uint16_t mac_ack_wait_duration;
     uint8_t mac_mlme_retry_max;
     uint8_t aUnitBackoffPeriod;
+    uint8_t number_of_csma_ca_periods;  /**< Number of CSMA-CA periods */
+    uint16_t multi_cca_interval;        /**< Length of the additional CSMA-CA period(s) in microseconds */
     /* Indirect queue parameters */
     struct mac_pre_build_frame *indirect_pd_data_request_queue;
     arm_event_t mac_mcps_timer_event;

source/MAC/IEEE802_15_4/mac_mcps_sap.c

@@ -1828,6 +1828,13 @@ static int8_t mcps_pd_data_cca_trig(protocol_interface_rf_mac_setup_s *rf_ptr, m
             }
             cca_enabled = true;
         }
+        // Use double CCA check with FHSS for data packets only
+        if (rf_ptr->fhss_api && !rf_ptr->mac_ack_tx_active && !rf_ptr->active_pd_data_request->asynch_request) {
+            if ((buffer->tx_time - (rf_ptr->multi_cca_interval * (rf_ptr->number_of_csma_ca_periods - 1))) > mac_mcps_sap_get_phy_timestamp(rf_ptr)) {
+                buffer->csma_periods_left = rf_ptr->number_of_csma_ca_periods;
+                buffer->tx_time -= (rf_ptr->multi_cca_interval * (rf_ptr->number_of_csma_ca_periods - 1));
+            }
+        }
         mac_pd_sap_set_phy_tx_time(rf_ptr, buffer->tx_time, cca_enabled);
         if (mac_plme_cca_req(rf_ptr) != 0) {
             if (buffer->fcf_dsn.frametype == MAC_FRAME_ACK) {

source/MAC/IEEE802_15_4/mac_mcps_sap.h

@@ -57,6 +57,11 @@ typedef enum {
 #define MAC_SAP_TRIG_TX                 7
 #define MCPS_SAP_DATA_ACK_CNF_EVENT     8
 
+// Default number of CSMA-CA periods
+#define MAC_DEFAULT_NUMBER_OF_CSMA_PERIODS  1
+// Interval between two CCA checks
+#define MAC_DEFAULT_CSMA_MULTI_CCA_INTERVAL 1000
+
 /**
  * @brief struct mac_aux_security_header_t MAC auxiliarity security header structure
  * INTERNAL use only
@@ -126,6 +131,7 @@ typedef struct mac_pre_build_frame {
     uint8_t *mac_payload;
     uint8_t status;
     uint8_t asynch_channel;
+    uint8_t csma_periods_left;
     uint32_t tx_time;
     bool upper_layer_request;
     bool mac_allocated_payload_ptr: 1;

source/MAC/IEEE802_15_4/mac_mlme.c

@@ -724,6 +724,16 @@ static int8_t mac_mlme_handle_set_values(protocol_interface_rf_mac_setup_s *rf_m
     return -1;
 }
 
+static int8_t mac_mlme_set_multi_csma_parameters(protocol_interface_rf_mac_setup_s *rf_mac_setup, const mlme_set_t *set_req)
+{
+    mlme_multi_csma_ca_param_t multi_csma_params;
+    memcpy(&multi_csma_params, set_req->value_pointer, sizeof(mlme_multi_csma_ca_param_t));
+    rf_mac_setup->multi_cca_interval = multi_csma_params.multi_cca_interval;
+    rf_mac_setup->number_of_csma_ca_periods = multi_csma_params.number_of_csma_ca_periods;
+    tr_debug("Multi CSMA-CA, interval: %u, periods %u", rf_mac_setup->multi_cca_interval, rf_mac_setup->number_of_csma_ca_periods);
+    return 0;
+}
+
 int8_t mac_mlme_set_req(protocol_interface_rf_mac_setup_s *rf_mac_setup, const mlme_set_t *set_req)
 {
     if (!set_req || !rf_mac_setup || !rf_mac_setup->dev_driver || !rf_mac_setup->dev_driver->phy_driver) {
@@ -749,6 +759,8 @@ 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 macMultiCSMAParameters:
+            return mac_mlme_set_multi_csma_parameters(rf_mac_setup, set_req);
         case macRfConfiguration:
             rf_mac_setup->dev_driver->phy_driver->extension(PHY_EXTENSION_SET_RF_CONFIGURATION, (uint8_t *) set_req->value_pointer);
             mac_mlme_set_symbol_rate(rf_mac_setup);
@@ -1072,6 +1084,8 @@ protocol_interface_rf_mac_setup_s *mac_mlme_data_base_allocate(uint8_t *mac64, a
     entry->mac_interface_id = -1;
     entry->dev_driver = dev_driver;
     entry->aUnitBackoffPeriod = 20; //This can be different in some Platform 20 comes from 12-symbol turnaround and 8 symbol CCA read
+    entry->number_of_csma_ca_periods = MAC_DEFAULT_NUMBER_OF_CSMA_PERIODS;
+    entry->multi_cca_interval = MAC_DEFAULT_CSMA_MULTI_CCA_INTERVAL;
 
     if (mac_sec_mib_init(entry, storage_sizes) != 0) {
         mac_mlme_data_base_deallocate(entry);

source/MAC/IEEE802_15_4/mac_pd_sap.c

@@ -101,6 +101,10 @@ uint32_t mac_csma_backoff_get(protocol_interface_rf_mac_setup_s *rf_mac_setup)
         if (backoff_in_us < MIN_FHSS_CSMA_PERIOD_US) {
             backoff_in_us += MIN_FHSS_CSMA_PERIOD_US;
         }
+        // Backoff must be long enough to make multiple CCA checks
+        if (backoff_in_us < (uint32_t)(rf_mac_setup->multi_cca_interval * (rf_mac_setup->number_of_csma_ca_periods - 1))) {
+            backoff_in_us += ((rf_mac_setup->multi_cca_interval * (rf_mac_setup->number_of_csma_ca_periods - 1)) - backoff_in_us);
+        }
     }
     return backoff_in_us;
 }
@@ -405,17 +409,17 @@ static int8_t mac_data_interface_tx_done_cb(protocol_interface_rf_mac_setup_s *r
     if (status == PHY_LINK_CCA_PREPARE) {
 
         if (rf_ptr->mac_ack_tx_active) {
-            return 0;
+            return PHY_TX_ALLOWED;
         }
 
         if (mac_data_asynch_channel_switch(rf_ptr, rf_ptr->active_pd_data_request)) {
-            return 0;
+            return PHY_TX_ALLOWED;
         }
 
         if (rf_ptr->fhss_api) {
             mac_pre_build_frame_t *active_buf = rf_ptr->active_pd_data_request;
             if (!active_buf) {
-                return -1;
+                return PHY_TX_NOT_ALLOWED;
             }
 
             // Change to destination channel and write synchronization info to Beacon frames here
@@ -426,16 +430,21 @@ static int8_t mac_data_interface_tx_done_cb(protocol_interface_rf_mac_setup_s *r
             // When FHSS TX handle returns -1, transmission of the packet is currently not allowed -> restart CCA timer
             if (tx_handle_retval == -1) {
                 mac_sap_cca_fail_cb(rf_ptr);
-                return -2;
+                return PHY_TX_NOT_ALLOWED;
             }
             // When FHSS TX handle returns -3, we are trying to transmit broadcast packet on unicast channel -> push back
             // to queue by using CCA fail event
             if (tx_handle_retval == -3) {
                 mac_tx_done_state_set(rf_ptr, MAC_CCA_FAIL);
-                return -3;
+                return PHY_TX_NOT_ALLOWED;
             } else if (tx_handle_retval == -2) {
                 mac_tx_done_state_set(rf_ptr, MAC_UNKNOWN_DESTINATION);
-                return -2;
+                return PHY_TX_NOT_ALLOWED;
+            }
+            if (--active_buf->csma_periods_left > 0) {
+                active_buf->tx_time += rf_ptr->multi_cca_interval;
+                mac_pd_sap_set_phy_tx_time(rf_ptr, active_buf->tx_time, true);
+                return PHY_RESTART_CSMA;
             }
         }
 
@@ -497,6 +506,9 @@ static int8_t mac_data_interface_tx_done_cb(protocol_interface_rf_mac_setup_s *r
             mac_sap_cca_fail_cb(rf_ptr);
             break;
 
+        case PHY_LINK_CCA_OK:
+            break;
+
         case PHY_LINK_TX_FAIL:
             mac_sap_no_ack_cb(rf_ptr);
             break;

test/nanostack/unittest/mac/mac_pd_sap/test_mac_pd_sap.c

@@ -829,17 +829,18 @@ bool test_mac_cca_prepare_cb()
 
     memset(&test_packet, 0, sizeof(mac_pre_build_frame_t));
     rf_ptr.active_pd_data_request = &test_packet;
+    test_packet.csma_periods_left = 1;
     test_packet.fcf_dsn.frametype = FC_BEACON_FRAME;
     test_packet.asynch_request = false;
     fhss_callback_response = -1;
     ret = mac_pd_sap_data_cb(&rf_ptr, &phy_message);
-    if (ret != -2) {
+    if (ret != -1) {
         return false;
     }
     fhss_callback_response = -3;
     rf_ptr.macRfRadioTxActive = true;
     ret = mac_pd_sap_data_cb(&rf_ptr, &phy_message);
-    if (ret != -3) {
+    if (ret != -1) {
         return false;
     }