etx.h

00001 /*
00002  * Copyright (c) 2014-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  * \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 /* Fraction that is used when calculating moving average
00030    e.g. ETX = 7/8 * current ETX + 1/8 * new ETX sample
00031    Range for value can be from 1 to 11 */
00032 #define ETX_MOVING_AVERAGE_FRACTION      3     // n >> 3, 1/8
00033 
00034 typedef struct etx_storage_s {
00035     uint16_t        etx;                       /*!< 12 bits fraction */
00036     uint16_t        stored_diff_etx;           /*!< 12 bits fraction */
00037     uint8_t         remote_incoming_idr;       /*!< 5 bits fraction */
00038     unsigned        accumulated_failures: 5;
00039     unsigned        tmp_etx: 1;
00040     unsigned        linkIdr: 4;
00041 } etx_storage_t;
00042 
00043 /**
00044  * \brief A function to update ETX value based on transmission attempts
00045  *
00046  *  Update is made based on failed and successful message sending
00047  *  attempts for a message.
00048  *
00049  * \param interface_id Interface identifier
00050  * \param attempts number of attempts to send message
00051  * \param success was message sending successful
00052  * \param attribute_index Neighbour attribute index
00053  */
00054 void etx_transm_attempts_update(int8_t interface_id, uint8_t attempts, bool success, uint8_t attribute_index);
00055 
00056 /**
00057  * \brief A function to update ETX value based on remote incoming IDR
00058  *
00059  *  Update is made based on remote incoming IDR received from
00060  *  neighbor.
00061  *
00062  * \param interface_id Interface identifier
00063  * \param remote_incoming_idr Remote incoming IDR
00064  * \param attribute_index Neighbour attribute index
00065  */
00066 void etx_remote_incoming_idr_update(int8_t interface_id, uint8_t remote_incoming_idr, uint8_t attribute_index);
00067 
00068 /**
00069  * \brief A function to read ETX value
00070  *
00071  *  Returns ETX value for an address
00072  *
00073  * \param interface_id network interface id
00074  * \param addr_type address type, ADDR_802_15_4_SHORT or ADDR_802_15_4_LONG
00075  * \param addr_ptr PAN ID with 802.15.4 address
00076  *
00077  * \return 0x0100 to 0xFFFF ETX value (8 bit fraction)
00078  * \return 0xFFFF address not associated
00079  * \return 0x0000 address unknown or other error
00080  * \return 0x0001 no ETX statistics on this interface
00081  */
00082 uint16_t etx_read(int8_t interface_id, addrtype_t addr_type, const uint8_t *addr_ptr);
00083 
00084 /**
00085  * \brief A function to read local incoming IDR value
00086  *
00087  *  Returns local incoming IDR value for an neighbour
00088  *
00089  * \param attribute_index Neighbour attribute index
00090  *
00091  * \return 0x0100 to 0xFFFF incoming IDR value (8 bit fraction)
00092  * \return 0x0000 address unknown
00093  */
00094 uint16_t etx_local_incoming_idr_read(int8_t interface_id, uint8_t attribute_index);
00095 
00096 /**
00097  * \brief A function to read local ETXvalue
00098  *
00099  *  Returns local ETX value for an address
00100  *
00101  * \param mac64_addr_ptr long MAC address
00102  *
00103  * \return 0x0100 to 0xFFFF ETX value (8 bit fraction)
00104  * \return 0x0000 address unknown
00105  */
00106 uint16_t etx_local_etx_read(int8_t interface_id, uint8_t attribute_index);
00107 
00108 /**
00109  * \brief A function to update ETX value based on LQI and dBm
00110  *
00111  *  Update is made based on dBM and LQI of received message.
00112  *
00113  * \param lqi link quality indicator
00114  * \param dbm measured dBm
00115  * \param attribute_index Neighbour attribute index
00116  *
00117  * \return 0x0100 to 0xFFFF local incoming IDR value (8 bit fraction)
00118  */
00119 uint16_t etx_lqi_dbm_update(int8_t interface_id, uint8_t lqi, int8_t dbm, uint8_t attribute_index);
00120 
00121 /**
00122  * \brief A function callback that indicates ETX value change
00123  *
00124  *  Callback indicates when ETX value has changed more or equal to
00125  *  hysteresis value.
00126  *
00127  * \param nwk_interface_id network interface id
00128  * \param previous_etx ETX value to what the current ETX was compared (8 bit fraction)
00129  * \param current_etx current ETX value (8 bit fraction)
00130  * \param attribute_index Neighbour attribute index
00131  *
00132  */
00133 typedef void (etx_value_change_handler_t)(int8_t nwk_id, uint16_t previous_etx, uint16_t current_etx, uint8_t attribute_index);
00134 
00135 /**
00136  * \brief A function callback that indicates the number of accumulated TX failures
00137  *
00138  * Callback indicates when number of accumulated failures is more or equal to threshold value.
00139  *
00140  * \param interface_id interface ID
00141  * \param accumulated_failures number of accumulated failures
00142  * \param attribute_index Neighbour attribute index
00143  *
00144  */
00145 typedef void (etx_accum_failures_handler_t)(int8_t interface_id, uint8_t accumulated_failures, uint8_t attribute_index);
00146 
00147 /**
00148  * \brief A function to register ETX value change callback
00149  *
00150  *  When ETX value has changed more or equal to hysteresis value ETX
00151  *  module calls ETX value change callback.
00152  *
00153  * \param nwk_interface_id network interface id
00154  * \param hysteresis hysteresis value (8 bit fraction)
00155  * \param callback_ptr callback function pointer
00156  *
00157  * \return 0 not 6LowPAN interface
00158  * \return 1 success
00159  */
00160 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);
00161 
00162 /**
00163  * \brief A function to allocte ETX storage list
00164  *
00165  * \param interface_id interface id
00166  * \param etx_storage_size Size of storage. 0 will free allocate data
00167  *
00168  * \return false Allocate fail
00169  * \return true Allocate OK
00170  */
00171 bool etx_storage_list_allocate(int8_t interface_id, uint8_t etx_storage_size);
00172 
00173 /**
00174  * \brief A function to read ETX storage for defined neighbour
00175  *
00176  * \param interface_id interface id
00177  * \param attribute_index Neighbour attribute index
00178  *
00179  * \return Pointer to ETX storage
00180  * \return NULL When unknow interface or attribute
00181  */
00182 etx_storage_t *etx_storage_entry_get(int8_t interface_id, uint8_t attribute_index);
00183 
00184 
00185 /**
00186  * \brief A function to register accumulated failures callback
00187  *
00188  *  When the number of accumulated failures has reached the threshold
00189  *  value, the ETX module calls the accumulated failures callback on
00190  *  every transmission failure.
00191  *
00192  * \param nwk_id network ID (6LoWPAN)
00193  * \param interface_id interface ID
00194  * \param threshold threshold value for accumulated failures
00195  * \param callback_ptr callback function pointer
00196  *
00197  * \return 0 not 6LowPAN interface
00198  * \return 1 success
00199  */
00200 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);
00201 
00202 /**
00203  * \brief A function to remove ETX neighbor
00204  *
00205  *  Notifies ETX module that neighbor has been removed. Calls ETX value change callback
00206  *  if that is set.
00207  *
00208  * \param attribute_index Neighbour attribute index
00209  *
00210  */
00211 void etx_neighbor_remove(int8_t interface_id, uint8_t attribute_index);
00212 
00213 /**
00214  * \brief A function to add ETX neighbor
00215  *
00216  *  Notifies ETX module that neighbor has been added. Calls ETX value change callback
00217  *  if that is set.
00218  *
00219  * \param attribute_index Neighbour attribute index
00220  *
00221  */
00222 void etx_neighbor_add(int8_t interface_id, uint8_t attribute_index);
00223 
00224 #endif /* ETX_H_ */