Implemented FHSS expedited forwarding mode (#2606)

* FHSS: expedited forwarding state implemented

* FHSS WS: Unit tests for expedited forwarding

* MAC: enable FHSS expedited forwarding when data req with EF priority

* FHSS: macro EXPEDITED_FORWARDING_POLL_PERIOD to contain conversion to 50us slots

* Use macro with default poll period

Author: Jarkko Paso

nanostack/fhss_api.h

@@ -49,6 +49,7 @@ typedef struct fhss_callback fhss_callback_t;
 typedef enum {
     FHSS_UNSYNCHRONIZED,
     FHSS_SYNCHRONIZED,
+    FHSS_EXPEDITED_FORWARDING
 } fhss_states;
 
 /**

source/MAC/IEEE802_15_4/mac_mcps_sap.c

@@ -269,6 +269,10 @@ void mcps_sap_data_req_handler_ext(protocol_interface_rf_mac_setup_s *rf_mac_set
     switch (priority) {
         case MAC_DATA_EXPEDITE_FORWARD:
             buffer->priority = MAC_PD_DATA_EF_PRIORITY;
+            // Enable FHSS expedited forwarding
+            if (rf_mac_setup->fhss_api) {
+                rf_mac_setup->fhss_api->synch_state_set(rf_mac_setup->fhss_api, FHSS_EXPEDITED_FORWARDING, 0);
+            }
             break;
         case MAC_DATA_HIGH_PRIORITY:
             buffer->priority = MAC_PD_DATA_HIGH_PRIOTITY;

source/Service_Libs/fhss/fhss_ws.c

@@ -352,44 +352,51 @@ static void fhss_broadcast_handler(const fhss_api_t *fhss_api, uint16_t delay)
         fhss_ws_start_timer(fhss_structure, MS_TO_US(fhss_structure->ws->fhss_configuration.fhss_bc_dwell_interval) - ((int64_t) delay_us * fhss_structure->platform_functions.fhss_resolution_divider), fhss_broadcast_handler);
         fhss_structure->ws->is_on_bc_channel = true;
         next_channel = fhss_structure->ws->bc_channel = fhss_ws_calc_bc_channel(fhss_structure);
-
-        /* Start timer with random timeout to trigger broadcast TX queue poll event.
-         * Min random is 1/50 of the channel dwell interval.
-         * Max random is 3/4 of the channel dwell interval.
-         * Event timer resolution is 50us.
-         */
-        uint32_t bc_dwell_us = MS_TO_US(fhss_structure->ws->fhss_configuration.fhss_bc_dwell_interval);
-        uint16_t bc_min_random = (bc_dwell_us / 50) / 50;
-        uint16_t bc_max_random = (bc_dwell_us - (bc_dwell_us / 4)) / 50;
-        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, randLIB_get_random_in_range(bc_min_random, bc_max_random));
+        if (fhss_structure->ws->expedited_forwarding_enabled_us) {
+            eventOS_callback_timer_start(fhss_structure->fhss_event_timer, EXPEDITED_FORWARDING_POLL_PERIOD);
+        } else {
+            /* Start timer with random timeout to trigger broadcast TX queue poll event.
+             * Min random is 1/50 of the channel dwell interval.
+             * Max random is 3/4 of the channel dwell interval.
+             * Event timer resolution is 50us.
+             */
+            uint32_t bc_dwell_us = MS_TO_US(fhss_structure->ws->fhss_configuration.fhss_bc_dwell_interval);
+            uint16_t bc_min_random = (bc_dwell_us / 50) / 50;
+            uint16_t bc_max_random = (bc_dwell_us - (bc_dwell_us / 4)) / 50;
+            eventOS_callback_timer_start(fhss_structure->fhss_event_timer, randLIB_get_random_in_range(bc_min_random, bc_max_random));
+        }
     } else {
         fhss_structure->ws->unicast_start_time_us = fhss_structure->callbacks.read_timestamp(fhss_structure->fhss_api);
         uint32_t timeout = MS_TO_US(fhss_structure->ws->fhss_configuration.fhss_broadcast_interval - fhss_structure->ws->fhss_configuration.fhss_bc_dwell_interval);
         fhss_ws_start_timer(fhss_structure, timeout - (delay_us * fhss_structure->platform_functions.fhss_resolution_divider), fhss_broadcast_handler);
         fhss_structure->ws->is_on_bc_channel = false;
         // Should return to own (unicast) listening channel after broadcast channel
         next_channel = fhss_structure->rx_channel;
-        /* Start timer with random timeout to trigger unicast TX queue poll event.
-         * For hops 0,1,4,5,8,9,...
-         * Min random is 1/100 of the TX slot length.
-         * Max random is 1/5 of the TX slot length.
-         *
-         * For hops 2,3,6,7,10,11,...
-         * Min random is 1/100 of the TX slot length plus 0.5*TX slot length.
-         * Max random is 1/10 of the TX slot length plus 0.5*TX slot length.
-         * Event timer resolution is 50us.
-         */
-        // returns 1 if polling of TX queue is done on latter half of the TX slot
-        uint8_t own_tx_trig_slot = calc_own_tx_trig_slot(fhss_structure->own_hop);
-        uint32_t txrx_slot_length_us = MS_TO_US(fhss_structure->ws->txrx_slot_length_ms);
-        uint16_t uc_min_random = (((txrx_slot_length_us / 2) * own_tx_trig_slot) / 50) + ((txrx_slot_length_us / 100) / 50);
-        uint16_t uc_max_random = (((txrx_slot_length_us / 2) * own_tx_trig_slot) / 50) + ((txrx_slot_length_us / 5) / 50);
-        bool tx_allowed = fhss_ws_check_tx_allowed(fhss_structure);
-        if (!tx_allowed) {
-            uc_min_random += (txrx_slot_length_us) / 50;
-            uc_max_random += (txrx_slot_length_us) / 50;
+        if (fhss_structure->ws->expedited_forwarding_enabled_us) {
+            eventOS_callback_timer_start(fhss_structure->fhss_event_timer, EXPEDITED_FORWARDING_POLL_PERIOD);
+        } else {
+            /* Start timer with random timeout to trigger unicast TX queue poll event.
+             * For hops 0,1,4,5,8,9,...
+             * Min random is 1/100 of the TX slot length.
+             * Max random is 1/5 of the TX slot length.
+             *
+             * For hops 2,3,6,7,10,11,...
+             * Min random is 1/100 of the TX slot length plus 0.5*TX slot length.
+             * Max random is 1/10 of the TX slot length plus 0.5*TX slot length.
+             * Event timer resolution is 50us.
+             */
+            // returns 1 if polling of TX queue is done on latter half of the TX slot
+            uint8_t own_tx_trig_slot = calc_own_tx_trig_slot(fhss_structure->own_hop);
+            uint32_t txrx_slot_length_us = MS_TO_US(fhss_structure->ws->txrx_slot_length_ms);
+            uint16_t uc_min_random = (((txrx_slot_length_us / 2) * own_tx_trig_slot) / 50) + ((txrx_slot_length_us / 100) / 50);
+            uint16_t uc_max_random = (((txrx_slot_length_us / 2) * own_tx_trig_slot) / 50) + ((txrx_slot_length_us / 5) / 50);
+            bool tx_allowed = fhss_ws_check_tx_allowed(fhss_structure);
+            if (!tx_allowed) {
+                uc_min_random += (txrx_slot_length_us) / 50;
+                uc_max_random += (txrx_slot_length_us) / 50;
+            }
+            eventOS_callback_timer_start(fhss_structure->fhss_event_timer, randLIB_get_random_in_range(uc_min_random, uc_max_random));
         }
-        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, randLIB_get_random_in_range(uc_min_random, uc_max_random));
 
 #ifdef FHSS_CHANNEL_DEBUG
         tr_info("%"PRIu32" UC %u", fhss_structure->callbacks.read_timestamp(fhss_structure->fhss_api), fhss_structure->rx_channel);
@@ -438,9 +445,19 @@ static void fhss_event_timer_cb(int8_t timer_id, uint16_t slots)
         return;
     }
 
-    // No one would poll TX queue if schedule timers were not started. Start poll timer with 10ms (200*50us) interval.
-    if ((fhss_structure->ws->unicast_timer_running == false) && (fhss_structure->ws->broadcast_timer_running == false)) {
-        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, 200);
+    if (fhss_structure->ws->expedited_forwarding_enabled_us) {
+        if ((fhss_structure->callbacks.read_timestamp(fhss_structure->fhss_api) - fhss_structure->ws->expedited_forwarding_enabled_us) > S_TO_US(EXPEDITED_FORWARDING_PERIOD)) {
+            fhss_structure->ws->expedited_forwarding_enabled_us = 0;
+        }
+        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, EXPEDITED_FORWARDING_POLL_PERIOD);
+        if (fhss_structure->ws->is_on_bc_channel == true) {
+            queue_size = fhss_structure->callbacks.read_tx_queue_size(fhss_structure->fhss_api, true);
+        } else {
+            queue_size = fhss_structure->callbacks.read_tx_queue_size(fhss_structure->fhss_api, false);
+        }
+    } else if ((fhss_structure->ws->unicast_timer_running == false) && (fhss_structure->ws->broadcast_timer_running == false)) {
+        // No one would poll TX queue if schedule timers were not started. Start poll timer with default interval.
+        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, DEFAULT_POLL_PERIOD);
         queue_size = fhss_structure->callbacks.read_tx_queue_size(fhss_structure->fhss_api, false);
     } else {
         if (fhss_structure->ws->is_on_bc_channel == true) {
@@ -535,6 +552,16 @@ static int16_t fhss_ws_synch_state_set_callback(const fhss_api_t *api, fhss_stat
     if (!fhss_structure) {
         return -1;
     }
+    if (fhss_state == FHSS_EXPEDITED_FORWARDING) {
+        if (!fhss_structure->ws->expedited_forwarding_enabled_us) {
+            eventOS_callback_timer_start(fhss_structure->fhss_event_timer, EXPEDITED_FORWARDING_POLL_PERIOD);
+        }
+        fhss_structure->ws->expedited_forwarding_enabled_us = fhss_structure->callbacks.read_timestamp(fhss_structure->fhss_api);
+        if (!fhss_structure->ws->expedited_forwarding_enabled_us) {
+            fhss_structure->ws->expedited_forwarding_enabled_us++;
+        }
+        return 0;
+    }
     if (fhss_state == FHSS_SYNCHRONIZED) {
         uint32_t fhss_broadcast_interval = fhss_structure->ws->fhss_configuration.fhss_broadcast_interval;
         uint8_t fhss_bc_dwell_interval = fhss_structure->ws->fhss_configuration.fhss_bc_dwell_interval;
@@ -1139,9 +1166,9 @@ int fhss_ws_configuration_set(fhss_structure_t *fhss_structure, const fhss_ws_co
         channel_count_uc = channel_count_bc;
     }
 
-    // No one would poll TX queue if schedule timers were not started. Start poll timer with 10ms (200*50us) interval.
+    // No one would poll TX queue if schedule timers were not started. Start poll timer with default interval.
     if ((fhss_structure->ws->unicast_timer_running == false) && (fhss_structure->ws->broadcast_timer_running == false)) {
-        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, 200);
+        eventOS_callback_timer_start(fhss_structure->fhss_event_timer, DEFAULT_POLL_PERIOD);
     }
 
     fhss_structure->number_of_channels = fhss_configuration->channel_mask_size;

source/Service_Libs/fhss/fhss_ws.h

@@ -18,17 +18,23 @@
 #define FHSS_WS_H_
 
 // TX slot length is optimised to this packet length
-#define OPTIMAL_PACKET_LENGTH   500
+#define OPTIMAL_PACKET_LENGTH               500
 // Max TX/RX slot length in milliseconds. Is used when datarate is not given by PHY or calculated slot length exceeds maximum allowed.
-#define WS_TXRX_SLOT_LEN_MS_MAX         100
+#define WS_TXRX_SLOT_LEN_MS_MAX             100
 // Min TX/RX slot length in milliseconds. Is used when calculated slot length is under minimum allowed.
-#define WS_TXRX_SLOT_LEN_MS_MIN         13
+#define WS_TXRX_SLOT_LEN_MS_MIN             13
 // Default minimum broadcast synchronization interval in seconds
-#define DEFAULT_MIN_SYNCH_INTERVAL      60
+#define DEFAULT_MIN_SYNCH_INTERVAL          60
 // Drift compensation allowed if at least SYNCH_COMPENSATION_MIN_INTERVAL (seconds) since last synchronization
-#define SYNCH_COMPENSATION_MIN_INTERVAL 60
+#define SYNCH_COMPENSATION_MIN_INTERVAL     60
 // MAX compensation per received synchronization info in ns
-#define MAX_DRIFT_COMPENSATION_STEP     10
+#define MAX_DRIFT_COMPENSATION_STEP         10
+// Length of expedited forwarding period in seconds
+#define EXPEDITED_FORWARDING_PERIOD         5
+// TX poll interval for expedited forwarding in 50us slots
+#define EXPEDITED_FORWARDING_POLL_PERIOD    (5000 / 50)
+// TX poll interval used when channel schedules are not yet started (50us slots)
+#define DEFAULT_POLL_PERIOD    (10000 / 50)
 typedef struct fhss_ws fhss_ws_t;
 
 struct fhss_ws {
@@ -44,6 +50,7 @@ struct fhss_ws {
     uint8_t *tr51_output_table;
     uint32_t next_uc_timeout;
     uint32_t next_bc_timeout;
+    uint32_t expedited_forwarding_enabled_us;
     bool unicast_timer_running;
     bool broadcast_timer_running;
     bool is_on_bc_channel;

test/nanostack/unittest/service_libs/fhss_ws/fhsswstest.cpp

@@ -102,3 +102,8 @@ TEST(fhssws, test_fhss_ws_remove_parent)
 {
     CHECK(test_fhss_ws_remove_parent());
 }
+
+TEST(fhssws, test_fhss_event_timer_cb)
+{
+    CHECK(test_fhss_event_timer_cb());
+}

test/nanostack/unittest/service_libs/fhss_ws/test_fhss_ws.c

@@ -29,6 +29,7 @@
 #include "fhss_callbacks_stub.h"
 #include "fhss_platform_stub.h"
 #include "channel_functions_stub.h"
+#include "ns_timer_stub.h"
 
 #define VENDOR_CHANNEL          89
 #define DEFAULT_CHANNEL         99
@@ -980,3 +981,63 @@ bool test_fhss_ws_remove_parent()
     }
     return true;
 }
+
+bool test_fhss_event_timer_cb()
+{
+    fhss_api_t *fhss_api = test_generate_fhss_api();
+    fhss_ws_configuration_t fhss_configuration;
+    fhss_timer_t fhss_timer;
+    fhss_common_stub.bool_value = true;
+    channel_list_stub.uint8_value = 1;
+    nsdynmemlib_stub.returnCounter = 3;
+    ns_timer_stub.cb_counter = 1;
+    // Enabling FHSS will register the TX poll timer
+    if (fhss_ws_enable(fhss_api, &fhss_configuration, &fhss_timer) == NULL) {
+        return false;
+    }
+
+    fhss_common_stub.fhss_struct.ws->unicast_timer_running = true;
+    fhss_common_stub.fhss_struct.ws->broadcast_timer_running = true;
+    test_set_platform_api(&fhss_common_stub.fhss_struct.platform_functions);
+    fhss_platform_stub.remaining_slots_value = 200000;
+    fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
+    fhss_common_stub.fhss_struct.ws->txrx_slot_length_ms = 54;
+    fhss_callbacks_stub.uint8_value = 5;
+
+    // Test that timer is started with correct value for expedited forwarding
+    fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
+    fhss_callbacks_stub.uint32_value = 5000000;
+    ns_timer_stub.cb(1, 100);
+    if (ns_timer_stub.start_slots != EXPEDITED_FORWARDING_POLL_PERIOD) {
+        printf("Fail: Wrong EF poll timer start value: %u. Expected: %u\r\n", ns_timer_stub.start_slots, EXPEDITED_FORWARDING_POLL_PERIOD);
+        return false;
+    }
+
+    // Test that expedited forwarding is stopped after period is over
+    fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
+    fhss_callbacks_stub.uint32_value = fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us + (EXPEDITED_FORWARDING_PERIOD * 1000000) + 1;
+    ns_timer_stub.cb(1, 100);
+    if ((ns_timer_stub.start_slots != EXPEDITED_FORWARDING_POLL_PERIOD) || fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us) {
+        printf("Fail: Wrong EF stop value: %u. Expected: %u. EF enabled: %s\r\n", ns_timer_stub.start_slots, EXPEDITED_FORWARDING_POLL_PERIOD, fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us ? "true" : "false");
+        return false;
+    }
+    // Test that normal polling is started after expedited forwarding
+    ns_timer_stub.cb(1, 100);
+    if (ns_timer_stub.start_slots != ((fhss_common_stub.fhss_struct.ws->txrx_slot_length_ms * 2 * 1000) / 50)) {
+        printf("Fail: Wrong UC poll timer start value: %u. Expected: %u\r\n", ns_timer_stub.start_slots, ((fhss_common_stub.fhss_struct.ws->txrx_slot_length_ms * 2 * 1000) / 50));
+        return false;
+    }
+    // Test that on broadcast channel the poll timer is not restarted
+    fhss_common_stub.fhss_struct.ws->is_on_bc_channel = true;
+    ns_timer_stub.start_slots = 0xffff;
+    ns_timer_stub.cb(1, 100);
+    if (ns_timer_stub.start_slots != 0xffff) {
+        printf("Fail: Wrong BC poll timer start value: %u. Expected: %u\r\n", ns_timer_stub.start_slots, 0xffff);
+        return false;
+    }
+
+    free(fhss_common_stub.fhss_struct.ws->tr51_channel_table);
+    free(fhss_common_stub.fhss_struct.ws->tr51_output_table);
+    free(fhss_common_stub.fhss_struct.ws);
+    return true;
+}

test/nanostack/unittest/service_libs/fhss_ws/test_fhss_ws.h

@@ -39,6 +39,7 @@ bool test_fhss_ws_update_uc_channel_callback();
 bool test_fhss_unicast_handler();
 bool test_fhss_ws_set_parent();
 bool test_fhss_ws_remove_parent();
+bool test_fhss_event_timer_cb();
 
 #ifdef __cplusplus
 }

test/nanostack/unittest/stub/ns_timer_stub.c

@@ -52,6 +52,7 @@ int8_t ns_timer_sleep(void)
 
 int8_t eventOS_callback_timer_start(int8_t ns_timer_id, uint16_t slots)
 {
+    ns_timer_stub.start_slots = slots;
     return ns_timer_stub.int8_value;
 }
 

test/nanostack/unittest/stub/ns_timer_stub.h

@@ -24,6 +24,7 @@ extern "C" {
 typedef struct {
     int8_t int8_value;
     uint8_t cb_counter;
+    uint16_t start_slots;
     void (*cb)(int8_t, uint16_t);
 } ns_timer_stub_def;