net_rpl.h

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