net_rpl.h

00001 /*
00002  * Copyright (c) 2013-2017 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 #ifndef _NS_RPL_H
00015 #define _NS_RPL_H
00016 
00017 #include "ns_types.h"
00018 
00019 #ifdef __cplusplus
00020 extern "C" {
00021 #endif
00022 
00023 /**
00024  * \file net_rpl.h
00025  * \brief ZigBeeIP Router and Border Router RPL API.
00026  *
00027  * This API is primarily used with a border router. You can also use it with a basic router.
00028  *
00029  * - arm_nwk_6lowpan_rpl_memory_limit_set(), Set RPL global memory limit sizes. Call this only at boot ones.
00030  * - arm_nwk_6lowpan_rpl_dodag_init(), Allocate and init RPL DODAG root.
00031  * - arm_nwk_6lowpan_rpl_dodag_remove(), Remove DDAG root, specifically.
00032  * - arm_nwk_6lowpan_rpl_dodag_start(), Activate RPL DODAG instance.
00033  * - arm_nwk_6lowpan_rpl_dodag_poison(), Trigger some poison advertisements for the current instance, and then become a leaf (so no more adverts are sent). If a DODAG root, this remains allocated so arm_nwk_6lowpan_rpl_dodag_remove() still needs to be called to free it, after delaying some seconds to allow the poison advertisements to be sent().
00034  * - arm_nwk_6lowpan_rpl_dodag_prefix_update(), Update prefix info to the root.
00035  * - arm_nwk_6lowpan_rpl_dodag_route_update(), Update route info to the root.
00036  * - arm_nwk_6lowpan_rpl_dodag_dao_trig(), Increment the DAO Trigger Sequence Number (DTSN), to cause downstream nodes to refresh their Destination Advertisement Objects (DAOs).
00037  * - arm_nwk_6lowpan_rpl_dodag_version_increment(), Increment the DODAG version to trigger a global DODAG repair.
00038  *
00039  * \section rpl-recommend RECOMMEND API for router and border router:
00040  * - rpl_instance_list_read(), Read active RPL instance list.
00041  * - rpl_read_dodag_info(), Read RPL DODAG information to rpl_dodag_info_t structure by selected RPL instance ID.
00042  *
00043  * \section rpl-dodag-init Steps to define a new RPL DODAG instance:
00044  *  1. Allocate RPL root base with arm_nwk_6lowpan_rpl_dodag_init().
00045  *  2. Set prefix 1 to root with arm_nwk_6lowpan_rpl_dodag_prefix_update().
00046  *  3. Set Route(s) to root with arm_nwk_6lowpan_rpl_dodag_route_update().
00047  *  4. Start Activate RPL DODAG:
00048  *   * arm_nwk_6lowpan_rpl_dodag_start() if RPL is generated after arm_nwk_interface().
00049  *
00050  */
00051 
00052 /** \name DoDag Root setups
00053  * <B>DODAGPreference (Prf):</B> A 3-bit unsigned integer that defines how
00054          preferable the root of this DODAG is compared to other DODAG
00055          roots within the instance. DAGPreference ranges from 0x00
00056          (least preferred) to 0x07 (most preferred). The default is 0
00057          (least preferred).
00058  *
00059  * @{
00060  */
00061 #define RPL_DODAG_PREF_MASK         0x07                          /**< Preference mask */
00062 #define RPL_DODAG_PREF(n)           ((n) & RPL_DODAG_PREF_MASK)   /**< DODAG preference */
00063 /** @} */
00064 
00065 
00066 /** \name Mode of Operation (MOP)
00067  * The Mode of Operation (MOP) field identifies
00068    the mode of operation of the RPL instance as administratively
00069    provisioned at and distributed by the DODAG root. All nodes
00070    joining the DODAG must be able to honor the MOP to
00071    fully participate as a router. Otherwise, they must only join as a leaf.
00072  * @{
00073  */
00074 #define RPL_MODE_MASK               0x38  /**< MOP mask */
00075 #define RPL_MODE_SHIFT              3     /**< shift count */
00076 #define RPL_MODE_NO_DOWNWARD        0x00  /**< No Downward routes maintained by RPL */
00077 #define RPL_MODE_NON_STORING        0x08  /**< Non-Storing Mode of Operation */
00078 #define RPL_MODE_STORING            0x10  /**< Storing Mode of Operation with no multicast support */
00079 #define RPL_MODE_STORING_MULTICAST  0x18  /**< Storing Mode of Operation with multicast support */
00080 #define RPL_MODE_P2P_DISCOVERY      0x20  /**< RFC 6997 */
00081 /** @} */
00082 
00083 /** Grounded (G): The Grounded 'G' flag indicates whether the DODAG
00084    advertised can satisfy the application-defined goal. If the
00085    flag is set, the DODAG is grounded. If the flag is cleared,
00086    the DODAG is floating.
00087 */
00088 #define RPL_GROUNDED                0x80
00089 
00090 /** \name FOR BACKWARDS COMPATIBILITY
00091  * @{
00092  */
00093 #define BR_DODAG_PREF_0             RPL_DODAG_PREF(0)     /**< backward compatibility */
00094 #define BR_DODAG_PREF_1             RPL_DODAG_PREF(1)     /**< backward compatibility */
00095 #define BR_DODAG_PREF_2             RPL_DODAG_PREF(2)     /**< backward compatibility */
00096 #define BR_DODAG_PREF_3             RPL_DODAG_PREF(3)     /**< backward compatibility */
00097 #define BR_DODAG_PREF_4             RPL_DODAG_PREF(4)     /**< backward compatibility */
00098 #define BR_DODAG_PREF_5             RPL_DODAG_PREF(5)     /**< backward compatibility */
00099 #define BR_DODAG_PREF_6             RPL_DODAG_PREF(6)     /**< backward compatibility */
00100 #define BR_DODAG_PREF_7             RPL_DODAG_PREF(7)     /**< backward compatibility */
00101 #define BR_DODAG_MOP_NON_STORING    RPL_MODE_NON_STORING  /**< backward compatibility */
00102 #define BR_DODAG_MOP_STORING        RPL_MODE_STORING      /**< backward compatibility */
00103 #define BR_DODAG_FLOATING           0                     /**< backward compatibility */
00104 #define BR_DODAG_GROUNDED           RPL_GROUNDED          /**< backward compatibility */
00105 /** @} */
00106 
00107 /** \name Compatibility for even older misspellings
00108  * @{
00109  */
00110 #define BR_DODAG_MOP_NON_STRORING   BR_DODAG_MOP_NON_STORING    /**< backward compatibility */
00111 #define BR_DODAG_MOP_STRORING       BR_DODAG_MOP_STORING        /**< backward compatibility */
00112 #define BR_DODAG_FLOATIN            BR_DODAG_FLOATING           /**< backward compatibility */
00113 /** @} */
00114 
00115 /** RPL ROOT parent flag */
00116 #define RPL_ROOT_PARENT             0
00117 /** RPL primary active primary_parent primary_parent_rank information is valid. */
00118 #define RPL_PRIMARY_PARENT_SET      1
00119 /** RPL secondary active secondary_parent secondary_parent_rank information is valid. */
00120 #define RPL_SECONDARY_PARENT_SET    2
00121 
00122 /** RPL prefix update flags for A-flag AUTONOMOUS address generation. */
00123 #define RPL_PREFIX_AUTONOMOUS_ADDRESS_FLAG 0x40
00124 /** RPL prefix update flags for R-Flag. */
00125 #define RPL_PREFIX_ROUTER_ADDRESS_FLAG 0x20
00126 
00127 /** Flag in RPL instance ID to indicate that it is a local instance. */
00128 #define RPL_INSTANCE_LOCAL          0x80
00129 
00130 /*!
00131  * \struct rpl_dodag_info_t
00132  * \brief RPL Instance DODAG info structure for rpl_read_dodag_info. Read RFC 6550 for more information and to make sure you know what you are doing.
00133  */
00134 typedef struct rpl_dodag_info_t {
00135     uint8_t dodag_id[16];           /**< RPL DODAG ID. */
00136     uint8_t instance_id;            /**< RPL instance ID. */
00137     uint8_t flags;                  /**< RPL DODAG Flags: (MOP,Grounded, Router Pref) */
00138     uint8_t version_num;            /**< RPL DODAG version number. */
00139     uint8_t DTSN;                   /**< RPL DODAG DAO trigger version number. */
00140     uint16_t curent_rank;           /**< RPL DODAG node current Rank. */
00141     uint8_t parent_flags;           /**< RPL DODAG parent Flags: RPL_ROOT_PARENT or RPL_PRIMARY_PARENT_SET, RPL_SECONDARY_PARENT_SET */
00142     uint8_t primary_parent[16];     /**< Primary Parent GP address if RPL_PRIMARY_PARENT_SET flag is active. */
00143     uint16_t primary_parent_rank;   /**< Primary Parent Rank if RPL_PRIMARY_PARENT_SET flag is active. */
00144     uint8_t secondary_parent[16];   /**< Secondary Parent GP address if RPL_SECONDARY_PARENT_SET flag is active. */
00145     uint16_t secondary_parent_rank; /**< Secondary Parent rank if RPL_SECONDARY_PARENT_SET flag is active. */
00146     uint16_t dag_min_hop_rank_inc;  /**< RPL DODAG conf DAG minimum rank increase. */
00147 } rpl_dodag_info_t;
00148 
00149 /*!
00150  * \struct dodag_config_t
00151  * \brief RPL DODAG config is used when allocating RPL base arm_nwk_6lowpan_rpl_dodag_init().
00152  */
00153 typedef struct dodag_config_t {
00154     uint8_t DAG_SEC_PCS;        /**< Path Control Size limits number of DAO parents. Possible values are 0-7, meaning 1-8 parents.
00155 (This also has an Authentication flag 0x10 – the “SEC”, but we don’t support that, and 4 reserved flags, so it is just the 3-bit PCS field). */
00156     uint8_t DAG_DIO_INT_DOUB;   /**< RPL Trickle DIOIntervalDoublings, recommended value 12. */
00157     uint8_t DAG_DIO_INT_MIN;    /**< RPL Trickle DIOIntervalMin, recommended value 9. */
00158     uint8_t DAG_DIO_REDU;       /**< RPL Trickle DIORedundancyConstant, recommended value 3. */
00159     uint16_t DAG_MAX_RANK_INC;  /**< RPL MaxRankIncrease, recommended value 2048. */
00160     uint16_t DAG_MIN_HOP_RANK_INC;  /**< RPL MinHopRankIncrease, recommended value 128. */
00161     uint16_t DAG_OCP;           /**< Objective code point, recommended value 1. */
00162     uint8_t LIFE_IN_SECONDS;    /**< Default lifetime for RPL routes, expressed in lifetime units. */
00163     uint16_t LIFETIME_UNIT;     /**< Defines the unit used to express route lifetimes, in seconds. */
00164 } dodag_config_t;
00165 
00166 /**
00167   * \brief RPL DODAG root base allocate.
00168   *
00169   * \param interface_id Interface ID
00170   * \param dodag_id A pointer to unique DODAGID. This must be the node's GP address in the ZigBeeIP network.
00171   * \param config A pointer to the DODAG configure structure.
00172   * \param instace_id Instance ID for RPL DODAG.
00173   * \param flags Defines RPL MOP and DODAG pref. ZigBeeIP should use (BR_DODAG_MOP_NON_STORING | BR_DODAG_PREF_7).
00174   *
00175   * \return 0, Allocate OK.
00176   * \return -1, Allocate fail (The node is already connected to the same instance or the memory allocate fails).
00177   * \return -2, DODAG configuration parameter failure.
00178   *
00179   */
00180 extern int8_t arm_nwk_6lowpan_rpl_dodag_init(int8_t interface_id, const uint8_t *dodag_id, const dodag_config_t *config, uint8_t instace_id, uint8_t flags);
00181 
00182 /**
00183   * \brief RPL Global memory size limits.
00184   *
00185   * Calling this function you can update default memory limits. Soft default is 1024 and hard limit is 2048.
00186   * \param soft_limit When RPL reach this state at total allocation it start cleaning unused data.
00187   * \param hard_limit Total allocation limit. 0 means no limit and > 0 define hard limit. When hard limit > 0 soft_limit must be smaller than hard.
00188   *
00189   * \return 0, Set OK.
00190   * \return -1, Unsupported parameter
00191   *
00192   */
00193 extern int8_t arm_nwk_6lowpan_rpl_memory_limit_set(size_t soft_limit, size_t hard_limit);
00194 /**
00195   * \brief RPL DODAG remove by given interface ID.
00196   *
00197   * \param interface_id Interface ID for removed DODAG.
00198   *
00199   * \return 0, Remove OK.
00200   * \return -1, Remove fail.
00201   *
00202   */
00203 extern int8_t arm_nwk_6lowpan_rpl_dodag_remove(int8_t interface_id);
00204 
00205 /**
00206   * \brief Activate RPL DODAG by given Interface ID.
00207   *
00208   * \param interface_id Interface ID for start DODAG root.
00209   *
00210   * \return 0, Start OK.
00211   * \return <0, Start fail.
00212   *
00213   */
00214 extern int8_t arm_nwk_6lowpan_rpl_dodag_start(int8_t interface_id);
00215 
00216 /**
00217   * \brief RPL prefix information update.
00218   *
00219   * \param interface_id Root interface ID
00220   * \param prefix_ptr A pointer to IPv6 prefix (16-bytes).
00221   * \param prefix_len Prefix length (should be 64).
00222   * \param flags  Define R-flag (RPL_PREFIX_ROUTER_ADDRESS_FLAG), A-flag (RPL_PREFIX_AUTONOMOUS_ADDRESS_FLAG).
00223   * \param lifetime Prefix lifetime.
00224   *
00225   *
00226   * \return 0, Update OK.
00227   * \return <0, Update fail.
00228   *
00229   */
00230 extern int8_t arm_nwk_6lowpan_rpl_dodag_prefix_update(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len, uint8_t flags, uint32_t lifetime);
00231 /**
00232   * \brief RPL route information update.
00233   *
00234   * \param interface_id Root interface ID.
00235   * \param route_ptr A pointer to IPv6 prefix (16-bytes).
00236   * \param prefix_len Prefix length (should be 64).
00237   * \param flags Define R-flag (RPL_PREFIX_ROUTER_ADDRESS_FLAG).
00238   * \param lifetime Route lifetime.
00239   *
00240   *
00241   * \return 0, Update OK.
00242   * \return <0, Update fail.
00243   *
00244   */
00245 extern int8_t arm_nwk_6lowpan_rpl_dodag_route_update(int8_t interface_id, uint8_t *route_ptr, uint8_t prefix_len, uint8_t flags, uint32_t lifetime);
00246 
00247 /**
00248   * \brief RPL DODAG poison.
00249   *
00250   * This function poisons the current RPL instance. After a few seconds arm_nwk_6lowpan_rpl_dodag_remove() can also clean the root.
00251   *
00252   * \param interface_id Interface ID that defines the RPL instance to be poisoned.
00253   *
00254   *
00255   * \return 0, Poison OK.
00256   * \return <0, Poison fail.
00257   *
00258   */
00259 extern int8_t arm_nwk_6lowpan_rpl_dodag_poison(int8_t interface_id);
00260 /**
00261   * \brief Trigger RPL DODAG DAO by DTSN increment.
00262   *
00263   *
00264   * \param interface_id Network interface ID.
00265   *
00266   *
00267   * \return 0, DAO trig OK
00268   * \return <0, DAO trig Fail
00269   *
00270   */
00271 extern int8_t arm_nwk_6lowpan_rpl_dodag_dao_trig(int8_t interface_id);
00272 /**
00273   * \brief RPL DODAG version update.
00274   *
00275   * Network devices need to reset the current RPL instance and do unicast DIS/DIO and DAO/DAO ACK handshake.
00276   *
00277   * \param interface_id Root interface ID.
00278   *
00279   *
00280   * \return 0, Version update OK.
00281   * \return <0, Version update fail.
00282   *
00283   */
00284 extern int8_t arm_nwk_6lowpan_rpl_dodag_version_increment(int8_t interface_id);
00285 /**
00286   * \brief Read RPL instance list of a node.
00287   *
00288   * Global instances are output as a single byte containing the instance ID;
00289   * local instances are output as the instance ID followed by the 16-byte DODAG ID.
00290   *
00291   * \param buffer_ptr A pointer to the location of the instance IDs.
00292   * \param buffer_size Instance list buffer size.
00293   *
00294   * \return RPL instance count (not necessarily number of bytes, if local instances).
00295   *
00296   */
00297 extern uint8_t rpl_instance_list_read(uint8_t *buffer_ptr, uint8_t buffer_size);
00298 /**
00299   * \brief Read DODAG information by given RPL instance ID.
00300   *
00301   * If it is a local instance ID, dodag_ptr must contain the DODAG ID on entry.
00302   *
00303   * \param dodag_ptr A pointer to DODAG information structure.
00304   * \param instance_id Read instance ID.
00305   *
00306   * \return 1, Read OK.
00307   * \return 0, Read fail.
00308   *
00309   */
00310 extern uint8_t rpl_read_dodag_info(rpl_dodag_info_t *dodag_ptr, uint8_t instance_id);
00311 /**
00312   * \brief RPL DODAG preference set.
00313   *
00314   * \param interface_id Interface ID in which the RPL instance updates the DODAG preference.
00315   * \param preference DODAG preference. 0 to 7. 0 is least preferred.
00316   *
00317   * \return 0, Update OK
00318   * \return <0, Update Fail
00319   *
00320   */
00321 extern int8_t arm_nwk_6lowpan_rpl_dodag_pref_set(int8_t interface_id, uint8_t preference);
00322 
00323 #ifdef __cplusplus
00324 }
00325 #endif
00326 #endif /*_NS_RPL_H*/