Contiki-NG
mpl.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018, University of Bristol - http://www.bristol.ac.uk/
3  * All rights reserved
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  */
31 
32 /**
33  * \addtogroup uip-multicast
34  * @{
35  */
36 /**
37  * \defgroup mpl Multicast Protocol for Low Power and Lossy Networks
38  *
39  * IPv6 multicast according to the algorithm in RFC7731
40  *
41  * The current version of the specification can be found in
42  * https://tools.ietf.org/html/rfc7731
43  *
44  * @{
45  */
46 /**
47  * \file
48  * Header file for the implementation of the MPL protocol
49  * \author
50  * Ed Rose - <er15406@bris.ac.uk>
51  */
52 
53 #ifndef MPL_H
54 #define MPL_H
55 #include "contiki.h"
56 #include "net/ipv6/uip.h"
58 
59 /*---------------------------------------------------------------------------*/
60 /* Protocol Constants */
61 /*---------------------------------------------------------------------------*/
62 #define ALL_MPL_FORWARDERS(a, r) uip_ip6addr(a, 0xFF00 + r,0x00,0x00,0x00,0x00,0x00,0x00,0xFC)
63 #define HBHO_OPT_TYPE_MPL 0x6D
64 #define MPL_IP_HOP_LIMIT 0xFF /**< Hop limit for ICMP messages */
65 #define HBHO_BASE_LEN 8
66 #define HBHO_S0_LEN 0
67 #define HBHO_S1_LEN 0
68 #define HBHO_S2_LEN 8
69 #define HBHO_S3_LEN 16
70 #define MPL_OPT_LEN_S0 2
71 #define MPL_OPT_LEN_S1 4
72 #define MPL_OPT_LEN_S2 10
73 #define MPL_OPT_LEN_S3 18
74 #define MPL_DGRAM_OUT 0
75 #define MPL_DGRAM_IN 1
76 
77 /* Trickle timer configuration */
78 #ifndef MPL_CONF_DATA_MESSAGE_IMIN
79 #define MPL_DATA_MESSAGE_IMIN 32
80 #else
81 #define MPL_DATA_MESSAGE_IMIN MPL_CONF_DATA_MESSAGE_IMIN
82 #endif
83 
84 #ifndef MPL_CONF_DATA_MESSAGE_IMAX
85 #define MPL_DATA_MESSAGE_IMAX MPL_CONTROL_MESSAGE_IMIN
86 #else
87 #define MPL_DATA_MESSAGE_IMAX MPL_CONF_DATA_MESSAGE_IMAX
88 #endif
89 
90 #ifndef MPL_CONF_DATA_MESSAGE_K
91 #define MPL_DATA_MESSAGE_K 1
92 #else
93 #define MPL_CONF_DATA_MESSAGE_K MPL_DATA_MESSAGE_K
94 #endif
95 
96 #ifndef MPL_CONF_CONTROL_MESSAGE_IMIN
97 #define MPL_CONTROL_MESSAGE_IMIN 32
98 #else
99 #define MPL_CONTROL_MESSAGE_IMIN MPL_CONF_CONTROL_MESSAGE_IMIN
100 #endif
101 
102 #ifndef MPL_CONF_CONTROL_MESSAGE_IMAX
103 #define MPL_CONTROL_MESSAGE_IMAX 32
104 #else
105 #define MPL_CONTROL_MESSAGE_IMAX MPL_CONF_CONTROL_MESSAGE_IMAX
106 #endif
107 
108 #ifndef MPL_CONF_CONTROL_MESSAGE_K
109 #define MPL_CONTROL_MESSAGE_K 1
110 #else
111 #define MPL_CONTROL_MESSAGE_K MPL_CONF_CONTROL_MESSAGE_K
112 #endif
113 
114 /*---------------------------------------------------------------------------*/
115 /* Protocol Configuration */
116 /*---------------------------------------------------------------------------*/
117 /**
118  * Seed ID Length
119  * The MPL Protocol requires that each seed is identified by an ID that is
120  * unique to the MPL domain. The Seed ID can be either a 16 bit, 64 bit,
121  * or 128 bit unsigned integer. It it's an 128 bit unsigned integer then the
122  * IPv6 address may be used. The format of the Seed ID is set in the
123  * three-bit 'S' field in MPL header options, and the value below mirrors this.
124  * 0 - The seed id will be the IPv6 address of this device. The values of
125  * MPL_CONF_SEED_ID_L and MPL_CONF_SEED_ID_H are ignored.
126  * 1 - The seed id will be a 16 bit unsigned integer defined
127  * in MPL_CONF_SEED_ID_L
128  * 2 - The seed id will be a 64 bit unsigned integer defined in
129  * in MPL_CONF_SEED_ID_L
130  * 3 - The seed id will be an 128 bit unsigned integer defined in both
131  * MPL_CONF_SEED_ID_L and MPL_CONF_SEED_ID_H
132  */
133 #ifndef MPL_CONF_SEED_ID_TYPE
134 #define MPL_SEED_ID_TYPE 0
135 #else
136 #define MPL_SEED_ID_TYPE MPL_CONF_SEED_ID_TYPE
137 #endif
138 /*---------------------------------------------------------------------------*/
139 /**
140  * Seed ID Alias
141  * Points to MPL_CONF_SEED_ID_L
142  */
143 #ifdef MPL_CONF_SEED_ID
144 #define MPL_CONF_SEED_ID_L MPL_CONF_SEED_ID
145 #endif
146 /*---------------------------------------------------------------------------*/
147 /**
148 * Seed ID Low Bits
149  * If the Seed ID Length setting is 1 or 2, this setting defines the seed
150  * id for this seed. If the seed id setting is 3, then this defines the lower
151  * 64 bits of the seed id.
152  */
153 #ifndef MPL_CONF_SEED_ID_L
154 #define MPL_SEED_ID_L 0x00
155 #else
156 #define MPL_SEED_ID_L MPL_CONF_SEED_ID_L
157 #endif
158 /*---------------------------------------------------------------------------*/
159 /**
160 * Seed ID High Bits
161  * If the Seed ID Length setting is 3, this setting defines the upper 64 bits
162  * for the seed id. Else it's ignored.
163  */
164 #ifndef MPL_CONF_SEED_ID_H
165 #define MPL_SEED_ID_H 0x00
166 #else
167 #define MPL_SEED_ID_H MPL_CONF_SEED_ID_H
168 #endif
169 /*---------------------------------------------------------------------------*/
170 /**
171  * Subscribe to All MPL Forwarders
172  * By default, an MPL forwarder will subscribe to the ALL_MPL_FORWARDERS
173  * address with realm-local scope: FF03::FC. This behaviour can be disabled
174  * using the macro below.
175  */
176 #ifndef MPL_CONF_SUB_TO_ALL_FORWARDERS
177 #define MPL_SUB_TO_ALL_FORWARDERS 1
178 #else
179 #define MPL_SUB_TO_ALL_FORWARDERS MPL_CONF_SUB_TO_ALL_FORWARDERS
180 #endif
181 /*---------------------------------------------------------------------------*/
182 /**
183  * Domain Set Size
184  * MPL Forwarders maintain a Domain Set which maps MPL domains to trickle
185  * timers. The size of this should reflect the number of MPL domains this
186  * forwarder is participating in.
187  */
188 #ifndef MPL_CONF_DOMAIN_SET_SIZE
189 #define MPL_DOMAIN_SET_SIZE 1
190 #else
191 #define MPL_DOMAIN_SET_SIZE MPL_CONF_DOMAIN_SET_SIZE
192 #endif
193 /*---------------------------------------------------------------------------*/
194 /**
195  * Seed Set Size
196  * MPL Forwarders maintain a Seed Set to keep track of the MPL messages that a
197  * particular seed has sent recently. Seeds remain on the Seed Set for the
198  * time specified in the Seed Set Entry Lifetime setting.
199  */
200 #ifndef MPL_CONF_SEED_SET_SIZE
201 #define MPL_SEED_SET_SIZE 2
202 #else
203 #define MPL_SEED_SET_SIZE MPL_CONF_SEED_SET_SIZE
204 #endif
205 /*---------------------------------------------------------------------------*/
206 /**
207  * Buffered Message Set Size
208  * MPL Forwarders maintain a buffer of data messages that are periodically
209  * forwarded around the MPL domain. These are forwarded when trickle timers
210  * expire, and remain in the buffer for the number of timer expirations
211  * set in Data Message Timer Expirations.
212  */
213 #ifndef MPL_CONF_BUFFERED_MESSAGE_SET_SIZE
214 #define MPL_BUFFERED_MESSAGE_SET_SIZE 6
215 #else
216 #define MPL_BUFFERED_MESSAGE_SET_SIZE MPL_CONF_BUFFERED_MESSAGE_SET_SIZE
217 #endif
218 /*---------------------------------------------------------------------------*/
219 /**
220  * MPL Forwarding Strategy
221  * Two forwarding strategies are defined for MPL. With Proactive forwarding
222  * enabled, the forwarder will schedule transmissions of new messages
223  * before any control messages are received to indicate that neighbouring nodes
224  * have yet to receive the messages. With Reactive forwarding enabled, MPL
225  * forwarders will only schedule transmissions of new MPL messages once control
226  * messages have been received indicating that they are missing those messages.
227  * 1 - Indicates that proactive forwarding be enabled
228  * 0 - Indicates that proactive forwarding be disabled
229  */
230 #ifndef MPL_CONF_PROACTIVE_FORWARDING
231 #define MPL_PROACTIVE_FORWARDING 0
232 #else
233 #define MPL_PROACTIVE_FORWARDING MPL_CONF_PROACTIVE_FORWARDING
234 #endif
235 /*---------------------------------------------------------------------------*/
236 /**
237  * Seed Set Entry Lifetime
238  * MPL Seed set entries remain in the seed set for a set period of time after
239  * the last message that was received by that seed. This is called the
240  * lifetime of the seed, and is defined in minutes.
241  */
242 #ifndef MPL_CONF_SEED_SET_ENTRY_LIFETIME
243 #define MPL_SEED_SET_ENTRY_LIFETIME 30
244 #else
245 #define MPL_SEED_SET_ENTRY_LIFETIME MPL_CONF_SEED_SET_ENTRY_LIFETIME
246 #endif
247 /*---------------------------------------------------------------------------*/
248 /**
249  * Data Message Timer Expirations
250  * MPL data message trickle timers are stopped after they expire a set number
251  * of times. The number of times they expire before being stopped is set below.
252  */
253 #ifndef MPL_CONF_DATA_MESSAGE_TIMER_EXPIRATIONS
254 #define MPL_DATA_MESSAGE_TIMER_EXPIRATIONS 5
255 #else
256 #define MPL_DATA_MESSAGE_TIMER_EXPIRATIONS MPL_CONF_DATA_MESSAGE_TIMER_EXPIRATIONS
257 #endif
258 /*---------------------------------------------------------------------------*/
259 /**
260  * Control Message Timer Expirations
261  * An MPL Forwarder forwards MPL messages for a particular domain using a
262  * trickle timer which is mapped using the Domain Set. MPL domains remain in
263  * the Domain Set for the number of timer expirations below. New messages on
264  * that domain cause the expirations counter to reset.
265  */
266 #ifndef MPL_CONF_CONTROL_MESSAGE_TIMER_EXPIRATIONS
267 #define MPL_CONTROL_MESSAGE_TIMER_EXPIRATIONS 10
268 #else
269 #define MPL_CONTROL_MESSAGE_TIMER_EXPIRATIONS MPL_CONF_CONTROL_MESSAGE_TIMER_EXPIRATIONS
270 #endif
271 /*---------------------------------------------------------------------------*/
272 /* Misc System Config */
273 /*---------------------------------------------------------------------------*/
274 
275 /* Configure the correct number of multicast addresses for MPL */
276 #define UIP_CONF_DS6_MADDR_NBU MPL_DOMAIN_SET_SIZE * 2
277 
278 /*---------------------------------------------------------------------------*/
279 /* Stats datatype */
280 /*---------------------------------------------------------------------------*/
281 /**
282  * \brief Multicast stats extension for the MPL engine
283  */
284 struct mpl_stats {
285  /** Number of received ICMP datagrams */
286  UIP_MCAST6_STATS_DATATYPE icmp_in;
287 
288  /** Number of ICMP datagrams sent */
289  UIP_MCAST6_STATS_DATATYPE icmp_out;
290 
291  /** Number of malformed ICMP datagrams seen by us */
292  UIP_MCAST6_STATS_DATATYPE icmp_bad;
293 };
294 #endif
295 /*---------------------------------------------------------------------------*/
296 /** @} */
297 /** @} */
UIP_MCAST6_STATS_DATATYPE icmp_bad
Number of malformed ICMP datagrams seen by us.
Definition: mpl.h:292
UIP_MCAST6_STATS_DATATYPE icmp_out
Number of ICMP datagrams sent.
Definition: mpl.h:289
Multicast stats extension for the MPL engine.
Definition: mpl.h:284
UIP_MCAST6_STATS_DATATYPE icmp_in
Number of received ICMP datagrams.
Definition: mpl.h:286
Header file for the uIP TCP/IP stack.
Header file for IPv6 multicast forwarding stats maintenance