load_balance_api.h

00001 /*
00002  * Copyright (c) 2016-2018, 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 
00018 /**
00019  * \file load_balance_api.h
00020  * \brief A API class to support 6lowpan network load balance which based on RPL routing.
00021  */
00022 
00023 #ifndef LOAD_BALANCE_API_H
00024 #define LOAD_BALANCE_API_H
00025 
00026 #include "ns_types.h"
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #include "net_load_balance_api.h"
00033 
00034 typedef struct load_balance_api load_balance_api_t;
00035 
00036 struct mlme_beacon_ind_s;
00037 struct mlme_pan_descriptor_s;
00038 
00039 typedef enum {
00040     LB_ROUTER_LEAVE,
00041     LB_NEIGHBOUR_LEAVE
00042 } load_balance_nwk_switch_operation;
00043 
00044 /**
00045  * Application which want enable load balance must first create load balance class, e.g 'load_balance_api_t* load_balance_create()'
00046  * In the function external Nanostack needs to fill necessary function pointers so that Upper layer can use it.
00047  * For load balance user define:
00048  *   - load_balance_beacon_notify: Beacon notify should call this api
00049  *   - load_balance_api_initialize: Initialise load balance class with next function pointer
00050  *   - load_balance_enable
00051  * Load Balance requested function pointers
00052  *   - load_balance_priority_get
00053  *   - load_balance_network_switch_req
00054  *   - load_balance_beacon_interval_set
00055  */
00056 
00057 /**
00058  * \brief load_balance_beacon_notify
00059  * \param api load_balance_api_t pointer
00060  * \param beacon_ind standard beacon indication structure
00061  * \param priority Beacon parsed network priority
00062  */
00063 typedef void load_balance_beacon_notify(const load_balance_api_t *api, const struct mlme_beacon_ind_s *beacon_ind, uint8_t priority);
00064 
00065 /**
00066  * \brief load_balance_second_ticks update load balance state timer
00067  * \param load_balance_api_t pointer
00068  */
00069 typedef void load_balance_second_ticks(const load_balance_api_t *api);
00070 
00071 /**
00072  * \brief load_balance_enabled handler for enabled or disable beacon notify
00073  * \param load_balance_api_t pointer
00074  * \param active_state true enable load balancer and false disable
00075  * \param network_triggle_max_period time that load balance will send periodic beacon
00076  * \param network_route_life_time time for device route lifetime
00077  */
00078 typedef void load_balance_enable(const load_balance_api_t *api,
00079                                  bool active_state, uint32_t network_triggle_max_period,
00080                                  uint32_t network_route_life_time);
00081 
00082 /**
00083  * \brief load_balance_priority_get function for load balance to get current advertisement priority
00084  * \param load_balance_user pointer to load balancer user initialised data
00085  *
00086  * \return priority
00087  */
00088 typedef uint8_t load_balance_priority_get(const void *load_balance_user);
00089 
00090 /**
00091  * \brief load_balance_beacon_tx function for trig periodically beacon
00092  * \param load_balance_user pointer to load balancer user initialised data
00093  *
00094  */
00095 typedef void load_balance_beacon_tx(const void *load_balance_user);
00096 
00097 /**
00098  * \brief load_balance_network_switch_notify this function will be called by load balance when it have detected better network to switch change state
00099  * \param load_balance_user pointer to load balancer user initialised data
00100  * \param operation network switch operation
00101  * \param timeout pointer where operation time must be define NULL when load balance not need time out or user set 0
00102  *
00103  * \return true Network switching can be performed immediately
00104  * \return false Network switching will be performed later
00105  */
00106 typedef bool load_balance_network_switch_notify(const void *load_balance_user, load_balance_nwk_switch_operation operation, uint16_t *timeout);
00107 
00108 /**
00109  * \brief load_balance_network_switch_req this function will be called by load balance when it have detected better network to switch
00110  * \param load_balance_user pointer to load balancer user initialised data
00111  * \param PANDescriptor pointer to link and coordinator info
00112  * \param beacon_payload beacon payload pointer for new network
00113  * \param beacon_payload_length payload length
00114  *
00115  * \return true network switch started
00116  * \return false network switch fail
00117  */
00118 typedef bool load_balance_network_switch_req(void *load_balance_user, struct mlme_pan_descriptor_s *PANDescriptor, const uint8_t *beacon_payload, uint16_t beacon_payload_length);
00119 
00120 
00121 /**
00122  * \brief load_balance_api_get_node_count Get border router registered node count
00123  * \param lb_user Load balancing user defined unique data.
00124  * \param node_count Pointer where node count is stored
00125  * \return -1 Get fail, 0 node_count include current node count
00126  */
00127 typedef int8_t load_balance_api_get_node_count(void *lb_user, uint16_t *node_count);
00128 
00129 /**
00130  * \brief load_balance_api_set_load_level Update new load level to network
00131  * \param lb_user Load balancing user defined unique data.
00132  * \param load_level load level which could be [0,CONFIGURED_SCALER -1]
00133  * \return -1 Set fail, 0 New Network Load is updated
00134  */
00135 typedef int8_t load_balance_api_set_load_level(void *lb_user, uint8_t load_level);
00136 
00137 /**
00138  * \brief load_balance_api_initialize Initialises load balancer needed callback.
00139  * \param api load_balance_api_t pointer, which is created by application.
00140  * \param lb_beacon_tx_period_set_cb Upper layer function to handle MCPS confirmations
00141  * \param priority_get_cb Upper layer function to handle MCPS indications
00142  * \param lb_nwk_switch_cb
00143  * \param  beacon_max_payload_length Set 0 if network switch is disabled otherwise give max supported beacon payload.
00144  * \param lb_user Load balancing user defined unique data
00145  * \return -1 if error, -2 if Out of Memory, 0 otherwise
00146  */
00147 typedef int8_t load_balance_api_initialize(load_balance_api_t *api, load_balance_beacon_tx *lb_beacon_tx,
00148                                            load_balance_priority_get *priority_get_cb, load_balance_network_switch_req *lb_nwk_switch_cb, uint16_t beacon_max_payload_length, void *lb_user);
00149 
00150 /**
00151  * \brief Struct load_balance_api_s defines functions for two-way communications between load balance and user.
00152  * Nanostack creates load_balance_api_s object by calling load_balance_create() function.
00153  * Then object is passed to Upper layer which then initialises it's own callback functions.
00154  */
00155 struct load_balance_api {
00156     load_balance_api_initialize *lb_initialize;
00157     load_balance_enable         *lb_enable;
00158     load_balance_beacon_notify  *lb_beacon_notify;
00159     load_balance_second_ticks   *lb_seconds_tick_update;
00160 };
00161 
00162 /**
00163  * \brief Create load balance class
00164  * \param lb_notify_cb user callback for accept network switch
00165  * \param activate_periodic_beacon True define that load balance will generate periodic beacon based configured value at enable
00166  *
00167  * \return Pointer to load balance class
00168  */
00169 load_balance_api_t *load_balance_create(load_balance_network_switch_notify *lb_notify_cb, bool activate_periodic_beacon);
00170 
00171 /**
00172  * \brief Delete load balance class and free memory
00173  * \param api Class pointer to deleted class
00174  *
00175  * \return 0 process ok -1 Unknown class
00176  */
00177 int load_balance_delete(load_balance_api_t *api);
00178 
00179 /**
00180  * \brief Set load balance threshold min and max
00181  *
00182  * Nework switch will work next  diff_priority >= randLIB_get_random_in_range(threshold_min, threshold_max) --> switch network if true
00183  * For border router Disable Network compare set threshold_min and threshold_max to 0.
00184  *
00185  * \param api Class pointer to deleted class
00186  * \param threshold_min minimal threshold value for network switch
00187  * \param threshold_max max threshold value for network switch
00188  *
00189  * \return 0 process ok -1 Unknown class or unsupported threshold
00190  */
00191 int load_balance_network_threshold_set(load_balance_api_t *api, uint8_t threshold_min, uint8_t threshold_max);
00192 
00193 /**
00194  * \brief Enable load balance load monitor and update feature
00195  *
00196  * This feature is for border router's defined function for give network scale and load parameter what load balancer will follow automatically.
00197  *
00198  * \param api Class pointer to deleted class
00199  * \param expected_node_count node which define max load to network
00200  * \param network_load_scaler Define max load value
00201  * \param get_count_cb function pointer for read current node count
00202  * \param set_new_load_cb function pointer what is called when load level must be update
00203  *
00204  * \return 0 process ok -1 Unknown class or unsupported parameter
00205  */
00206 int load_balance_network_load_monitor_enable(load_balance_api_t *api, uint16_t expected_node_count, uint8_t network_load_scaler, load_balance_api_get_node_count *get_count_cb, load_balance_api_set_load_level *set_new_load_cb);
00207 
00208 /**
00209  * \brief Disable load balance load monitor and update feature
00210  *
00211  * \param api Class pointer to deleted class
00212  *
00213  * \return 0 process ok -1 Unknown class
00214  */
00215 int load_balance_network_load_monitor_disable(load_balance_api_t *api);
00216 
00217 /**
00218  * \brief Set network probability percent when new network is better than threshold max
00219  *
00220  * \param api Class pointer to deleted class
00221  * \param max_p is percent probability to switch network. Default is 25%. Accepted values are [1,100] recommend values are 10-25.
00222  *
00223  * \return 0 process ok -1 Unknown class or unsupported parameter
00224  */
00225 int load_balance_set_max_probability(load_balance_api_t *api, uint8_t max_p);
00226 
00227 /**
00228  * \brief Set user callback for accepting the network switch.
00229  * \param api Class pointer to deleted class.
00230  * \param network_switch_notify User callback.
00231  *
00232  * \return 0 Set OK.
00233  * \return -1 unknown Interface.
00234  */
00235 int load_balance_network_switch_cb_set(load_balance_api_t *api, net_load_balance_network_switch_notify *network_switch_notify);
00236 
00237 #ifdef __cplusplus
00238 }
00239 #endif
00240 
00241 #endif // LOAD_BALANCE_API_H