Multicast README
This commit is contained in:
George Oikonomou
George Oikonomou
parent
226701b098
commit
230881df44
111
core/net/ipv6/multicast/README.md
Normal file
111
core/net/ipv6/multicast/README.md
Normal file
|
|
@ -0,0 +1,111 @@
|
||||||
|
README file for Contiki's IPv6 multicast core
|
||||||
|
|
||||||
|
Author: George Oikonomou
|
||||||
|
|
||||||
|
What does it do
|
||||||
|
===============
|
||||||
|
These files, alongside some core modifications, add support for IPv6 multicast
|
||||||
|
to contiki's uIPv6 engine.
|
||||||
|
|
||||||
|
Currently, two modes are supported:
|
||||||
|
|
||||||
|
* 'Stateless Multicast RPL Forwarding' (SMRF)
|
||||||
|
RPL in MOP 3 handles group management as per the RPL docs,
|
||||||
|
SMRF is a lightweight engine which handles datagram forwarding.
|
||||||
|
SMRF is documented here:
|
||||||
|
http://dx.doi.org/10.1007/s11277-013-1250-5
|
||||||
|
and here:
|
||||||
|
http://dx.doi.org/10.1109/PerComW.2012.6197494
|
||||||
|
* 'Multicast Forwarding with Trickle' according to the algorithm described
|
||||||
|
in the internet draft:
|
||||||
|
http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
|
||||||
|
The version of this draft that's currently implementated is documented
|
||||||
|
in `roll-tm.h`
|
||||||
|
|
||||||
|
More engines can (and hopefully will) be added in the future. The first
|
||||||
|
addition is most likely going to be an updated implementation of MPL
|
||||||
|
|
||||||
|
The Big Gotcha
|
||||||
|
==============
|
||||||
|
Currently we only support traffic originating and destined inside a single 6LoWPAN
|
||||||
|
To be able to send multicast traffic from the internet to 6LoWPAN nodes or the other
|
||||||
|
way round, we need border routers or other gateway devices to be able to achieve
|
||||||
|
the following:
|
||||||
|
|
||||||
|
* Add/Remove Trickle Multicast, RPL or other HBHO headers as necessary for datagrams
|
||||||
|
entering / exiting the 6LoWPAN
|
||||||
|
* Advertise multicast group membership to the internet (e.g. with MLD)
|
||||||
|
|
||||||
|
These are currently not implemented and are in the ToDo list. Contributions welcome.
|
||||||
|
|
||||||
|
Where to Start
|
||||||
|
==============
|
||||||
|
The best place in `examples/ipv6/multicast`
|
||||||
|
|
||||||
|
There is a cooja example demonstrating basic functionality
|
||||||
|
|
||||||
|
How to Use
|
||||||
|
==========
|
||||||
|
Look in `core/net/ipv6/multicast/uip-mcast6-engines.h` for a list of supported
|
||||||
|
multicast engines.
|
||||||
|
|
||||||
|
To turn on multicast support, add this line in your `project-` or `contiki-conf.h`
|
||||||
|
|
||||||
|
#define UIP_MCAST6_CONF_ENGINE xyz
|
||||||
|
|
||||||
|
where xyz is a value from `uip-mcast6-engines.h`
|
||||||
|
|
||||||
|
To disable:
|
||||||
|
|
||||||
|
#define UIP_MCAST6_CONF_ENGINE 0
|
||||||
|
|
||||||
|
You also need to make sure the multicast code gets built. Your example's
|
||||||
|
(or platform's) Makefile should include this:
|
||||||
|
|
||||||
|
MODULES += core/net/ipv6/multicast
|
||||||
|
|
||||||
|
How to extend
|
||||||
|
=============
|
||||||
|
Let's assume you want to write an engine called foo.
|
||||||
|
The multicast API defines a multicast engine driver in a fashion similar to
|
||||||
|
the various NETSTACK layer drivers. This API defines functions for basic
|
||||||
|
multicast operations (init, in, out).
|
||||||
|
In order to extend multicast with a new engine, perform the following steps:
|
||||||
|
|
||||||
|
- Open `uip-mcast6-engines.h` and assign a unique integer code to your engine
|
||||||
|
|
||||||
|
#define UIP_MCAST6_ENGINE_FOO xyz
|
||||||
|
|
||||||
|
- Include your engine's `foo.h`
|
||||||
|
|
||||||
|
- In `foo.c`, implement:
|
||||||
|
* `init()`
|
||||||
|
* `in()`
|
||||||
|
* `out()`
|
||||||
|
* Define your driver like so:
|
||||||
|
|
||||||
|
`const struct uip_mcast6_driver foo_driver = { ... }`
|
||||||
|
|
||||||
|
- If you want to maintain stats:
|
||||||
|
* Declare a `struct foo_stats` in `foo.h`
|
||||||
|
* Define a variable of type `struct foo_stats` called `foo_stats` in `foo.c`
|
||||||
|
The names `foo_stats` for the stats variable and stats datatype are only
|
||||||
|
examples. You can assign different names
|
||||||
|
|
||||||
|
- Open `uip-mcast6.h` and add a section in the `#if` spree. This aims to
|
||||||
|
configure the uIPv6 core. More specifically, you need to:
|
||||||
|
* Specify if you want to put RPL in MOP3 by defining
|
||||||
|
`RPL_CONF_MULTICAST`: 1: MOP 3, 0: non-multicast MOP
|
||||||
|
* Define your engine details
|
||||||
|
|
||||||
|
#define UIP_MCAST6 foo_driver
|
||||||
|
#define UIP_MCAST6_STATS foo_stats
|
||||||
|
typedef struct foo_stats uip_mcast6_stats_t;
|
||||||
|
|
||||||
|
* Optionally, add a configuration check block to stop builds when the
|
||||||
|
configuration is not sane.
|
||||||
|
|
||||||
|
If you need your engine to perform operations not supported by the generic
|
||||||
|
UIP_MCAST6 API, you will have to hook those in the uip core manually. As an
|
||||||
|
example, see how the core is modified so that it can deliver ICMPv6 datagrams
|
||||||
|
to the ROLL TM engine.
|
||||||
Loading…
Reference in a new issue