fhss.h

00001 /*
00002  * Copyright (c) 2015-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef FHSS_H_
00018 #define FHSS_H_
00019 #include "ns_list.h"
00020 #define MAX_SCRAMBLE_TABLE_INDEXES  20
00021 
00022 // Lifetime is given as seconds
00023 #define BEACON_INFO_LIFETIME        600
00024 // Limits the number of synchronization info messages sent on broadcast channels
00025 #define MAX_SYNCH_INFOS_PER_CHANNEL_LIST    2
00026 // FHSS randomly selects the starting superframe for broadcast channel. This defines how many superframes are used for randomization.
00027 #define NUMBER_OF_BC_START_SUPERFRAMES  3
00028 
00029 #define FHSS_TASKLET_INIT_EVENT             0
00030 #define FHSS_TIMER_EVENT                    1
00031 #define FHSS_COMPARE_SYNCH_PARENT           2
00032 #define FHSS_BROADCAST_CHANNEL              3
00033 #define FHSS_UPDATE_SYNCH_INFO_STORAGE      4
00034 
00035 struct fhss_callback;
00036 
00037 typedef struct fhss_beacon_info
00038 {
00039     uint16_t pan_id;
00040     uint8_t source_address[8];
00041     uint32_t timestamp;
00042     uint8_t synch_info[FHSS_SYNCH_INFO_LENGTH];
00043     struct fhss_beacon_info *next;
00044 }fhss_beacon_info_t;
00045 
00046 typedef struct fhss_failed_tx
00047 {
00048     uint8_t handle;
00049     uint8_t bad_channel;
00050     uint8_t retries_done;
00051     ns_list_link_t link;
00052 }fhss_failed_tx_t;
00053 
00054 typedef NS_LIST_HEAD (fhss_failed_tx_t, link) fhss_failed_tx_list_t;
00055 
00056 typedef struct
00057 {
00058     int32_t avg_synch_fix;
00059     int avg_synch_fix_counter;
00060     int drift_compensation;
00061     int channel_counter;
00062 } fhss_synch_monitor_s;
00063 
00064 typedef struct
00065 {
00066     fhss_api_t *fhss_api;
00067     uint32_t datarate;
00068     fhss_states fhss_state;
00069     fhss_timer_t platform_functions;
00070     fhss_configuration_t fhss_configuration;
00071     fhss_synch_configuration_t synch_configuration;
00072 
00073     uint8_t fhss_resolution_divider;
00074     /** Unicast channel index, [0..(number_of_channels-number_of_beacon_channels-1)] */
00075     uint8_t uc_channel_index;
00076     /** Current superframe number, [0..(fhss_number_of_superframes-1)] */
00077     uint8_t current_superframe;
00078     /** Current channel index, [0..(number_of channels-1)] */
00079     uint8_t current_channel_index;
00080     /** Current broadcast index, [0..(number_of_bc_channels-1)] */
00081     uint8_t broadcast_index;
00082     /** Number of channels (unicast and broadcast) */
00083     uint16_t number_of_channels;
00084     /** Channel list counter is increased every time channel list is gone through*/
00085     uint16_t channel_list_counter;
00086     /** This is used to store current RX channel*/
00087     uint8_t rx_channel;
00088     /** Own hop count*/
00089     uint8_t own_hop;
00090     /** Holds the information: transmission is allowed or not on this superframe*/
00091     bool tx_allowed;
00092     /** The tasklet_id of periodic beacon sender, -1 if none is started. */
00093     int8_t beacon_tasklet_id;
00094     /** When synchronization is lost, this counter is used to detect the situation and stop network*/
00095     uint8_t beacons_received_timer;
00096     /** Holds the current synchronization parent MAC address*/
00097     uint8_t synch_parent[8];
00098     // Synch info needs to be sent on next broadcast channel
00099     bool send_synch_info_on_next_broadcast_channel;
00100     // Used for randomizing broadcast sending. Device is not allowed to start broadcasting before the given superframe.
00101     uint8_t broadcast_start_superframe;
00102     /*Indexes in this table will be used to extend the repeated channel sequence*/
00103     uint8_t fhss_scramble_table[MAX_SCRAMBLE_TABLE_INDEXES];
00104     /** Used to monitor and fix synchronization drift*/
00105     fhss_synch_monitor_s synch_monitor;
00106     /** Used to drop multiple synch info messages on same broadcast channel*/
00107     bool beacon_received_on_this_bc_channel;
00108     /** Timer used for events other than synchronization.*/
00109     int8_t fhss_event_timer;
00110     /* Counts the number of sent synch Beacons (Beacon on broadcast channel). Used to limit Beacon traffic when several nodes are scanning network*/
00111     uint8_t synch_infos_sent_counter;
00112     uint32_t synch_interval;
00113     /* This timer/timeout is used to trigger periodically Beacon requests. Resolution is superframe length. Note that FHSS must be synchronized to use this*/
00114     uint32_t fhss_timeout;
00115     uint32_t fhss_timer;
00116     uint16_t synch_panid;
00117     /* Bit mask for FHSS events pushed to event queue. Prevents pushing same event to queue multiple times*/
00118     uint8_t active_fhss_events;
00119 
00120     struct fhss_callback callbacks;
00121     fhss_beacon_info_t *fhss_beacon_info_store;
00122     fhss_failed_tx_list_t fhss_failed_tx_list;
00123     fhss_statistics_t *fhss_stats_ptr;
00124 } fhss_structure_t;
00125 
00126 int8_t fhss_enable(fhss_api_t *fhss_api, const fhss_configuration_t *fhss_configuration, const fhss_timer_t *fhss_timer, fhss_statistics_t *fhss_statistics);
00127 int8_t fhss_disable(fhss_structure_t *fhss_structure);
00128 int8_t fhss_set_datarate(fhss_structure_t *fhss_structure, uint32_t datarate);
00129 bool fhss_is_synch_root(fhss_structure_t *fhss_structure);
00130 int8_t fhss_set_synch_configuration(fhss_structure_t *fhss_structure, const fhss_synch_configuration_t *fhss_synch_configuration);
00131 bool fhss_check_bad_channel(fhss_structure_t *fhss_structure, uint8_t handle);
00132 bool fhss_check_channel_type(fhss_structure_t *fhss_structure, bool is_bc, int frame_type);
00133 bool fhss_check_tx_allowed(fhss_structure_t *fhss_structure, bool is_bc, uint16_t frame_length, int frame_type, uint8_t phy_header_length, uint8_t phy_tail_length);
00134 fhss_structure_t *fhss_get_object_with_api(const fhss_api_t *fhss_api);
00135 fhss_beacon_info_t *fhss_get_beacon_info(fhss_structure_t *fhss_structure, uint16_t pan_id);
00136 int fhss_flush_beacon_info_storage(fhss_structure_t *fhss_structure);
00137 int fhss_add_beacon_info(fhss_structure_t *fhss_structure, uint16_t pan_id, uint8_t *source_address, uint32_t timestamp, uint8_t *synch_info);
00138 void fhss_update_beacon_info_lifetimes(fhss_structure_t *fhss_structure, uint32_t timestamp);
00139 void fhss_trig_event(fhss_structure_t *fhss_structure, uint8_t event_type);
00140 int fhss_timeout_start(fhss_structure_t *fhss_structure, uint32_t time);
00141 int fhss_timeout_stop(fhss_structure_t *fhss_structure);
00142 int fhss_compare_with_synch_parent_address(fhss_structure_t *fhss_structure, const uint8_t *source_addr);
00143 uint32_t fhss_get_tx_time(fhss_structure_t *fhss_structure, uint16_t bytes_to_send, uint8_t phy_header_length, uint8_t phy_tail_length);
00144 int fhss_get_parent_address(fhss_structure_t *fhss_structure, uint8_t *p_addr);
00145 int fhss_down(fhss_structure_t *fhss_structure);
00146 int fhss_update_synch_parent_address(fhss_structure_t *fhss_structure);
00147 void fhss_superframe_handler(const fhss_api_t *fhss_api, uint16_t delay);
00148 fhss_failed_tx_t *fhss_failed_handle_find(fhss_structure_t *fhss_structure, uint8_t handle);
00149 int fhss_failed_handle_add(fhss_structure_t *fhss_structure, uint8_t handle);
00150 int fhss_failed_handle_remove(fhss_structure_t *fhss_structure, uint8_t handle);
00151 void fhss_set_active_event(fhss_structure_t *fhss_structure, uint8_t event_type);
00152 void fhss_clear_active_event(fhss_structure_t *fhss_structure, uint8_t event_type);
00153 bool fhss_read_active_event(fhss_structure_t *fhss_structure, uint8_t event_type);
00154 #define MAX_FHSS_TIMER_DIVIDER  100
00155 #define SYNCH_MONITOR_AVG_SAMPLES   5
00156 
00157 // TX/RX slot management interface
00158 /**
00159  * Update slots
00160  *
00161  * Every superframe handler interrupt calls this function to update the TX/RX slot status.
00162  *
00163  * @param fhss_structure Pointer to FHSS structure
00164  * @return 0 for success, -1 for fail
00165  */
00166 int fhss_update_txrx_slots(fhss_structure_t *fhss_structure);
00167 
00168 void fhss_start_timer(fhss_structure_t *fhss_structure, uint32_t time, void (*callback)(const fhss_api_t *fhss_api, uint16_t));
00169 
00170 
00171 /**
00172  * Calculate time in microseconds to start of next superframe.
00173  *
00174  * @param fhss_struct FHSS state
00175  * @return microseconds left to start of next superframe
00176  */
00177 uint32_t fhss_get_remaining_time_to_next_superframe(const fhss_structure_t *fhss_struct);
00178 
00179 #endif /* FHSS_H_ */