etx.h

00001 /*
00002  * Copyright (c) 2014-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 /*
00018  * \file etx.h
00019  * \brief Expected transmission count (ETX metric), module
00020  *
00021  *
00022  */
00023 
00024 #ifndef ETX_H_
00025 #define ETX_H_
00026 
00027 #include "NWK_INTERFACE/Include/protocol_abstract.h"
00028 
00029 struct mle_neigh_table_entry_t;
00030 /* Fraction that is used when calculating moving average
00031    e.g. ETX = 7/8 * current ETX + 1/8 * new ETX sample
00032    Range for value can be from 1 to 11 */
00033 #define ETX_MOVING_AVERAGE_FRACTION      3     // n >> 3, 1/8
00034 
00035 /**
00036  * \brief A function to update ETX value based on transmission attempts
00037  *
00038  *  Update is made based on failed and successful message sending
00039  *  attempts for a message.
00040  *
00041  * \param interface_id Interface identifier
00042  * \param attempts number of attempts to send message
00043  * \param success was message sending successful
00044  * \param addr_type address type, ADDR_802_15_4_SHORT or ADDR_802_15_4_LONG
00045  * \param addr_ptr PAN ID with 802.15.4 address
00046  */
00047 void etx_transm_attempts_update(int8_t interface_id, uint8_t attempts, bool success, addrtype_t addr_type, const uint8_t *addr_ptr);
00048 
00049 /**
00050  * \brief A function to update ETX value based on remote incoming IDR
00051  *
00052  *  Update is made based on remote incoming IDR received from
00053  *  neighbor.
00054  *
00055  * \param interface_id Interface identifier
00056  * \param remote_incoming_idr Remote incoming IDR
00057  * \param mac64_addr_ptr long MAC address
00058  */
00059 void etx_remote_incoming_idr_update(int8_t interface_id, uint8_t remote_incoming_idr, struct mle_neigh_table_entry_t *neigh_table_ptr);
00060 
00061 /**
00062  * \brief A function to read ETX value
00063  *
00064  *  Returns ETX value for an address
00065  *
00066  * \param interface_id network interface id
00067  * \param addr_type address type, ADDR_802_15_4_SHORT or ADDR_802_15_4_LONG
00068  * \param addr_ptr PAN ID with 802.15.4 address
00069  *
00070  * \return 0x0100 to 0xFFFF ETX value (8 bit fraction)
00071  * \return 0xFFFF address not associated
00072  * \return 0x0000 address unknown or other error
00073  * \return 0x0001 no ETX statistics on this interface
00074  */
00075 uint16_t etx_read(int8_t interface_id, addrtype_t addr_type, const uint8_t *addr_ptr);
00076 
00077 /**
00078  * \brief A function to read local incoming IDR value
00079  *
00080  *  Returns local incoming IDR value for an address
00081  *
00082  * \param mac64_addr_ptr long MAC address
00083  *
00084  * \return 0x0100 to 0xFFFF incoming IDR value (8 bit fraction)
00085  * \return 0x0000 address unknown
00086  */
00087 uint16_t etx_local_incoming_idr_read(int8_t interface_id, struct mle_neigh_table_entry_t *neigh_table_ptr);
00088 
00089 /**
00090  * \brief A function to update ETX value based on LQI and dBm
00091  *
00092  *  Update is made based on dBM and LQI of received message.
00093  *
00094  * \param lqi link quality indicator
00095  * \param dbm measured dBm
00096  * \param mac64_addr_ptr long MAC address
00097  *
00098  * \return 0x0100 to 0xFFFF local incoming IDR value (8 bit fraction)
00099  */
00100 uint16_t etx_lqi_dbm_update(int8_t interface_id, uint8_t lqi, int8_t dbm, struct mle_neigh_table_entry_t *neigh_table_ptr);
00101 
00102 /**
00103  * \brief A function callback that indicates ETX value change
00104  *
00105  *  Callback indicates when ETX value has changed more or equal to
00106  *  hysteresis value.
00107  *
00108  * \param nwk_interface_id network interface id
00109  * \param previous_etx ETX value to what the current ETX was compared (8 bit fraction)
00110  * \param current_etx current ETX value (8 bit fraction)
00111  * \param mac64_addr_ptr long MAC address
00112  * \param mac16_addr short MAC address or 0xffff address is not set
00113  *
00114  */
00115 typedef void (etx_value_change_handler_t)(int8_t nwk_id, uint16_t previous_etx, uint16_t current_etx, const uint8_t *mac64_addr_ptr, uint16_t mac16_addr);
00116 
00117 /**
00118  * \brief A function callback that indicates the number of accumulated TX failures
00119  *
00120  * Callback indicates when number of accumulated failures is more or equal to threshold value.
00121  *
00122  * \param interface_id interface ID
00123  * \param accumulated_failures number of accumulated failures
00124  * \param neigh_table_ptr the neighbor node in question
00125  *
00126  */
00127 typedef void (etx_accum_failures_handler_t)(int8_t interface_id, uint8_t accumulated_failures, struct mle_neigh_table_entry_t *neigh_table_ptr);
00128 
00129 /**
00130  * \brief A function to register ETX value change callback
00131  *
00132  *  When ETX value has changed more or equal to hysteresis value ETX
00133  *  module calls ETX value change callback.
00134  *
00135  * \param nwk_interface_id network interface id
00136  * \param hysteresis hysteresis value (8 bit fraction)
00137  * \param callback_ptr callback function pointer
00138  *
00139  * \return 0 not 6LowPAN interface
00140  * \return 1 success
00141  */
00142 uint8_t etx_value_change_callback_register(nwk_interface_id nwk_id,int8_t interface_id, uint16_t hysteresis, etx_value_change_handler_t *callback_ptr);
00143 
00144 /**
00145  * \brief A function to register accumulated failures callback
00146  *
00147  *  When the number of accumulated failures has reached the threshold
00148  *  value, the ETX module calls the accumulated failures callback on
00149  *  every transmission failure.
00150  *
00151  * \param nwk_id network ID (6LoWPAN)
00152  * \param interface_id interface ID
00153  * \param threshold threshold value for accumulated failures
00154  * \param callback_ptr callback function pointer
00155  *
00156  * \return 0 not 6LowPAN interface
00157  * \return 1 success
00158  */
00159 uint8_t etx_accum_failures_callback_register(nwk_interface_id nwk_id, int8_t interface_id, uint8_t threshold, etx_accum_failures_handler_t *callback_ptr);
00160 
00161 /**
00162  * \brief A function to remove ETX neighbor
00163  *
00164  *  Notifies ETX module that neighbor has been removed. Calls ETX value change callback
00165  *  if that is set.
00166  *
00167  * \param mac64_addr_ptr long MAC address
00168  *
00169  */
00170 void etx_neighbor_remove(int8_t interface_id, struct mle_neigh_table_entry_t *neigh_table_ptr);
00171 
00172 /**
00173  * \brief A function to add ETX neighbor
00174  *
00175  *  Notifies ETX module that neighbor has been added. Calls ETX value change callback
00176  *  if that is set.
00177  *
00178  * \param mac64_addr_ptr long MAC address
00179  *
00180  */
00181 void etx_neighbor_add(int8_t interface_id, struct mle_neigh_table_entry_t *neigh_table_ptr);
00182 
00183 #endif /* ETX_H_ */