net_6lowpan_parameter_api.h

00001 /*
00002  * Copyright (c) 2014-2015, 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 
00019 #ifndef NET_6LOWPAN_PARAMETER_API_H_
00020 #define NET_6LOWPAN_PARAMETER_API_H_
00021 
00022 #include "ns_types.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /**
00029  * \file net_6lowpan_parameter_api.h
00030  * \brief API for setting up 6LoWPAN network parameters
00031  *
00032  * \section tim-para-def 6LoWPAN Default timer values
00033  * - Timer values are specified in ticks
00034  * - Default 6LoWPAN ND Bootstrap tick is 1 tick = 100ms
00035  *
00036  * - Default Random value 0x1f = [0..3.1] seconds.
00037  * - Default RS retry counter 3.
00038  * - Default RS retry interval is 15 + random --> [1.5..4.6] seconds.
00039  * - Default NS retry counter 5.
00040  * - Default NS retry interval is 100 + random + backoff --> [10.0..13.1+10.0*retry] seconds.
00041  * - Default NS retry linear backoff is 100.
00042  *
00043  * - Default RA transmit interval is 150, exponentially backed off --> 15.0, 30.0, 60.0 seconds.
00044  * - Default RA transmit counter is 5.
00045  *
00046  * - Default NS forward timeout is 300 --> 30.0 seconds.
00047  *
00048  *  \section Changing random and interval values
00049  *  - Random parameter + NS or RS minimum interval must sum to less than 0xFFFF.
00050  *  - Random maximums are manipulated as bit masks, so must be (2^n)-1.
00051  */
00052 
00053 /*!
00054  * \struct nd_parameters_s
00055  * \brief 6LoWPAN Neighbor Discovery parameters
00056  */
00057 typedef struct nd_parameters_s {
00058     uint8_t rs_retry_max;                   /**< Define Bootstrap RS max retry count. */
00059     uint8_t ns_retry_max;                   /**< Define Bootstrap NS max retry count. */
00060     uint16_t timer_random_max;              /**< Define Interval random in 6LoWPAN bootstrap timer ticks for RS, NS and starting NS - NA process.  */
00061     uint16_t rs_retry_interval_min;         /**< Define Retry interval in 6LoWPAN bootstrap timer ticks waiting for RA. */
00062     uint16_t ns_retry_interval_min;         /**< Define Retry interval in 6LoWPAN bootstrap timer ticks waiting for NA. */
00063     uint16_t ns_retry_linear_backoff;       /**< Define Retry interval linear backoff in bootstrap timer ticks. */
00064     bool multihop_dad;                      /**< Define whether to perform duplicate address detection with border router or locally. */
00065     bool iids_map_to_mac;                   /**< Define whether IPv6 IIDs can be assumed to be based on MAC address (so no address resolution by routers). */
00066     bool send_nud_probes;                   /**< Define whether IPv6 NUD probes are enabled (disabling may limit fault detection). */
00067     uint16_t ra_interval_min;               /**< Define initial transmission interval for Router Advertisements in standard timer ticks. */
00068     uint8_t ra_transmits;                   /**< Define number of RA transmissions. */
00069     uint8_t ra_cur_hop_limit;               /**< Define the value of current hop limit in RAs. */
00070     uint32_t ra_link_mtu;                   /**< Define the value of link MTU in RAs. */
00071     uint32_t ra_reachable_time;             /**< Define the value of reachable time in RAs (in milliseconds). */
00072     uint32_t ra_retrans_timer;              /**< Define the value of retrans timer in RAs (in milliseconds). */
00073     uint16_t ns_forward_timeout;            /**< Define timeout when forwarding NS messages - if reached, our own address discovery process is restarted. */
00074 } nd_parameters_s;
00075 
00076 /**
00077  * \brief Function to change 6LoWPAN ND bootstrap parameters.
00078  *
00079  * Note: This function should be called after net_init_core() and definitely
00080  * before creating any 6LoWPAN interface.
00081  *
00082  * For future compatibility, to support extensions to this structure, read
00083  * the current parameters using net_6lowpan_timer_parameter_read(),
00084  * modify known fields, then set.
00085  *
00086  * \param parameter_ptr Pointer for ND parameters.
00087  *
00088  * \return 0, Change OK.
00089  * \return -1, Invalid values.
00090  * \return -2, 6LoWPAN interface already active.
00091  *
00092  */
00093 extern int8_t net_6lowpan_nd_parameter_set(const nd_parameters_s *parameter_ptr);
00094 
00095 /**
00096  * \brief Function to change 6LoWPAN bootstrap base tick 100ms multiplier.
00097  *
00098  * Note: This function MUST be called after net_init_core(). Do not change this
00099  * unless you really want 6LoWPAN bootstrap working slower than normally.
00100  *
00101  * This only affects the bootstrap timers.
00102  *
00103  * \param base_tick_x_100ms Tick resolution in 100ms units.
00104  *        Max value 10 --> 10 times slower functionality
00105  *
00106  * \return 0, Change OK.
00107  * \return -1, Invalid value (<1 or >10).
00108  *
00109  */
00110 extern int8_t net_6lowpan_nd_timer_base_tick_set(uint8_t base_tick_x_100ms);
00111 
00112 /**
00113  * \brief Function to read 6LoWPAN ND bootstrap parameters.
00114  *
00115  * \param parameter_ptr Output pointer for ND parameters.
00116  *
00117  */
00118 extern void net_6lowpan_nd_parameter_read(nd_parameters_s *parameter_ptr);
00119 
00120 #ifdef __cplusplus
00121 }
00122 #endif
00123 
00124 #endif /* NET_6LOWPAN_DEFAULT_PARAMETER_API_H_ */