mac_neighbor_table.h

00001 /*
00002  * Copyright (c) 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 #ifndef MAC_NEIGHBOR_TABLE_H_
00019 #define MAC_NEIGHBOR_TABLE_H_
00020 
00021 #include "ns_types.h"
00022 #include "ns_list.h"
00023 
00024 #define NEIGHBOR_CLASS_LINK_DEFAULT_LIFETIME 240
00025 
00026 #define ACTIVE_NUD_PROCESS_MAX 3 //Limit That how many activate NUD process is active in same time
00027 
00028 #define NORMAL_NEIGHBOUR                0
00029 #define SECONDARY_PARENT_NEIGHBOUR      1
00030 #define CHILD_NEIGHBOUR                 2
00031 #define PRIORITY_PARENT_NEIGHBOUR       3
00032 /**
00033  * Generic Neighbor table entry
00034  */
00035 typedef struct mac_neighbor_table_entry {
00036     uint8_t         index ;                  /*!< Unique Neighbour index */
00037     uint8_t         mac64 [8];               /*!< MAC64 */
00038     uint16_t        mac16 ;                  /*!< MAC16 address for neighbor 0xffff when no 16-bit address is unknown */
00039     uint32_t        lifetime ;               /*!< Life time in seconds which goes down */
00040     uint32_t        link_lifetime ;          /*!< Configured link timeout*/
00041     bool            rx_on_idle :1;           /*!< True, RX on idle allways at idle state, false disable radio */
00042     bool            ffd_device :1;           /*!< True FFD device, false for RFD */
00043     bool            advertisment:1;
00044     bool            connected_device :1;     /*!< True Link is connected and data rx is accepted , False RX data is not accepted*/
00045     bool            trusted_device :1;       /*!< True mean use normal group key, false for enable pairwise key */
00046     bool            nud_active :1;           /*!< True Neighbor NUD process is active, false not active process */
00047     unsigned        link_role :2;            /*!< Link role: NORMAL_NEIGHBOUR, PRIORITY_PARENT_NEIGHBOUR, SECONDARY_PARENT_NEIGHBOUR, CHILD_NEIGHBOUR */
00048     ns_list_link_t  link;
00049 } mac_neighbor_table_entry_t;
00050 
00051 typedef NS_LIST_HEAD (mac_neighbor_table_entry_t, link) mac_neighbor_table_list_t;
00052 
00053 #define mac_neighbor_info(interface) ((interface)->mac_parameters->mac_neighbor_table) /*!< Helper macro for give mac neighbor class pointer from interface pointer. */
00054 
00055 /**
00056  * Remove entry notify
00057  *
00058  * \param entry_ptr Pointer to removed entry
00059  * \param user_data pointer for user to detect interface
00060  */
00061 typedef void neighbor_entry_remove_notify(mac_neighbor_table_entry_t *entry_ptr, void *user_data);
00062 
00063 
00064 /**
00065  * NUD entry notify
00066  *
00067  * \param entry_ptr Pointer to neighbor entry
00068  * \param user_data pointer for user to detect interface
00069  *
00070  * \return true NUD message generated
00071  * \return false When NUD is not generated
00072  */
00073 typedef bool neighbor_entry_nud_notify(mac_neighbor_table_entry_t *entry_ptr, void *user_data);
00074 
00075 /**
00076  * Neighbor table class structure
00077  */
00078 typedef struct mac_neighbor_table_class {
00079     mac_neighbor_table_list_t neighbour_list ;               /*!< List of active neighbors */
00080     mac_neighbor_table_list_t free_list ;                    /*!< List of free neighbors entries */
00081     uint32_t nud_threshold ;                                 /*!< NUD threshold time which generates keep alive message */
00082     uint8_t list_total_size ;                                /*!< Total number allocated neighbor entries */
00083     uint8_t active_nud_process ;                             /*!< Indicate Active NUD Process */
00084     uint8_t neighbour_list_size ;                            /*!< Active Neighbor list size */
00085     void *table_user_identifier ;                            /*!< Table user identifier like interface pointer */
00086     neighbor_entry_remove_notify *user_remove_notify_cb ;    /*!< Neighbor Remove Callback notify */
00087     neighbor_entry_nud_notify *user_nud_notify_cb ;          /*!< Trig NUD process for neighbor */
00088     mac_neighbor_table_entry_t neighbor_entry_buffer [];     /*!< Pointer for allocated neighbor table entries*/
00089 } mac_neighbor_table_t;
00090 
00091 
00092 /**
00093  * \brief mac_neighbor_table_create Allocate Neighbour table class
00094  *
00095  * Call this only one's for interface
00096  *
00097  * \param table_size size of neighbor table
00098  * \param remove_cb callback pointer for notify removed neighbor
00099  * \param nud_cb Interface NUD operation trgger callback
00100  * \param user_indentifier user identifier pointer like interface pointer
00101  *
00102  * \return pointer to neighbor table class when create is OK
00103  * \return NULL when memory allocation happen
00104  *
00105  */
00106 mac_neighbor_table_t *mac_neighbor_table_create(uint8_t table_size, neighbor_entry_remove_notify *remove_cb, neighbor_entry_nud_notify *nud_cb, void *user_indentifier);
00107 
00108 /**
00109  * mac_neighbor_table_delete Delete Neigbor table class
00110  *
00111  * \param table_class neighbor table class
00112  */
00113 void mac_neighbor_table_delete(mac_neighbor_table_t *table_class);
00114 
00115 /**
00116  * mac_neighbor_table_neighbor_list_clean Clean neighbour_list from giving class
00117  */
00118 void mac_neighbor_table_neighbor_list_clean(mac_neighbor_table_t *table_class);
00119 
00120 /**
00121  * mac_neighbor_table_neighbor_timeout_update Update Neighbor table timeout values
00122  *
00123  * \param table_class pointer to table class
00124  * \param time_update in seconds
00125  *
00126  */
00127 void mac_neighbor_table_neighbor_timeout_update(mac_neighbor_table_t *table_class, uint32_t time_update);
00128 
00129 
00130 /**
00131  * mac_neighbor_table_entry_allocate Allocate Neighbour table class entry
00132  *
00133  * \param table_class pointer to table class
00134  * \param mac64 neighbor 64-bit mac address
00135  *
00136  * \return NULL allocate fail
00137  * \return pointer to allocated neighbor table entry
00138  */
00139 mac_neighbor_table_entry_t *mac_neighbor_table_entry_allocate(mac_neighbor_table_t *table_class, const uint8_t *mac64);
00140 
00141 /**
00142  * mac_neighbor_table_neighbor_remove Remove neighbor from list
00143  *
00144  * \param table_class pointer to table class
00145  * \param neighbor_entry pointer to removed entry
00146  *
00147  */
00148 void mac_neighbor_table_neighbor_remove(mac_neighbor_table_t *table_class, mac_neighbor_table_entry_t *neighbor_entry);
00149 
00150 /**
00151  * mac_neighbor_table_neighbor_refresh Refresh neigbor timeout and time to live values based on giving time
00152  *
00153  * \param table_class pointer to table class
00154  * \param neighbor_entry pointer to refreshed entry
00155  * \param life_time define lifetime for neighbor
00156  */
00157 void mac_neighbor_table_neighbor_refresh(mac_neighbor_table_t *table_class, mac_neighbor_table_entry_t *neighbor_entry, uint32_t life_time);
00158 
00159 /**
00160  * mac_neighbor_table_neighbor_connected Mark neighbour connected state and data is accepted from device
00161  *
00162  * Call this function when node is trusted connected
00163  *
00164  * \param table_class pointer to table class
00165  * \param neighbor_entry pointer to refreshed entry
00166  */
00167 void mac_neighbor_table_neighbor_connected(mac_neighbor_table_t *table_class, mac_neighbor_table_entry_t *neighbor_entry);
00168 
00169 /**
00170  * mac_neighbor_table_trusted_neighbor Function for manage neighbor role at mesh network
00171  *
00172  * Call this function when node is trusted connected
00173  *
00174  * \param table_class pointer to table class
00175  * \param neighbor_entry pointer to refreshed entry
00176  * \param trusted_device True neigbor is part of mesh and will use group key , false enable pairwose key
00177  */
00178 void mac_neighbor_table_trusted_neighbor(mac_neighbor_table_t *table_class, mac_neighbor_table_entry_t *neighbor_entry, bool trusted_device);
00179 
00180 /**
00181  * mac_neighbor_table_address_discover Discover neighbor from list by address
00182  *
00183  *  \param table_class pointer to table class
00184  *  \param address pointer to 16-bit MAC or 64-bit address for discover
00185  *  \param address_type 2 for 16-bit address and 3 for 64-bit (same than 802.15.4 define)
00186  *
00187  *  \return pointer to discover neighbor entry if it exist
00188  */
00189 mac_neighbor_table_entry_t *mac_neighbor_table_address_discover(mac_neighbor_table_t *table_class, const uint8_t *address, uint8_t address_type);
00190 
00191 /**
00192  * mac_neighbor_table_attribute_discover Discover neighbor from list by attribute index
00193  *
00194  *  \param table_class pointer to table class
00195  *  \param index neighbor index
00196  *
00197  *  \return pointer to discover neighbor entry if it exist
00198  */
00199 mac_neighbor_table_entry_t *mac_neighbor_table_attribute_discover(mac_neighbor_table_t *table_class, uint8_t index);
00200 
00201 mac_neighbor_table_entry_t *mac_neighbor_entry_get_by_ll64(mac_neighbor_table_t *table_class, const uint8_t *ipv6Address, bool allocateNew, bool *new_entry_allocated);
00202 
00203 mac_neighbor_table_entry_t *mac_neighbor_entry_get_by_mac64(mac_neighbor_table_t *table_class, const uint8_t *mac64, bool allocateNew, bool *new_entry_allocated);
00204 
00205 #endif /* MAC_NEIGHBOR_TABLE_H_ */