neighbor_table_definition.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 neighbor_table_definition.h
00019  * \brief Neighbor Cache for Layer 2
00020  *
00021  * Frame Counter filter USAGE:
00022  * Library keeps track of highest accepted Frame Counter and 15 Frame Counter before that. Functionality is:
00023  *  -   If received counter is duplicate, packet is silently rejected and Security module return error about that
00024  *  -   If received counter is bigger than highest accepted counter + 15, then we will ???
00025  *  -   If received counter is smaller than  highest accepted counter - 15, then packet is silently rejected and security module will return duplicate
00026  */
00027 
00028 #ifndef NEIGHBOR_TABLE_DEFINITION_H_
00029 #define NEIGHBOR_TABLE_DEFINITION_H_
00030 
00031 #include "ns_list.h"
00032 
00033 #define NEIGH_LQI_DEFAULT_SAMPLE                16
00034 
00035 #define NEIGH_LINK_REQUEST_COUNTER              3
00036 /** Flag Bit Definition */
00037 #define NEIGH_DEV_MASK                          0x0200
00038 #define NEIGH_FFD_DEV                           0x0200  /** FFD Router Device */
00039 #define NEIGH_RFD_DEV                           0x0000  /** RFD Router Device */
00040 #define NEIGH_RX_ON_IDLE                        0x0100 /** Radio is ON when mac is at idle */
00041 #define NEIGH_HANDSHAKE_READY                   0x0080 /** MLE association is ready or MAC association complete */
00042 #define NEIGH_SECURITY_HANSHAKE_PENGING_FLAG    0x0040 /** Indicate that Security Handshake is not ready with this neighbour  */
00043 #define NEIGH_PRIORITY_FLAG                     0x0020 /** Indicate priority Neighbor (Cordinator or ND/RPL Router) */
00044 #define NEIGH_RESERVED_FLAG                     0x0010
00045 #define NEIGH_IDR_MASK                          0x000f /** MLE Spesific IDR value */
00046 
00047 /** Mode bit definition for MLE */
00048 #define NEIGH_MODE_DEV_MASK 2
00049 #define NEIGH_MODE_FFD_DEV 2
00050 #define NEIGH_MODE_RFD_DEV 0
00051 #define NEIGH_MODE_RX_ON_IDLE 8
00052 
00053 #define NEIGH_MAX_KEY_TABLE_SIZE            2
00054 
00055 /*!
00056  * \enum keypair_key_state_e
00057  * \brief Key Pair key state.
00058  */
00059 typedef enum keypair_key_state_e {
00060     KEYPAIR_NOT_VALID = 0,          /*!<  Key info idle state */
00061     KEYPAIR_FOR_TX_RX,              /*!<  Primary Key */
00062     KEYPAIR_FOR_RX,                 /*!<  Secondary key only for RX */
00063     KEYPAIR_WAIT_RX_TO_PRIMARY      /*!<  After key update process key need to be trig by network cordinator */
00064 } keypair_key_state_e;
00065 
00066 /*!
00067  * \enum neighbor_address_type_e
00068  * \brief Address Type.
00069  */
00070 typedef enum neighbor_address_type_e {
00071     NEIGH_64_BIT_ADDRESS = 0,           /*!<  64-bit MAC address */
00072     NEIGH_16_BIT_ADDRESS,               /*!<  16-bit MAC address */
00073 
00074     NEIGH__TIMED_OUT,                   /*!<  timed-out entry (internal use) */
00075 } neighbor_address_type_e;
00076 
00077 /*!
00078  * \struct neighbor_keypair_info_s
00079  *
00080  * \brief Key pair info structure.
00081  */
00082 typedef struct neighbor_keypair_info_s {
00083     uint8_t  aes_key [16];                   /*!< Unique key pair key */
00084     uint8_t  key_id ;                        /*!< Unique key pair id */
00085     uint32_t input_security_frame_counter ;  /*!< Accepted highest Frame Counter */
00086     uint16_t missed_frame_counters ;         /*!< Bit mask for detect missed packet counters bit 0 is is always value from  input_security_frame_counter */
00087     uint32_t output_security_frame_counter ; /*!< Output Frame counter */
00088     keypair_key_state_e  key_state ;         /*!< Define, Primary, Secondary and coming key state */
00089 } neighbor_keypair_info_s;
00090 
00091 /*!
00092  * \struct neighbor_generic_sec_info_s
00093  *
00094  * \brief Generic Security key components.
00095  */
00096 typedef struct neighbor_generic_sec_info_s {
00097     uint8_t key_id ;                     /*!< Security Key Id */
00098     uint32_t security_frame_counter ;    /*!< Security frame counter for generic network Key */
00099     uint16_t missed_frame_counters ;     /*!< Bit mask for detect missed packet counters bit 0 is is allways value from  accepted_security_frame_counter */
00100 } neighbor_generic_sec_info_s;
00101 
00102 /*!
00103  * \struct neighbor_sec_key_rx_components_s
00104  *
00105  * \brief Security RX key component info structure.
00106  */
00107 typedef struct neighbor_sec_key_rx_components_s {
00108     neighbor_generic_sec_info_s component_table [NEIGH_MAX_KEY_TABLE_SIZE]; /*!< Security Key Id component table */
00109     uint8_t default_ptr ;/*!< Indicate primary entry 0 or 1 */
00110 } neighbor_sec_key_rx_components_s;
00111 
00112 /*!
00113  * \struct neighbor_keypair_components_s
00114  *
00115  * \brief Security Key pair component table info structure.
00116  */
00117 typedef struct neighbor_keypair_components_s {
00118     neighbor_keypair_info_s key_pair_table [NEIGH_MAX_KEY_TABLE_SIZE]; /*!< Security Key pair component table */
00119     uint8_t default_ptr ; /*!< Indicate primary entry 0 or 1 */
00120 } neighbor_keypair_components_s;
00121 
00122 /*!
00123  * \struct neighbor_lqi_info_s
00124  *
00125  * \brief Neighbour LQI info structure.
00126  */
00127 typedef struct neighbor_lqi_info_s {
00128     uint8_t calculated_avarage_lqi ; /*!< Average LQI after  defined Sample Count*/
00129     uint16_t lqi_sample_sum ;        /*!< Sum of LQI's */
00130     uint8_t sample_counter ;         /*!< LQI sample counter */
00131 } neighbor_lqi_info_s;
00132 
00133 typedef struct neigh_cache_entry_s {
00134     uint16_t                            ttl;                /*!< Entry timeout tick value is interface specific MLE configured interface use 4 Second tick value */
00135     uint8_t                             link_req_counter;   /*!< This value is used when TTL goes to zero*/
00136     uint16_t                            timeout_rx;         /*!< Configured Timeout start value MLE define or MAC */
00137     uint8_t                             mac64[8];           /*!< EUI-64 for Node */
00138     uint16_t                            mac16;              /*!< Neighbor 16-bit Address, 0xffff if not configured */
00139     uint16_t                            flags;              /*!< Indicate Priority, Handshake Ready, Security active,Device Type & Receiver state at MAC idle state  */
00140     neighbor_lqi_info_s                 lqi_info;           /*!< Neighbor LQI info */
00141     uint8_t                             route_external_advertise;   /*!< Route external advertisement counter */
00142     neighbor_sec_key_rx_components_s    neighbor_sec_key_rx_components; /* Security RX key frame filters */
00143     neighbor_keypair_components_s       *neighbor_keypair_info; /* Optionally when node to node have unique key pairs */
00144     ns_list_link_t                      link;               /*!< List link entry */
00145 } neigh_cache_entry_s;
00146 
00147 #define NEIGH_ENTRY_PTR_ERR ((neigh_cache_entry_s *) -1)
00148 
00149 /*!
00150  * \struct neigh_cache_s
00151  *
00152  * \brief Top-level neighbour cache descriptor.
00153  *
00154  * This passed by reference to all APIs. Users should not manipulate contents.
00155  */
00156 typedef struct neigh_cache_s {
00157     NS_LIST_HEAD(neigh_cache_entry_s, link) head;
00158 } neigh_cache_s;
00159 
00160 /**
00161  * \brief A function to initialize a neighbor cache before use
00162  *
00163  * \param neigh_cache pointer to neighbor cache.
00164  */
00165 extern void neighbor_cache_init(neigh_cache_s *neigh_cache);
00166 
00167 /**
00168  * \brief A function to flush an entire neighbour cache
00169  *
00170  * \param neigh_cache pointer to neighbor cache.
00171  *
00172  * \return <n> The number of entries removed
00173  */
00174 extern int neighbor_cache_flush(neigh_cache_s *neigh_cache);
00175 
00176 /**
00177  * \brief Helper macro to get the first cache entry, for iteration.
00178  *
00179  * \param neigh_cache pointer to neighbor cache.
00180  *
00181  * \return pointer to first cache entry
00182  * \return NULL if cache empty
00183  */
00184 #define neighbor_cache_first(neigh_cache) ns_list_get_first(&(neigh_cache)->head)
00185 
00186 /**
00187  * \brief Helper macro to get the next cache entry, for iteration.
00188  *
00189  * Not safe for use if you're deleting entries - use
00190  * neighbor_cache_delete_by_pointer in that case.
00191  *
00192  * \param neigh_cache pointer to neighbor cache.
00193  * \param entry pointer to current neighbor cache entry.
00194  *
00195  * \return pointer to next cache entry
00196  * \return NULL if no more entries
00197  */
00198 #define neighbor_cache_entry_next(cache, entry) ns_list_get_next(&(cache)->head, entry)
00199 
00200 /**
00201  * \brief A function to create or return an existing neighbor cache entry.
00202  *
00203  * \param neigh_cache pointer to neighbor cache.
00204  * \param address_ptr pointer to EUI-64 address (64-bit)
00205  *
00206  * \return pointer to cache entry, possibly newly created.
00207  * \return NULL if entry not found or an unable to allocate memory for new entry
00208  */
00209 extern neigh_cache_entry_s *neighbor_cache_entry_create(neigh_cache_s *neigh_cache, const uint8_t address_ptr[8]);
00210 
00211 /**
00212  * \brief A function to locate an existing entry by address
00213  *
00214  * Note that this can re-order the cache, so could upset iteration using macros.
00215  *
00216  * \param neigh_cache pointer to neighbor cache.
00217  * \param address_type type for 16-bit or 64-bit address
00218  * \param address_ptr pointer to address of specified type
00219  *
00220  * \return pointer to cache entry
00221  * \return NULL if not found
00222  */
00223 extern neigh_cache_entry_s *neighbor_cache_entry_get(neigh_cache_s *neigh_cache, neighbor_address_type_e address_type, const void *address_ptr);
00224 
00225 /**
00226  * \brief A function to delete an entry by address.
00227  *
00228  * \param neigh_cache pointer to neighbor cache.
00229  * \param address_type type for 16-bit or 64-bit address
00230  * \param address_ptr pointer to address of specified type
00231  *
00232  * \return 0 Removed OK
00233  * \return -1 Entry not found
00234  */
00235 extern int8_t neighbor_cache_entry_delete(neigh_cache_s *neigh_cache, neighbor_address_type_e address_type, const void *address_ptr);
00236 
00237 /**
00238  * \brief A function to delete an entry by entry pointer.
00239  *
00240  * \param neigh_cache pointer to neighbor cache.
00241  * \param entry pointer to entry
00242  *
00243  * \return pointer to the next entry, to allow deletion during iteration
00244  * \return NULL if no more entries
00245  * \return NEIGH_ENTRY_PTR_ERR if entry pointer not found (no longer checked)
00246  */
00247 extern neigh_cache_entry_s *neighbor_cache_entry_delete_by_entry_pointer(neigh_cache_s *neigh_cache, neigh_cache_entry_s *entry);
00248 
00249 
00250 /**
00251  * \brief A function to get a timed-out neighbor entry.
00252  *
00253  * Returns an entry whose TTL field is set to zero.
00254  *
00255  * \param neigh_cache pointer to neighbor cache.
00256  *
00257  * \return pointer to a timed-out entry
00258  * \return NULL if no timed-out entries
00259  */
00260 extern neigh_cache_entry_s *neighbor_cache_entry_get_timed_out(neigh_cache_s *neigh_cache);
00261 
00262 /**
00263  * \brief A function to update Neighbor cache Time-To-Live values.
00264  *
00265  * This decrements the TTL for all entries in the cache. TTL values are
00266  * are clamped to not wrap past zero. When an entry's TTL value becomes zero,
00267  * link_req_counter is set to NEIGH_LINK_REQUEST_COUNTER. (Note that
00268  * newly-created entries have ttl and link_req_counter both zero - they will
00269  * need initialising before use).
00270  *
00271  * \param neigh_cache pointer to neighbor cache.
00272  * \param tick amount to decrement TTL
00273  *
00274  * \return total number of entries in the cache whose TTL is 0 after the update
00275  */
00276 extern int neighbor_cache_ttl_update(neigh_cache_s *neigh_cache, uint16_t ticks);
00277 
00278 #endif /* NEIGHBOR_TABLE_DEFINITION_H_ */