net_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 net_load_balance_api.h
00020  * \brief 6LoWPAN network load balance control API.
00021  */
00022 
00023 #ifndef NET_LOAD_BALANCE_API_H_
00024 #define NET_LOAD_BALANCE_API_H_
00025 
00026 #include "ns_types.h"
00027 
00028 /**
00029  * \brief load_balance_network_switch_notify This function is called by the load balancer when it has detected a better network to switch to.
00030  *
00031  * \return true The network can be switched immediately.
00032  * \return false The load balancer will ask later a time for network switching if a better network is still available at that time.
00033  */
00034 typedef bool net_load_balance_network_switch_notify(void);
00035 
00036 /**
00037  * \brief Set user callback for accepting the network switch.
00038  * \param interface_id Interface ID.
00039  * \param network_switch_notify User callback.
00040  *
00041  * \return 0 Set OK.
00042  * \return -1 unknown Interface.
00043  */
00044 int8_t net_load_balance_network_switch_cb_set(int8_t interface_id, net_load_balance_network_switch_notify *network_switch_notify);
00045 
00046 /**
00047  * \brief Create and enable load balance to the selected interface.
00048  * \param interface_id Interface ID.
00049  * \param enable_periodic_beacon_interval Set True when you want to activate load balance periodic beacon; false will work only properly with the FHSS system.
00050  *
00051  * \return 0 Enable OK.
00052  * \return -1 unknown Interface or parameter error.
00053  * \return -2 Out of memory.
00054  * \return -3 Load balance already configured to this interface.
00055  */
00056 int8_t net_load_balance_create(int8_t interface_id, bool enable_periodic_beacon_interval);
00057 
00058 /**
00059  * \brief Disable and delete load balancing from the interface.
00060  * \param interface_id Interface ID.
00061  *
00062  * \return 0 Process OK.
00063  * \return -1 Unknown interface.
00064  */
00065 int8_t net_load_balance_delete(int8_t interface_id);
00066 
00067 /**
00068  * \brief Set load balance threshold min and max.
00069  *
00070  *  Network switch: diff_priority >= randLIB_get_random_in_range(threshold_min, threshold_max) --> switch network if true.
00071  *  For border router: Disable network compare by setting threshold_min and threshold_max to 0.
00072  *
00073  * \param interface_id Interface ID.
00074  * \param threshold_min Min value defines a random minimum value for compare (must be bigger than 0).
00075  * \param threshold_max Max value defines a random maximum value for compare (must be bigger than 0).
00076  *
00077  * \return 0 Process OK, -1 Unknown interface ID.
00078  */
00079 int8_t net_load_balance_threshold_set(int8_t interface_id, uint8_t threshold_min, uint8_t threshold_max);
00080 
00081 
00082 /**
00083  * \brief Set the network probability percent when the new network is better than threshold max.
00084  *
00085  * \param interface_id Interface ID.
00086  * \param max_p Probability percent to switch the network. Default is 25%. Accepted values are [1,100], recommend values are 10-25.
00087  *
00088  * \return 0 Process OK, -1 Unknown interface ID or parameter fail.
00089  */
00090 int8_t net_load_balance_set_max_probability(int8_t interface_id, uint8_t max_p);
00091 
00092 /**
00093  * \brief Set load balance expected device count and enable automatic network load level update.
00094  *
00095  * This feature is just for RPL DoDAG root device!
00096  *
00097  * \param interface_id Interface ID.
00098  * \param expected_device_count Device count that sets the max load level.
00099  *        - If the count is not divisible by 8, the function rounds the number up to reach that.
00100  *        - It is not hard limit it define max DoDAG preference.
00101  *        - For hard limit, check whiteboard_api.h.
00102  *
00103  * \return 0 Process OK, -1 Unknown interface ID, -2 Out of memory.
00104  */
00105 int8_t net_load_balance_load_level_update_enable(int8_t interface_id, uint16_t expected_device_count);
00106 
00107 /**
00108  * \brief Disable the automatic network load level update.
00109  *
00110  * \param interface_id Interface ID.
00111  *
00112  * \return 0 Process OK, -1 Unknown interface ID.
00113  */
00114 int8_t net_load_balance_load_level_update_disable(int8_t interface_id);
00115 
00116 
00117 
00118 #endif /* NET_LOAD_BALANCE_API_H_ */