Contiki-NG
Files | Data Structures | Macros | Functions | Variables
Multicast Protocol for Low Power and Lossy Networks

IPv6 multicast according to the algorithm in RFC7731. More...

Files

file  mpl.c
 Implementation of the MPL protocol.
 
file  mpl.h
 Header file for the implementation of the MPL protocol.
 

Data Structures

struct  mpl_stats
 Multicast stats extension for the MPL engine. More...
 

Macros

#define SEED_ID_S1(dst, src)   { (*(uint16_t *)&(dst)->id) = (src); (dst)->s = 1; }
 Set the seed id to a 16 bit constant dst: seed_id_t to set to the constant src: 16 bit integer to set.
 
#define SEED_ID_S2(dst, src)   { (*(uint64_t *)&(dst)->id) = (src); (dst)->s = 2; }
 Set the seed id to a 64 bit constant dst: seed_id_t to set to the constant src: 64 bit integer to set.
 
#define SEED_ID_S3(dst, l, h)   { (*(uint64_t *)&(dst)->id) = (l); (*(uint64_t *)&(dst)->id[8]) = (h); (dst)->s = 3; }
 Set the seed id to a 128 bit constant dst: seed_id_t to set to the constant l: Lower 64 bits of the seed id to set h: Upper 64 bits of the seed id to set.
 
#define seed_id_cmp(a, b)   (memcmp((a)->id, (b)->id, sizeof(uint8_t) * 16) == 0)
 Compare two contiki seed ids represented as seed_id_t types a: First value to compare b: Second value to compare.
 
#define seed_id_cpy(a, b)   (memcpy((a), (b), sizeof(seed_id_t)))
 Copy one seed_id_t into another. More...
 
#define seed_id_clr(a)   (memset((a), 0, sizeof(seed_id_t)))
 Clear a seed id value to zero a: Value to clear.
 
#define MSG_SET_IS_USED(h)   ((h)->seed != NULL)
 Get the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define MSG_SET_CLEAR_USED(h)   ((h)->seed = NULL)
 Clear the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define SEQ_VAL_IS_EQ(i1, i2)   ((i1) == (i2))
 s1 is said to be equal s2 if SEQ_VAL_IS_EQ(s1, s2) == 1
 
#define SEQ_VAL_IS_LT(i1, i2)
 s1 is said to be less than s2 if SEQ_VAL_IS_LT(s1, s2) == 1
 
#define SEQ_VAL_IS_GT(i1, i2)
 s1 is said to be greater than s2 iif SEQ_VAL_IS_LT(s1, s2) == 1
 
#define SEQ_VAL_ADD(s, n)   (((s) + (n)) % 0x100)
 Add n to s: (s + n) modulo (2 ^ SERIAL_BITS) => ((s + n) % 0x8000)
 
#define SEED_SET_IS_USED(h)   (((h)->domain != NULL))
 Get the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define SEED_SET_CLEAR_USED(h)   ((h)->domain = NULL)
 Clear the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define DOMAIN_SET_IS_USED(h)   (uip_is_addr_mcast(&(h)->data_addr))
 Get the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define DOMAIN_SET_CLEAR_USED(h)   (memset(&(h)->data_addr, 0, sizeof(uip_ip6addr_t)))
 Clear the state of the used flag in the buffered message set entry h: pointer to the message set entry.
 
#define HBH_GET_S(h)   (((h)->flags & 0xC0) >> 6)
 Get the MPL Parametrization for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_SET_S(h, s)   ((h)->flags |= ((s & 0x03) << 6))
 Set the MPL Parametrization bit for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_CLR_S(h)   ((h)->flags &= ~0xC0)
 Clear the MPL Parametrization bit for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_GET_M(h)   (((h)->flags & 0x20) == 0x20)
 Get the MPL Parametrization for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_SET_M(h)   ((h)->flags |= 0x20)
 Set the MPL Parametrization bit for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_GET_V(h)   (((h)->flags & 0x10) == 0x10)
 Get the MPL Parametrization for a multicast HBHO header m: pointer to the HBHO header.
 
#define HBH_CLR_V(h)   ((h)->flags &= ~0x10)
 Set the MPL Parametrization bit for a multicast HBHO header m: pointer to the HBHO header.
 
#define SEED_INFO_GET_S(h)   ((h)->bm_len_S & 0x03)
 Get the S bits in the length/S field in the seed info header h: pointer to the seed info struct.
 
#define SEED_INFO_CLR_S(h)   ((h)->bm_len_S &= ~0x03)
 Clear the S bits within the length/S field in the seed info header h: pointer to the seed info struct.
 
#define SEED_INFO_SET_S(h, s)   ((h)->bm_len_S |= (s & 0x03))
 Set the S bits within the seed info struct. More...
 
#define SEED_INFO_GET_LEN(h)   ((h)->bm_len_S >> 2)
 Get the length bits from the seed info struct. More...
 
#define SEED_INFO_CLR_LEN(h)   ((h)->bm_len_S &= 0x03)
 Clear the length bits in the seed info struct. More...
 
#define SEED_INFO_SET_LEN(h, l)   ((h)->bm_len_S |= (l << 2))
 Set the length bits in the seed info struct. More...
 
#define mpl_control_trickle_timer_start(t)   { (t)->e = 0; trickle_timer_set(&(t)->tt, control_message_expiration, (t)); }
 Start the trickle timer for a control message t: Pointer to set that should be reset.
 
#define mpl_data_trickle_timer_start(t)   { (t)->e = 0; trickle_timer_set(&(t)->tt, data_message_expiration, (t)); }
 Start the trickle timer for a data message t: Pointer to set that should be reset.
 
#define mpl_trickle_timer_inconsistency(t)   { (t)->e = 0; trickle_timer_inconsistency(&(t)->tt); }
 Call inconsistency on the provided timer t: Pointer to set that should be reset.
 
#define mpl_trickle_timer_reset(t)   { (t)->e = 0; trickle_timer_reset_event(&(t)->tt); }
 Reset the trickle timer and expiration count for the set t: Pointer to set that should be reset.
 
#define BIT_VECTOR_SET_BIT(v, b)   (v[b / 8] |= (0x80 >> b % 8))
 Set a single bit within a bit vector that spans multiple bytes v: The bit vector b: The 0-indexed bit to set.
 
#define BIT_VECTOR_GET_BIT(v, b)   ((v[b / 8] & (0x80 >> b % 8)) == (0x80 >> b % 8))
 Get the value of a bit in a bit vector v: The bit vector b: The 0-indexed bit to get.
 
#define UIP_ADDR_MAKE_LINK_LOCAL(a)   (((uip_ip6addr_t *)a)->u8[1] = UIP_MCAST6_SCOPE_LINK_LOCAL)
 Modify an ipv6 address to give it link local scope a: uip_ip6addr_t address to modify.
 
#define MPL_IP_HOP_LIMIT   0xFF
 Hop limit for ICMP messages.
 
#define MPL_SEED_ID_TYPE   0
 Seed ID Length The MPL Protocol requires that each seed is identified by an ID that is unique to the MPL domain. More...
 
#define MPL_SEED_ID_L   0x00
 Seed ID Alias Points to MPL_CONF_SEED_ID_L. More...
 
#define MPL_SEED_ID_H   0x00
 Seed ID High Bits If the Seed ID Length setting is 3, this setting defines the upper 64 bits for the seed id. More...
 
#define MPL_SUB_TO_ALL_FORWARDERS   1
 Subscribe to All MPL Forwarders By default, an MPL forwarder will subscribe to the ALL_MPL_FORWARDERS address with realm-local scope: FF03::FC. More...
 
#define MPL_DOMAIN_SET_SIZE   1
 Domain Set Size MPL Forwarders maintain a Domain Set which maps MPL domains to trickle timers. More...
 
#define MPL_SEED_SET_SIZE   2
 Seed Set Size MPL Forwarders maintain a Seed Set to keep track of the MPL messages that a particular seed has sent recently. More...
 
#define MPL_BUFFERED_MESSAGE_SET_SIZE   6
 Buffered Message Set Size MPL Forwarders maintain a buffer of data messages that are periodically forwarded around the MPL domain. More...
 
#define MPL_PROACTIVE_FORWARDING   0
 MPL Forwarding Strategy Two forwarding strategies are defined for MPL. More...
 
#define MPL_SEED_SET_ENTRY_LIFETIME   30
 Seed Set Entry Lifetime MPL Seed set entries remain in the seed set for a set period of time after the last message that was received by that seed. More...
 
#define MPL_DATA_MESSAGE_TIMER_EXPIRATIONS   5
 Data Message Timer Expirations MPL data message trickle timers are stopped after they expire a set number of times. More...
 
#define MPL_CONTROL_MESSAGE_TIMER_EXPIRATIONS   10
 Control Message Timer Expirations An MPL Forwarder forwards MPL messages for a particular domain using a trickle timer which is mapped using the Domain Set. More...
 

Functions

static void icmp_in (void)
 
static struct mpl_msg * buffer_reclaim (void)
 
static void seed_id_net_to_host (seed_id_t *dst, void *src, uint8_t s)
 
static void seed_id_host_to_net (void *dst, seed_id_t *src)
 
static uint8_t accept (uint8_t in)
 

Variables

const struct uip_mcast6_driver mpl_driver
 The MPL engine driver.
 

Detailed Description

IPv6 multicast according to the algorithm in RFC7731.

The current version of the specification can be found in https://tools.ietf.org/html/rfc7731

Macro Definition Documentation

◆ MPL_BUFFERED_MESSAGE_SET_SIZE

#define MPL_BUFFERED_MESSAGE_SET_SIZE   6

Buffered Message Set Size MPL Forwarders maintain a buffer of data messages that are periodically forwarded around the MPL domain.

These are forwarded when trickle timers expire, and remain in the buffer for the number of timer expirations set in Data Message Timer Expirations.

Definition at line 214 of file mpl.h.

◆ MPL_CONTROL_MESSAGE_TIMER_EXPIRATIONS

#define MPL_CONTROL_MESSAGE_TIMER_EXPIRATIONS   10

Control Message Timer Expirations An MPL Forwarder forwards MPL messages for a particular domain using a trickle timer which is mapped using the Domain Set.

MPL domains remain in the Domain Set for the number of timer expirations below. New messages on that domain cause the expirations counter to reset.

Definition at line 267 of file mpl.h.

◆ MPL_DATA_MESSAGE_TIMER_EXPIRATIONS

#define MPL_DATA_MESSAGE_TIMER_EXPIRATIONS   5

Data Message Timer Expirations MPL data message trickle timers are stopped after they expire a set number of times.

The number of times they expire before being stopped is set below.

Definition at line 254 of file mpl.h.

◆ MPL_DOMAIN_SET_SIZE

#define MPL_DOMAIN_SET_SIZE   1

Domain Set Size MPL Forwarders maintain a Domain Set which maps MPL domains to trickle timers.

The size of this should reflect the number of MPL domains this forwarder is participating in.

Definition at line 189 of file mpl.h.

◆ MPL_PROACTIVE_FORWARDING

#define MPL_PROACTIVE_FORWARDING   0

MPL Forwarding Strategy Two forwarding strategies are defined for MPL.

With Proactive forwarding enabled, the forwarder will schedule transmissions of new messages before any control messages are received to indicate that neighbouring nodes have yet to receive the messages. With Reactive forwarding enabled, MPL forwarders will only schedule transmissions of new MPL messages once control messages have been received indicating that they are missing those messages. 1 - Indicates that proactive forwarding be enabled 0 - Indicates that proactive forwarding be disabled

Definition at line 231 of file mpl.h.

◆ MPL_SEED_ID_H

#define MPL_SEED_ID_H   0x00

Seed ID High Bits If the Seed ID Length setting is 3, this setting defines the upper 64 bits for the seed id.

Else it's ignored.

Definition at line 165 of file mpl.h.

◆ MPL_SEED_ID_L

#define MPL_SEED_ID_L   0x00

Seed ID Alias Points to MPL_CONF_SEED_ID_L.

Seed ID Low Bits If the Seed ID Length setting is 1 or 2, this setting defines the seed id for this seed. If the seed id setting is 3, then this defines the lower 64 bits of the seed id.

Definition at line 154 of file mpl.h.

◆ MPL_SEED_ID_TYPE

#define MPL_SEED_ID_TYPE   0

Seed ID Length The MPL Protocol requires that each seed is identified by an ID that is unique to the MPL domain.

The Seed ID can be either a 16 bit, 64 bit, or 128 bit unsigned integer. It it's an 128 bit unsigned integer then the IPv6 address may be used. The format of the Seed ID is set in the three-bit 'S' field in MPL header options, and the value below mirrors this. 0 - The seed id will be the IPv6 address of this device. The values of MPL_CONF_SEED_ID_L and MPL_CONF_SEED_ID_H are ignored. 1 - The seed id will be a 16 bit unsigned integer defined in MPL_CONF_SEED_ID_L 2 - The seed id will be a 64 bit unsigned integer defined in in MPL_CONF_SEED_ID_L 3 - The seed id will be an 128 bit unsigned integer defined in both MPL_CONF_SEED_ID_L and MPL_CONF_SEED_ID_H

Definition at line 134 of file mpl.h.

◆ MPL_SEED_SET_ENTRY_LIFETIME

#define MPL_SEED_SET_ENTRY_LIFETIME   30

Seed Set Entry Lifetime MPL Seed set entries remain in the seed set for a set period of time after the last message that was received by that seed.

This is called the lifetime of the seed, and is defined in minutes.

Definition at line 243 of file mpl.h.

◆ MPL_SEED_SET_SIZE

#define MPL_SEED_SET_SIZE   2

Seed Set Size MPL Forwarders maintain a Seed Set to keep track of the MPL messages that a particular seed has sent recently.

Seeds remain on the Seed Set for the time specified in the Seed Set Entry Lifetime setting.

Definition at line 201 of file mpl.h.

◆ MPL_SUB_TO_ALL_FORWARDERS

#define MPL_SUB_TO_ALL_FORWARDERS   1

Subscribe to All MPL Forwarders By default, an MPL forwarder will subscribe to the ALL_MPL_FORWARDERS address with realm-local scope: FF03::FC.

This behaviour can be disabled using the macro below.

Definition at line 177 of file mpl.h.

◆ seed_id_cpy

#define seed_id_cpy (   a,
 
)    (memcpy((a), (b), sizeof(seed_id_t)))

Copy one seed_id_t into another.

a: Destination b: Source

Definition at line 141 of file mpl.c.

◆ SEED_INFO_CLR_LEN

#define SEED_INFO_CLR_LEN (   h)    ((h)->bm_len_S &= 0x03)

Clear the length bits in the seed info struct.

h: pointer to the seed info struct

Definition at line 377 of file mpl.c.

◆ SEED_INFO_GET_LEN

#define SEED_INFO_GET_LEN (   h)    ((h)->bm_len_S >> 2)

Get the length bits from the seed info struct.

h: pointer to seed info struct.

Definition at line 372 of file mpl.c.

◆ SEED_INFO_SET_LEN

#define SEED_INFO_SET_LEN (   h,
 
)    ((h)->bm_len_S |= (l << 2))

Set the length bits in the seed info struct.

These must be cleared beforehand. h: pointer to the seed info struct l: Length value (0-63) that the length bits should be set to

Definition at line 383 of file mpl.c.

◆ SEED_INFO_SET_S

#define SEED_INFO_SET_S (   h,
 
)    ((h)->bm_len_S |= (s & 0x03))

Set the S bits within the seed info struct.

These must be cleared beforehand. h: Pointer to the seed info struct s: value (0-3) that the S bits should be set to

Definition at line 367 of file mpl.c.

Function Documentation

◆ accept()

static uint8_t accept ( uint8_t  in)
static

Seed ID is embedded in the header where padding would otherwise be. Since we're only interested in the address the specific s1/s2/s3 type doesn't matter.

Check for inconsistency MPL Defines an inconsistent packet as "receiving an MPL Data Message that has the same MPL Domain Address, seed-id value, and the M flag set, but has a sequence value less than that of the MPL Data Message managed by the Trickle timer." We have already satisfied the domain address and seed-id conditions, now check the rest.

Definition at line 1391 of file mpl.c.

◆ buffer_reclaim()

static struct mpl_msg* buffer_reclaim ( void  )
static

To reclaim this, we need to increment the min seq number to the next largest sequence number in the set. This won't necessarily be min_seq + 1 because MPL does not require or ensure that sequence number are sequential, it just denotes the order messages are sent. We've already worked out what this new value is.

Definition at line 489 of file mpl.c.

◆ icmp_in()

static void icmp_in ( void  )
static

Work out what offset the local or remote message set need so that the sequence numbers match up

If we've made it this far, our sets overlap and we can work out specific messages that may be missing from each set.

If we enter this loop it means there is a gap in local sequence numbers. Check that same gap exists in the remote set.

We have reached the end of local set, the remainder of the remote set should be zero else local is missing a message.

Definition at line 1063 of file mpl.c.

◆ seed_id_host_to_net()

static void seed_id_host_to_net ( void *  dst,
seed_id_t *  src 
)
static

Convert a seed id from our internal representation to network order and representation based on length s.

Definition at line 692 of file mpl.c.

◆ seed_id_net_to_host()

static void seed_id_net_to_host ( seed_id_t *  dst,
void *  src,
uint8_t  s 
)
static

Convert a seed id in network order header format and length S to internal representation.

Definition at line 640 of file mpl.c.