net_rpl.h

00001 /*
00002  * Copyright (c) 2014-2015 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_dodag_init(), Allocate and init RPL DODAG root.
00030  * - arm_nwk_6lowpan_rpl_dodag_remove(), Remove DDAG root, specifically.
00031  * - arm_nwk_6lowpan_rpl_dodag_start(), Activate RPL DODAG instance.
00032  * - 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().
00033  * - arm_nwk_6lowpan_rpl_dodag_prefix_update(), Update prefix info to the root.
00034  * - arm_nwk_6lowpan_rpl_dodag_route_update(), Update route info to the root.
00035  * - 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).
00036  * - arm_nwk_6lowpan_rpl_dodag_version_increment(), Increment the DODAG version to trigger a global DODAG repair.
00037  *
00038  * \section rpl-recommend RECOMMEND API for router and border router:
00039  * - rpl_instance_list_read(), Read active RPL instance list.
00040  * - rpl_read_dodag_info(), Read RPL DODAG information to rpl_dodag_info_t structure by selected RPL instance ID.
00041  *
00042  * \section rpl-dodag-init Steps to define a new RPL DODAG instance:
00043  *  1. Allocate RPL root base with arm_nwk_6lowpan_rpl_dodag_init().
00044  *  2. Set prefix 1 to root with arm_nwk_6lowpan_rpl_dodag_prefix_update().
00045  *  3. Set Route(s) to root with arm_nwk_6lowpan_rpl_dodag_route_update().
00046  *  4. Start Activate RPL DODAG:
00047  *   * arm_nwk_6lowpan_rpl_dodag_start() if RPL is generated after arm_nwk_interface().
00048  *
00049  */
00050 
00051 /* DoDag Root setups */
00052 /* DODAGPreference (Prf): A 3-bit unsigned integer that defines how
00053          preferable the root of this DODAG is compared to other DODAG
00054          roots within the instance. DAGPreference ranges from 0x00
00055          (least preferred) to 0x07 (most preferred). The default is 0
00056          (least preferred). */
00057 #define RPL_DODAG_PREF_MASK         0x07
00058 #define RPL_DODAG_PREF(n)           ((n) & RPL_DODAG_PREF_MASK)
00059 
00060 /* Mode of Operation (MOP): The Mode of Operation (MOP) field identifies
00061    the mode of operation of the RPL instance as administratively
00062    provisioned at and distributed by the DODAG root. All nodes
00063    joining the DODAG must be able to honor the MOP to
00064    fully participate as a router. Otherwise, they must only join as a leaf.
00065 */
00066 #define RPL_MODE_MASK               0x38
00067 #define RPL_MODE_SHIFT              3
00068 #define RPL_MODE_NO_DOWNWARD        0x00
00069 #define RPL_MODE_NON_STORING        0x08
00070 #define RPL_MODE_STORING            0x10
00071 #define RPL_MODE_STORING_MULTICAST  0x18
00072 #define RPL_MODE_P2P_DISCOVERY      0x20 /* RFC 6997 */
00073 
00074 /* Grounded (G): The Grounded 'G' flag indicates whether the DODAG
00075    advertised can satisfy the application-defined goal. If the
00076    flag is set, the DODAG is grounded. If the flag is cleared,
00077    the DODAG is floating.
00078 */
00079 #define RPL_GROUNDED                0x80
00080 
00081 /** FOR BACKWARDS COMPATIBILITY **/
00082 #define BR_DODAG_PREF_0             RPL_DODAG_PREF(0)
00083 #define BR_DODAG_PREF_1             RPL_DODAG_PREF(1)
00084 #define BR_DODAG_PREF_2             RPL_DODAG_PREF(2)
00085 #define BR_DODAG_PREF_3             RPL_DODAG_PREF(3)
00086 #define BR_DODAG_PREF_4             RPL_DODAG_PREF(4)
00087 #define BR_DODAG_PREF_5             RPL_DODAG_PREF(5)
00088 #define BR_DODAG_PREF_6             RPL_DODAG_PREF(6)
00089 #define BR_DODAG_PREF_7             RPL_DODAG_PREF(7)
00090 #define BR_DODAG_MOP_NON_STORING    RPL_MODE_NON_STORING
00091 #define BR_DODAG_MOP_STORING        RPL_MODE_STORING
00092 #define BR_DODAG_FLOATING           0
00093 #define BR_DODAG_GROUNDED           RPL_GROUNDED
00094 
00095 /* Compatibility for even older misspellings */
00096 #define BR_DODAG_MOP_NON_STRORING   BR_DODAG_MOP_NON_STORING
00097 #define BR_DODAG_MOP_STRORING       BR_DODAG_MOP_STORING
00098 #define BR_DODAG_FLOATIN            BR_DODAG_FLOATING
00099 
00100 /** RPL ROOT parent flag */
00101 #define RPL_ROOT_PARENT             0
00102 /** RPL primary active primary_parent primary_parent_rank information is valid. */
00103 #define RPL_PRIMARY_PARENT_SET      1
00104 /** RPL secondary active secondary_parent secondary_parent_rank information is valid. */
00105 #define RPL_SECONDARY_PARENT_SET    2
00106 
00107 /** RPL prefix update flags for A-flag AUTONOMOUS address generation. */
00108 #define RPL_PREFIX_AUTONOMOUS_ADDRESS_FLAG 0x40
00109 /** RPL prefix update flags for R-Flag. */
00110 #define RPL_PREFIX_ROUTER_ADDRESS_FLAG 0x20
00111 
00112 /** Flag in RPL instance ID to indicate that it is a local instance. */
00113 #define RPL_INSTANCE_LOCAL          0x80
00114 
00115 /*!
00116  * \struct rpl_dodag_info_t
00117  * \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.
00118  */
00119 typedef struct rpl_dodag_info_t {
00120     uint8_t dodag_id[16];           /**< RPL DODAG ID. */
00121     uint8_t instance_id;            /**< RPL instance ID. */
00122     uint8_t flags;                  /**< RPL DODAG Flags: (MOP,Grounded, Router Pref) */
00123     uint8_t version_num;            /**< RPL DODAG version number. */
00124     uint8_t DTSN;                   /**< RPL DODAG DAO trigger version number. */
00125     uint16_t curent_rank;           /**< RPL DODAG node current Rank. */
00126     uint8_t parent_flags;           /**< RPL DODAG parent Flags: RPL_ROOT_PARENT or RPL_PRIMARY_PARENT_SET, RPL_SECONDARY_PARENT_SET */
00127     uint8_t primary_parent[16];     /**< Primary Parent GP address if RPL_PRIMARY_PARENT_SET flag is active. */
00128     uint16_t primary_parent_rank;   /**< Primary Parent Rank if RPL_PRIMARY_PARENT_SET flag is active. */
00129     uint8_t secondary_parent[16];   /**< Secondary Parent GP address if RPL_SECONDARY_PARENT_SET flag is active. */
00130     uint16_t secondary_parent_rank; /**< Secondary Parent rank if RPL_SECONDARY_PARENT_SET flag is active. */
00131     uint16_t dag_min_hop_rank_inc;  /**< RPL DODAG conf DAG minimum rank increase. */
00132 } rpl_dodag_info_t;
00133 
00134 /*!
00135  * \struct dodag_config_t
00136  * \brief RPL DODAG config is used when allocating RPL base arm_nwk_6lowpan_rpl_dodag_init().
00137  */
00138 typedef struct dodag_config_t {
00139     uint8_t DAG_SEC_PCS;        /**< Path Control Size limits number of DAO parents. Possible values are 0-7, meaning 1-8 parents.
00140 (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). */
00141     uint8_t DAG_DIO_INT_DOUB;   /**< RPL Trickle DIOIntervalDoublings, recommended value 12. */
00142     uint8_t DAG_DIO_INT_MIN;    /**< RPL Trickle DIOIntervalMin, recommended value 9. */
00143     uint8_t DAG_DIO_REDU;       /**< RPL Trickle DIORedundancyConstant, recommended value 3. */
00144     uint16_t DAG_MAX_RANK_INC;  /**< RPL MaxRankIncrease, recommended value 2048. */
00145     uint16_t DAG_MIN_HOP_RANK_INC;  /**< RPL MinHopRankIncrease, recommended value 128. */
00146     uint16_t DAG_OCP;           /**< Objective code point, recommended value 1. */
00147     uint8_t LIFE_IN_SECONDS;    /**< Default lifetime for RPL routes, expressed in lifetime units. */
00148     uint16_t LIFETIME_UNIT;     /**< Defines the unit used to express route lifetimes, in seconds. */
00149 } dodag_config_t;
00150 
00151 /**
00152   * \brief RPL DODAG root base allocate.
00153   *
00154   * \param dodag_id A pointer to unique DODAGID. This must be the node's GP address in the ZigBeeIP network.
00155   * \param config A pointer to the DODAG configure structure.
00156   * \param instace_id Instance ID for RPL DODAG.
00157   * \param flags Defines RPL MOP and DODAG pref. ZigBeeIP should use (BR_DODAG_MOP_NON_STORING | BR_DODAG_PREF_7).
00158   *
00159   * \return 0, Allocate OK.
00160   * \return -1, Allocate fail (The node is already connected to the same instance or the memory allocate fails).
00161   * \return -2, DODAG configuration parameter failure.
00162   *
00163   */
00164 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);
00165 /**
00166   * \brief RPL DODAG remove by given instance ID.
00167   *
00168   * \param instace_id Instance ID for removed DODAG.
00169   *
00170   * \return 0, Remove OK.
00171   * \return -1, Remove fail.
00172   *
00173   */
00174 extern int8_t arm_nwk_6lowpan_rpl_dodag_remove(int8_t interface_id);
00175 
00176 /**
00177   * \brief Activate RPL DODAG by given Interface ID.
00178   *
00179   * \param interface_id Interface ID for start DODAG root.
00180   *
00181   * \return 0, Start OK.
00182   * \return <0, Start fail.
00183   *
00184   */
00185 extern int8_t arm_nwk_6lowpan_rpl_dodag_start(int8_t interface_id);
00186 
00187 /**
00188   * \brief RPL prefix information update.
00189   *
00190   * \param interface_id Root interface ID
00191   * \param prefix_ptr A pointer to IPv6 prefix (16-bytes).
00192   * \param prefix_len Prefix length (should be 64).
00193   * \param flags  Define R-flag (RPL_PREFIX_ROUTER_ADDRESS_FLAG), A-flag (RPL_PREFIX_AUTONOMOUS_ADDRESS_FLAG).
00194   * \param lifetime Prefix lifetime.
00195   *
00196   *
00197   * \return 0, Update OK.
00198   * \return <0, Update fail.
00199   *
00200   */
00201 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);
00202 /**
00203   * \brief RPL route information update.
00204   *
00205   * \param interface_id Root interface ID.
00206   * \param route_ptr A pointer to IPv6 prefix (16-bytes).
00207   * \param prefix_len Prefix length (should be 64).
00208   * \param flags Define R-flag (RPL_PREFIX_ROUTER_ADDRESS_FLAG).
00209   * \param lifetime Route lifetime.
00210   *
00211   *
00212   * \return 0, Update OK.
00213   * \return <0, Update fail.
00214   *
00215   */
00216 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);
00217 
00218 /**
00219   * \brief RPL DODAG poison.
00220   *
00221   * This function poisons the current RPL instance. After a few seconds arm_nwk_6lowpan_rpl_dodag_remove() can also clean the root.
00222   *
00223   * \param interface_id Interface ID that defines the RPL instance to be poisoned.
00224   *
00225   *
00226   * \return 0, Poison OK.
00227   * \return <0, Poison fail.
00228   *
00229   */
00230 extern int8_t arm_nwk_6lowpan_rpl_dodag_poison(int8_t interface_id);
00231 /**
00232   * \brief Trigger RPL DODAG DAO by DTSN increment.
00233   *
00234   *
00235   * \param interface_id Network interface ID.
00236   *
00237   *
00238   * \return 0, DAO trig OK
00239   * \return <0, DAO trig Fail
00240   *
00241   */
00242 extern int8_t arm_nwk_6lowpan_rpl_dodag_dao_trig(int8_t interface_id);
00243 /**
00244   * \brief RPL DODAG version update.
00245   *
00246   * Network devices need to reset the current RPL instance and do unicast DIS/DIO and DAO/DAO ACK handshake.
00247   *
00248   * \param interface_id Root interface ID.
00249   *
00250   *
00251   * \return 0, Version update OK.
00252   * \return <0, Version update fail.
00253   *
00254   */
00255 extern int8_t arm_nwk_6lowpan_rpl_dodag_version_increment(int8_t interface_id);
00256 /**
00257   * \brief Read RPL instance list of a node.
00258   *
00259   * Global instances are output as a single byte containing the instance ID;
00260   * local instances are output as the instance ID followed by the 16-byte DODAG ID.
00261   *
00262   * \param buffer_ptr A pointer to the location of the instance IDs.
00263   * \param buffer_size Instance list buffer size.
00264   *
00265   * \return RPL instance count (not necessarily number of bytes, if local instances).
00266   *
00267   */
00268 extern uint8_t rpl_instance_list_read(uint8_t *buffer_ptr, uint8_t buffer_size);
00269 /**
00270   * \brief Read DODAG information by given RPL instance ID.
00271   *
00272   * If it is a local instance ID, dodag_ptr must contain the DODAG ID on entry.
00273   *
00274   * \param dodag_ptr A pointer to DODAG information structure.
00275   * \param instance_id Read instance ID.
00276   *
00277   * \return 1, Read OK.
00278   * \return 0, Read fail.
00279   *
00280   */
00281 extern uint8_t rpl_read_dodag_info(rpl_dodag_info_t *dodag_ptr, uint8_t instance_id);
00282 /**
00283   * \brief RPL DODAG preference set.
00284   *
00285   * \param interface_id Interface ID in which the RPL instance updates the DODAG preference.
00286   * \param preference DODAG preference. 0 to 7. 0 is least preferred.
00287   *
00288   * \return 0, Update OK
00289   * \return <0, Update Fail
00290   *
00291   */
00292 extern int8_t arm_nwk_6lowpan_rpl_dodag_pref_set(int8_t interface_id, uint8_t preference);
00293 
00294 #ifdef __cplusplus
00295 }
00296 #endif
00297 #endif /*_NS_RPL_H*/