Contiki 2.6

rpl.h

00001 /*
00002  * Copyright (c) 2010, Swedish Institute of Computer Science.
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the Institute nor the names of its contributors
00014  *    may be used to endorse or promote products derived from this software
00015  *    without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00027  * SUCH DAMAGE.
00028  *
00029  * This file is part of the Contiki operating system.
00030  *
00031  * \file
00032  *      Public API declarations for ContikiRPL.
00033  * \author
00034  *      Joakim Eriksson <joakime@sics.se> & Nicolas Tsiftes <nvt@sics.se>
00035  *
00036  */
00037 
00038 #ifndef RPL_H
00039 #define RPL_H
00040 
00041 #include "rpl-conf.h"
00042 
00043 #include "lib/list.h"
00044 #include "net/uip.h"
00045 #include "net/uip-ds6.h"
00046 #include "sys/ctimer.h"
00047 
00048 /*---------------------------------------------------------------------------*/
00049 /* The amount of parents that this node has in a particular DAG. */
00050 #define RPL_PARENT_COUNT(dag)   list_length((dag)->parents)
00051 /*---------------------------------------------------------------------------*/
00052 typedef uint16_t rpl_rank_t;
00053 typedef uint16_t rpl_ocp_t;
00054 /*---------------------------------------------------------------------------*/
00055 /* DAG Metric Container Object Types, to be confirmed by IANA. */
00056 #define RPL_DAG_MC_NONE                 0 /* Local identifier for empty MC */
00057 #define RPL_DAG_MC_NSA                  1 /* Node State and Attributes */
00058 #define RPL_DAG_MC_ENERGY               2 /* Node Energy */
00059 #define RPL_DAG_MC_HOPCOUNT             3 /* Hop Count */
00060 #define RPL_DAG_MC_THROUGHPUT           4 /* Throughput */
00061 #define RPL_DAG_MC_LATENCY              5 /* Latency */
00062 #define RPL_DAG_MC_LQL                  6 /* Link Quality Level */
00063 #define RPL_DAG_MC_ETX                  7 /* Expected Transmission Count */
00064 #define RPL_DAG_MC_LC                   8 /* Link Color */
00065 
00066 /* DAG Metric Container flags. */
00067 #define RPL_DAG_MC_FLAG_P               0x8
00068 #define RPL_DAG_MC_FLAG_C               0x4
00069 #define RPL_DAG_MC_FLAG_O               0x2
00070 #define RPL_DAG_MC_FLAG_R               0x1
00071 
00072 /* DAG Metric Container aggregation mode. */
00073 #define RPL_DAG_MC_AGGR_ADDITIVE        0
00074 #define RPL_DAG_MC_AGGR_MAXIMUM         1
00075 #define RPL_DAG_MC_AGGR_MINIMUM         2
00076 #define RPL_DAG_MC_AGGR_MULTIPLICATIVE  3
00077 
00078 /* The bit index within the flags field of
00079    the rpl_metric_object_energy structure. */
00080 #define RPL_DAG_MC_ENERGY_INCLUDED      3
00081 #define RPL_DAG_MC_ENERGY_TYPE          1
00082 #define RPL_DAG_MC_ENERGY_ESTIMATION    0
00083 
00084 #define RPL_DAG_MC_ENERGY_TYPE_MAINS            0
00085 #define RPL_DAG_MC_ENERGY_TYPE_BATTERY          1
00086 #define RPL_DAG_MC_ENERGY_TYPE_SCAVENGING       2
00087 
00088 struct rpl_metric_object_energy {
00089   uint8_t flags;
00090   uint8_t energy_est;
00091 };
00092 
00093 /* Logical representation of a DAG Metric Container. */
00094 struct rpl_metric_container {
00095   uint8_t type;
00096   uint8_t flags;
00097   uint8_t aggr;
00098   uint8_t prec;
00099   uint8_t length;
00100   union metric_object {
00101     struct rpl_metric_object_energy energy;
00102     uint16_t etx;
00103   } obj;
00104 };
00105 typedef struct rpl_metric_container rpl_metric_container_t;
00106 /*---------------------------------------------------------------------------*/
00107 struct rpl_instance;
00108 struct rpl_dag;
00109 /*---------------------------------------------------------------------------*/
00110 struct rpl_parent {
00111   struct rpl_parent *next;
00112   struct rpl_dag *dag;
00113   rpl_metric_container_t mc;
00114   uip_ipaddr_t addr;
00115   rpl_rank_t rank;
00116   uint8_t link_metric;
00117   uint8_t dtsn;
00118   uint8_t updated;
00119 };
00120 typedef struct rpl_parent rpl_parent_t;
00121 /*---------------------------------------------------------------------------*/
00122 /* RPL DIO prefix suboption */
00123 struct rpl_prefix {
00124   uip_ipaddr_t prefix;
00125   uint32_t lifetime;
00126   uint8_t length;
00127   uint8_t flags;
00128 };
00129 typedef struct rpl_prefix rpl_prefix_t;
00130 /*---------------------------------------------------------------------------*/
00131 /* Directed Acyclic Graph */
00132 struct rpl_dag {
00133   uip_ipaddr_t dag_id;
00134   rpl_rank_t min_rank; /* should be reset per DAG iteration! */
00135   uint8_t version;
00136   uint8_t grounded;
00137   uint8_t preference;
00138   uint8_t used;
00139   /* live data for the DAG */
00140   uint8_t joined;
00141   rpl_parent_t *preferred_parent;
00142   rpl_rank_t rank;
00143   struct rpl_instance *instance;
00144   LIST_STRUCT(parents);
00145   rpl_prefix_t prefix_info;
00146 };
00147 typedef struct rpl_dag rpl_dag_t;
00148 typedef struct rpl_instance rpl_instance_t;
00149 /*---------------------------------------------------------------------------*/
00150 /*
00151  * API for RPL objective functions (OF)
00152  *
00153  * reset(dag)
00154  *
00155  *  Resets the objective function state for a specific DAG. This function is
00156  *  called when doing a global repair on the DAG.
00157  *
00158  * parent_state_callback(parent, known, etx)
00159  *
00160  *  Receives link-layer neighbor information. The parameter "known" is set
00161  *  either to 0 or 1. The "etx" parameter specifies the current
00162  *  ETX(estimated transmissions) for the neighbor.
00163  *
00164  * best_parent(parent1, parent2)
00165  *
00166  *  Compares two parents and returns the best one, according to the OF.
00167  *
00168  * best_dag(dag1, dag2)
00169  *
00170  *  Compares two DAGs and returns the best one, according to the OF.
00171  *
00172  * calculate_rank(parent, base_rank)
00173  *
00174  *  Calculates a rank value using the parent rank and a base rank.
00175  *  If "parent" is NULL, the objective function selects a default increment
00176  *  that is adds to the "base_rank". Otherwise, the OF uses information known
00177  *  about "parent" to select an increment to the "base_rank".
00178  *
00179  * update_metric_container(dag)
00180  *
00181  *  Updates the metric container for outgoing DIOs in a certain DAG.
00182  *  If the objective function of the DAG does not use metric containers, 
00183  *  the function should set the object type to RPL_DAG_MC_NONE.
00184  */
00185 struct rpl_of {
00186   void (*reset)(struct rpl_dag *);
00187   void (*parent_state_callback)(rpl_parent_t *, int, int);
00188   rpl_parent_t *(*best_parent)(rpl_parent_t *, rpl_parent_t *);
00189   rpl_dag_t *(*best_dag)(rpl_dag_t *, rpl_dag_t *);
00190   rpl_rank_t (*calculate_rank)(rpl_parent_t *, rpl_rank_t);
00191   void (*update_metric_container)( rpl_instance_t *);
00192   rpl_ocp_t ocp;
00193 };
00194 typedef struct rpl_of rpl_of_t;
00195 /*---------------------------------------------------------------------------*/
00196 /* Instance */
00197 struct rpl_instance {
00198   /* DAG configuration */
00199   rpl_metric_container_t mc;
00200   rpl_of_t *of;
00201   rpl_dag_t *current_dag;
00202   rpl_dag_t dag_table[RPL_MAX_DAG_PER_INSTANCE];
00203   /* The current default router - used for routing "upwards" */
00204   uip_ds6_defrt_t *def_route;
00205   uint8_t instance_id;
00206   uint8_t used;
00207   uint8_t dtsn_out;
00208   uint8_t mop;
00209   uint8_t dio_intdoubl;
00210   uint8_t dio_intmin;
00211   uint8_t dio_redundancy;
00212   uint8_t default_lifetime;
00213   uint8_t dio_intcurrent;
00214   uint8_t dio_send; /* for keeping track of which mode the timer is in */
00215   uint8_t dio_counter;
00216   rpl_rank_t max_rankinc;
00217   rpl_rank_t min_hoprankinc;
00218   uint16_t lifetime_unit; /* lifetime in seconds = l_u * d_l */
00219 #if RPL_CONF_STATS
00220   uint16_t dio_totint;
00221   uint16_t dio_totsend;
00222   uint16_t dio_totrecv;
00223 #endif /* RPL_CONF_STATS */
00224   uint32_t dio_next_delay; /* delay for completion of dio interval */
00225   struct ctimer dio_timer;
00226   struct ctimer dao_timer;
00227 };
00228 
00229 /*---------------------------------------------------------------------------*/
00230 /* Public RPL functions. */
00231 void rpl_init(void);
00232 void uip_rpl_input(void);
00233 rpl_dag_t *rpl_set_root(uint8_t instance_id, uip_ipaddr_t * dag_id);
00234 int rpl_set_prefix(rpl_dag_t *dag, uip_ipaddr_t *prefix, unsigned len);
00235 int rpl_repair_root(uint8_t instance_id);
00236 int rpl_set_default_route(rpl_instance_t *instance, uip_ipaddr_t *from);
00237 rpl_dag_t *rpl_get_any_dag(void);
00238 rpl_instance_t *rpl_get_instance(uint8_t instance_id);
00239 void rpl_update_header_empty(void);
00240 int rpl_update_header_final(uip_ipaddr_t *addr);
00241 int rpl_verify_header(int);
00242 void rpl_remove_header(void);
00243 uint8_t rpl_invert_header(void);
00244 /*---------------------------------------------------------------------------*/
00245 #endif /* RPL_H */