Mode switch PHY API (ARMmbed#2663)

Author: Jarkko Paso

nanostack/platform/arm_hal_phy.h

@@ -143,6 +143,7 @@ typedef struct phy_signal_info_s {
 typedef struct phy_csma_params {
     uint32_t backoff_time;           /**< CSMA Backoff us time before start CCA & TX. 0 should disable current backoff*/
     bool cca_enabled;                /**< True will affect CCA check false start TX direct after backoff */
+    bool mode_switch_phr;            /**< True - Frame is a mode switch PHR. In this case PHY driver should skip FCS and send two byte PHR as it is given by TX callback */
 } phy_csma_params_t;
 
 /** PHY modulation scheme */

source/MAC/IEEE802_15_4/mac_mcps_sap.c

@@ -2087,6 +2087,7 @@ int8_t mcps_generic_ack_build(protocol_interface_rf_mac_setup_s *rf_ptr, bool in
     phy_csma_params_t csma_params;
     csma_params.backoff_time = 0;
     csma_params.cca_enabled = false;
+    csma_params.mode_switch_phr = false;
     rf_ptr->dev_driver->phy_driver->extension(PHY_EXTENSION_SET_CSMA_PARAMETERS, (uint8_t *) &csma_params);
     if (rf_ptr->active_pd_data_request) {
         timer_mac_stop(rf_ptr);

source/MAC/IEEE802_15_4/mac_mode_switch.c

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2021, Pelion 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 "MAC/IEEE802_15_4/mac_defines.h"
+#include "MAC/IEEE802_15_4/mac_mode_switch.h"
+
+#define TRACE_GROUP "mswc"
+
+#define PHR_LEN 2
+
+
+int8_t ms_build_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t *data_ptr, uint8_t phy_mode_id)
+{
+    (void) rf_ptr, (void) phy_mode_id;
+    if (!data_ptr) {
+        return -1;
+    }
+
+    // - Write mode switch and PHY mode id fields
+    // - Calculate checksum
+    // - Calculate parity
+
+    // - With successful return value, MAC should start CSMA-CA for a mode switch PHR
+    return 0;
+}
+
+int8_t ms_parse_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, const uint8_t *data_ptr, uint16_t data_len)
+{
+    (void) rf_ptr;
+    if (data_len != PHR_LEN) {
+        return -1;
+    }
+    if (!data_ptr) {
+        return -1;
+    }
+    tr_info("Received mode switch PHR %s", trace_array(data_ptr, data_len));
+
+    // - Validate checksum
+    // - Validate parity
+    // - Read PHY mode id
+    // - Store current configuration
+    // - Resolve new configuration
+    // - Set new configuration
+    // - Set timer/timeout for waiting the frame with new PHY mode
+
+    // - With successful return value, MAC should not start new transmissions until a packet is received or reception timed out
+    return 0;
+}
+
+void ms_update_mode_switch_state(protocol_interface_rf_mac_setup_s *rf_ptr)
+{
+    (void) rf_ptr;
+    // MAC should call this after any transmission (TX done) and reception
+    // When mode switch PHR was sent, change new configuration here before transmitting data packet
+    // When data packet was sent, switch back to original configuration
+    // When packet was received in new configuration, switch back to original configuration
+    // When reception timeout occurs, switch back to original configuration
+}

source/MAC/IEEE802_15_4/mac_mode_switch.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2021, Pelion 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_MODE_SWITCH_H_
+#define MAC_MODE_SWITCH_H_
+
+/**
+ * @brief Build mode switch PHR.
+ * @param rf_ptr Pointer to MAC instance.
+ * @param data_ptr Pointer to data buffer.
+ * @param phy_mode_id Used PHY mode id.
+ * @return 0 - success, -1 - failure.
+ */
+int8_t ms_build_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t *data_ptr, uint8_t phy_mode_id);
+
+/**
+ * @brief Parse mode switch PHR.
+ * @param rf_ptr Pointer to MAC instance.
+ * @param data_ptr Pointer to data buffer.
+ * @param data_len Data length.
+ * @return 0 - mode switch PHR found, -1 - mode switch PHR not found.
+ */
+int8_t ms_parse_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, const uint8_t *data_ptr, uint16_t data_len);
+
+#endif /* MAC_MODE_SWITCH_H_ */

source/MAC/IEEE802_15_4/mac_pd_sap.c

@@ -35,6 +35,7 @@
 #include "MAC/IEEE802_15_4/mac_filter.h"
 #include "MAC/IEEE802_15_4/mac_mcps_sap.h"
 #include "MAC/IEEE802_15_4/mac_cca_threshold.h"
+#include "MAC/IEEE802_15_4/mac_mode_switch.h"
 #include "MAC/rf_driver_storage.h"
 #include "Core/include/ns_monitor.h"
 #include "ns_trace.h"
@@ -232,6 +233,7 @@ void mac_pd_abort_active_tx(protocol_interface_rf_mac_setup_s *rf_mac_setup)
     phy_csma_params_t csma_params;
     // Set TX time to 0 to abort current transmission
     csma_params.backoff_time = 0;
+    csma_params.mode_switch_phr = false;
     rf_mac_setup->dev_driver->phy_driver->extension(PHY_EXTENSION_SET_CSMA_PARAMETERS, (uint8_t *) &csma_params);
 }
 
@@ -251,6 +253,7 @@ void mac_pd_sap_set_phy_tx_time(protocol_interface_rf_mac_setup_s *rf_mac_setup,
     phy_csma_params_t csma_params;
     csma_params.backoff_time = tx_time;
     csma_params.cca_enabled = cca_enabled;
+    csma_params.mode_switch_phr = false;
     rf_mac_setup->dev_driver->phy_driver->extension(PHY_EXTENSION_SET_CSMA_PARAMETERS, (uint8_t *) &csma_params);
 }
 
@@ -1040,6 +1043,11 @@ int8_t mac_pd_sap_data_cb(void *identifier, arm_phy_sap_msg_t *message)
             goto ERROR_HANDLER;
         }
 
+        if (!ms_parse_mode_switch_phr(rf_ptr, pd_data_ind->data_ptr, pd_data_ind->data_len)) {
+            // TODO: mode switch returned 0, needs some logic to wait frame with new mode
+            goto ERROR_HANDLER;
+        }
+
         if (pd_data_ind->data_len < 3) {
             return -1;
         }

sources.mk

@@ -83,6 +83,7 @@ SRCS += \
 	source/MAC/IEEE802_15_4/sw_mac.c \
 	source/MAC/IEEE802_15_4/mac_fhss_callbacks.c \
 	source/MAC/IEEE802_15_4/mac_cca_threshold.c \
+	source/MAC/IEEE802_15_4/mac_mode_switch.c \
 	source/MAC/ethernet/ethernet_mac_api.c \
 	source/MAC/serial/serial_mac_api.c \
 	source/MAC/virtual_rf/virtual_rf_client.c \

test/nanostack/unittest/mac/mac_pd_sap/Makefile

@@ -22,6 +22,7 @@ TEST_SRC_FILES = \
         ../../stub/mac_timer_stub.c \
         ../../stub/mac_filter_stub.c \
         ../../stub/mac_cca_threshold_stub.c \
+        ../../stub/mac_mode_switch_stub.c \
         ../../stub/randLIB_stub.c \
         ../../stub/mac_mlme_stub.c \
         ../../stub/buffer_dyn_stub.c \

test/nanostack/unittest/stub/mac_mode_switch_stub.c

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2021, Pelion 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 "nsconfig.h"
+#include <string.h>
+#include "ns_types.h"
+#include "ns_list.h"
+#include "ns_trace.h"
+#include "mac_defines.h"
+
+int8_t ms_build_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, uint8_t *data_ptr, uint8_t phy_mode_id)
+{
+    return 0;
+}
+
+int8_t ms_parse_mode_switch_phr(protocol_interface_rf_mac_setup_s *rf_ptr, const uint8_t *data_ptr, uint16_t data_len)
+{
+    return -1;
+}
+
+void ms_update_mode_switch_state(protocol_interface_rf_mac_setup_s *rf_ptr)
+{
+
+}