Tidy-up multicast documentation

* Create a doxygen group and add files to it, so that documents appear as modules rather than simply under files
* Document plenty of functions, macros, constants, data types which were previously undocumented
* Re-structure some doxygen comments to improve structure and readability
This commit is contained in:
George Oikonomou 2015-02-15 19:16:16 +01:00
parent a4e7cc29e8
commit 5efb3f0769
10 changed files with 203 additions and 72 deletions

View file

@ -29,18 +29,13 @@
* This file is part of the Contiki operating system. * This file is part of the Contiki operating system.
*/ */
/**
* \addtogroup roll-tm
* @{
*/
/** /**
* \file * \file
* This file implements IPv6 MCAST forwarding according to the * Implementation of the ROLL TM multicast engine
* algorithm described in the "MCAST Forwarding Using Trickle"
* internet draft.
*
* The current version of the draft can always be found in
* http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
*
* This implementation is based on the draft version stored in
* ROLL_TM_VER
*
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
*/ */
@ -1440,6 +1435,9 @@ init()
return; return;
} }
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/**
* \brief The ROLL TM engine driver
*/
const struct uip_mcast6_driver roll_tm_driver = { const struct uip_mcast6_driver roll_tm_driver = {
"ROLL TM", "ROLL TM",
init, init,
@ -1447,3 +1445,4 @@ const struct uip_mcast6_driver roll_tm_driver = {
in, in,
}; };
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** @} */

View file

@ -30,8 +30,13 @@
*/ */
/** /**
* \file * \addtogroup uip6-multicast
* Header file for IPv6 multicast according to the algorithm in the * @{
*/
/**
* \defgroup roll-tm ROLL Trickle Multicast
*
* IPv6 multicast according to the algorithm in the
* "MCAST Forwarding Using Trickle" internet draft. * "MCAST Forwarding Using Trickle" internet draft.
* *
* The current version of the draft can always be found in * The current version of the draft can always be found in
@ -45,7 +50,11 @@
* Due to very significant changes between draft versions 1 and 2, * Due to very significant changes between draft versions 1 and 2,
* MPL will be implemented as a separate engine and this file here * MPL will be implemented as a separate engine and this file here
* will provide legacy support for Draft v1. * will provide legacy support for Draft v1.
* * @{
*/
/**
* \file
* Header file for the implementation of the ROLL-TM multicast engine
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
*/ */
@ -60,9 +69,9 @@
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* Protocol Constants */ /* Protocol Constants */
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
#define ROLL_TM_VER 1 /* Supported Draft Version */ #define ROLL_TM_VER 1 /**< Supported Draft Version */
#define ROLL_TM_ICMP_CODE 0 /* ICMPv6 code field */ #define ROLL_TM_ICMP_CODE 0 /**< ROLL TM ICMPv6 code field */
#define ROLL_TM_IP_HOP_LIMIT 0xFF /* Hop limit for ICMP messages */ #define ROLL_TM_IP_HOP_LIMIT 0xFF /**< Hop limit for ICMP messages */
#define ROLL_TM_INFINITE_REDUNDANCY 0xFF #define ROLL_TM_INFINITE_REDUNDANCY 0xFF
#define ROLL_TM_DGRAM_OUT 0 #define ROLL_TM_DGRAM_OUT 0
#define ROLL_TM_DGRAM_IN 1 #define ROLL_TM_DGRAM_IN 1
@ -153,7 +162,7 @@
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* Configuration */ /* Configuration */
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* /**
* Number of Sliding Windows * Number of Sliding Windows
* In essence: How many unique sources of simultaneous multicast traffic do we * In essence: How many unique sources of simultaneous multicast traffic do we
* want to support for our lowpan * want to support for our lowpan
@ -166,7 +175,7 @@
#define ROLL_TM_WINS 2 #define ROLL_TM_WINS 2
#endif #endif
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* /**
* Maximum Number of Buffered Multicast Messages * Maximum Number of Buffered Multicast Messages
* This buffer is shared across all Seed IDs, therefore a new very active Seed * This buffer is shared across all Seed IDs, therefore a new very active Seed
* may eventually occupy all slots. It would make little sense (if any) to * may eventually occupy all slots. It would make little sense (if any) to
@ -178,7 +187,7 @@
#define ROLL_TM_BUFF_NUM 6 #define ROLL_TM_BUFF_NUM 6
#endif #endif
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* /**
* Use Short Seed IDs [short: 2, long: 16 (default)] * Use Short Seed IDs [short: 2, long: 16 (default)]
* It can be argued that we should (and it would be easy to) support both at * It can be argued that we should (and it would be easy to) support both at
* the same time but the draft doesn't list this as a MUST so we opt for * the same time but the draft doesn't list this as a MUST so we opt for
@ -190,7 +199,7 @@
#define ROLL_TM_SHORT_SEEDS 0 #define ROLL_TM_SHORT_SEEDS 0
#endif #endif
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* /**
* Destination address for our ICMPv6 advertisements. The draft gives us a * Destination address for our ICMPv6 advertisements. The draft gives us a
* choice between LL all-nodes or LL all-routers * choice between LL all-nodes or LL all-routers
* *
@ -202,7 +211,7 @@
#define ROLL_TM_DEST_ALL_NODES 0 #define ROLL_TM_DEST_ALL_NODES 0
#endif #endif
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* /**
* M param for our outgoing messages * M param for our outgoing messages
* By default, we set the M bit (conservative). Define this as 0 to clear the * By default, we set the M bit (conservative). Define this as 0 to clear the
* M bit in our outgoing messages (aggressive) * M bit in our outgoing messages (aggressive)
@ -215,10 +224,21 @@
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* Stats datatype */ /* Stats datatype */
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/**
* \brief Multicast stats extension for the ROLL TM engine
*/
struct roll_tm_stats { struct roll_tm_stats {
/** Number of received ICMP datagrams */
UIP_MCAST6_STATS_DATATYPE icmp_in; UIP_MCAST6_STATS_DATATYPE icmp_in;
/** Number of ICMP datagrams sent */
UIP_MCAST6_STATS_DATATYPE icmp_out; UIP_MCAST6_STATS_DATATYPE icmp_out;
/** Number of malformed ICMP datagrams seen by us */
UIP_MCAST6_STATS_DATATYPE icmp_bad; UIP_MCAST6_STATS_DATATYPE icmp_bad;
}; };
/*---------------------------------------------------------------------------*/
#endif /* ROLL_TM_H_ */ #endif /* ROLL_TM_H_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */

View file

@ -29,12 +29,14 @@
* This file is part of the Contiki operating system. * This file is part of the Contiki operating system.
*/ */
/**
* \addtogroup smrf-multicast
* @{
*/
/** /**
* \file * \file
* This file implements 'Stateless Multicast RPL Forwarding' (SMRF) * This file implements 'Stateless Multicast RPL Forwarding' (SMRF)
* *
* It will only work in RPL networks in MOP 3 "Storing with Multicast"
*
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
*/ */
@ -199,6 +201,9 @@ out()
return; return;
} }
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/**
* \brief The SMRF engine driver
*/
const struct uip_mcast6_driver smrf_driver = { const struct uip_mcast6_driver smrf_driver = {
"SMRF", "SMRF",
init, init,
@ -206,3 +211,4 @@ const struct uip_mcast6_driver smrf_driver = {
in, in,
}; };
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** @} */

View file

@ -29,9 +29,19 @@
* This file is part of the Contiki operating system. * This file is part of the Contiki operating system.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/**
* \defgroup smrf-multicast 'Stateless Multicast RPL Forwarding' (SMRF)
*
* SMRF will only work in RPL networks in MOP 3 "Storing with Multicast"
* @{
*/
/** /**
* \file * \file
* Header file for 'Stateless Multicast RPL Forwarding' (SMRF) * Header file for the SMRF forwarding engine
* *
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
@ -71,5 +81,8 @@ struct smrf_stats {
uint16_t mcast_bad; uint16_t mcast_bad;
uint16_t mcast_dropped; uint16_t mcast_dropped;
}; };
/*---------------------------------------------------------------------------*/
#endif /* SMRF_H_ */ #endif /* SMRF_H_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */

View file

@ -29,6 +29,10 @@
* This file is part of the Contiki operating system. * This file is part of the Contiki operating system.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/** /**
* \file * \file
* Header file with definition of multicast engine constants * Header file with definition of multicast engine constants
@ -43,8 +47,9 @@
#ifndef UIP_MCAST6_ENGINES_H_ #ifndef UIP_MCAST6_ENGINES_H_
#define UIP_MCAST6_ENGINES_H_ #define UIP_MCAST6_ENGINES_H_
#define UIP_MCAST6_ENGINE_NONE 0 /* Selecting this disables mcast */ #define UIP_MCAST6_ENGINE_NONE 0 /**< Selecting this disables mcast */
#define UIP_MCAST6_ENGINE_SMRF 1 #define UIP_MCAST6_ENGINE_SMRF 1 /**< The SMRF engine */
#define UIP_MCAST6_ENGINE_ROLL_TM 2 #define UIP_MCAST6_ENGINE_ROLL_TM 2 /**< The ROLL TM engine */
#endif /* UIP_MCAST6_ENGINES_H_ */ #endif /* UIP_MCAST6_ENGINES_H_ */
/** @} */

View file

@ -28,6 +28,10 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE. * OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/** /**
* \file * \file
* Multicast routing table manipulation * Multicast routing table manipulation
@ -128,3 +132,4 @@ uip_mcast6_route_init()
list_init(mcast_route_list); list_init(mcast_route_list);
} }
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** @} */

View file

@ -28,9 +28,13 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE. * OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/** /**
* \file * \file
* Multicast routing table manipulation * Header file for multicast routing table manipulation
* *
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
@ -45,18 +49,48 @@
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** \brief An entry in the multicast routing table */ /** \brief An entry in the multicast routing table */
typedef struct uip_mcast6_route { typedef struct uip_mcast6_route {
struct uip_mcast6_route *next; struct uip_mcast6_route *next; /**< Routes are arranged in a linked list */
uip_ipaddr_t group; uip_ipaddr_t group; /**< The multicast group */
uint32_t lifetime; /* seconds */ uint32_t lifetime; /**< Entry lifetime seconds */
void *dag; /* Pointer to an rpl_dag_t struct */ void *dag; /**< Pointer to an rpl_dag_t struct */
} uip_mcast6_route_t; } uip_mcast6_route_t;
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** \name Multicast Routing Table Manipulation */ /** \name Multicast Routing Table Manipulation */
/** @{ */ /** @{ */
/**
* \brief Lookup a multicast route
* \param group A pointer to the multicast group to be searched for
* \return A pointer to the new routing entry, or NULL if the route could not
* be found
*/
uip_mcast6_route_t *uip_mcast6_route_lookup(uip_ipaddr_t *group); uip_mcast6_route_t *uip_mcast6_route_lookup(uip_ipaddr_t *group);
/**
* \brief Add a multicast route
* \param group A pointer to the multicast group to be added
* \return A pointer to the new route, or NULL if the route could not be added
*/
uip_mcast6_route_t *uip_mcast6_route_add(uip_ipaddr_t *group); uip_mcast6_route_t *uip_mcast6_route_add(uip_ipaddr_t *group);
void uip_mcast6_route_rm(uip_mcast6_route_t *defrt);
/**
* \brief Remove a multicast route
* \param route A pointer to the route to be removed
*/
void uip_mcast6_route_rm(uip_mcast6_route_t *route);
/**
* \brief Retrieve the count of multicast routes
* \return The number of multicast routes
*/
int uip_mcast6_route_count(void); int uip_mcast6_route_count(void);
/**
* \brief Retrieve a pointer to the start of the multicast routes list
* \return A pointer to the start of the multicast routes
*
* If the multicast routes list is empty, this function will return NULL
*/
uip_mcast6_route_t *uip_mcast6_route_list_head(void); uip_mcast6_route_t *uip_mcast6_route_list_head(void);
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** /**
@ -73,3 +107,4 @@ void uip_mcast6_route_init(void);
/** @} */ /** @} */
#endif /* UIP_MCAST6_ROUTE_H_ */ #endif /* UIP_MCAST6_ROUTE_H_ */
/** @} */

View file

@ -27,6 +27,10 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE. * OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/** /**
* \file * \file
* IPv6 multicast forwarding stats maintenance * IPv6 multicast forwarding stats maintenance
@ -47,3 +51,4 @@ uip_mcast6_stats_init(void *stats)
uip_mcast6_stats.engine_stats = stats; uip_mcast6_stats.engine_stats = stats;
} }
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/** @} */

View file

@ -27,6 +27,10 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE. * OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* \addtogroup uip6-multicast
* @{
*/
/** /**
* \file * \file
* Header file for IPv6 multicast forwarding stats maintenance * Header file for IPv6 multicast forwarding stats maintenance
@ -56,15 +60,35 @@
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* Stats datatype */ /* Stats datatype */
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/**
* \brief A data structure used to maintain multicast stats
*
* Each engine can extend this structure via the engine_stats field
*/
typedef struct uip_mcast6_stats { typedef struct uip_mcast6_stats {
/** Count of unique datagrams received */
UIP_MCAST6_STATS_DATATYPE mcast_in_unique; UIP_MCAST6_STATS_DATATYPE mcast_in_unique;
UIP_MCAST6_STATS_DATATYPE mcast_in_all; /* At layer 3 */
UIP_MCAST6_STATS_DATATYPE mcast_in_ours; /* Unique and we are a group member */ /** Count of all datagrams received */
UIP_MCAST6_STATS_DATATYPE mcast_fwd; /* Forwarded by us but we are not the seed */ UIP_MCAST6_STATS_DATATYPE mcast_in_all;
UIP_MCAST6_STATS_DATATYPE mcast_out; /* We are the seed */
/** Count of datagrams received for a group that we have joined */
UIP_MCAST6_STATS_DATATYPE mcast_in_ours;
/** Count of datagrams forwarded by us but we are not the seed */
UIP_MCAST6_STATS_DATATYPE mcast_fwd;
/** Count of multicast datagrams originated by us */
UIP_MCAST6_STATS_DATATYPE mcast_out;
/** Count of malformed multicast datagrams seen by us */
UIP_MCAST6_STATS_DATATYPE mcast_bad; UIP_MCAST6_STATS_DATATYPE mcast_bad;
/** Count of multicast datagrams correclty formed but dropped by us */
UIP_MCAST6_STATS_DATATYPE mcast_dropped; UIP_MCAST6_STATS_DATATYPE mcast_dropped;
void *engine_stats; /* Opaque pointer to an engine's additional stats */
/** Opaque pointer to an engine's additional stats */
void *engine_stats;
} uip_mcast6_stats_t; } uip_mcast6_stats_t;
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
/* Access macros */ /* Access macros */
@ -89,3 +113,5 @@ extern uip_mcast6_stats_t uip_mcast6_stats;
void uip_mcast6_stats_init(void *stats); void uip_mcast6_stats_init(void *stats);
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
#endif /* UIP_MCAST6_STATS_H_ */ #endif /* UIP_MCAST6_STATS_H_ */
/*---------------------------------------------------------------------------*/
/** @} */

View file

@ -30,9 +30,11 @@
*/ */
/** /**
* \file * \addtogroup uip6
* This header file contains configuration directives for uIPv6 * @{
* multicast support. */
/**
* \defgroup uip6-multicast IPv6 Multicast Forwarding
* *
* We currently support 2 engines: * We currently support 2 engines:
* - 'Stateless Multicast RPL Forwarding' (SMRF) * - 'Stateless Multicast RPL Forwarding' (SMRF)
@ -42,6 +44,14 @@
* in the internet draft: * in the internet draft:
* http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast * http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
* *
* @{
*/
/**
* \file
* This header file contains configuration directives for uIPv6
* multicast support.
*
* \author * \author
* George Oikonomou - <oikonomou@users.sourceforge.net> * George Oikonomou - <oikonomou@users.sourceforge.net>
*/ */
@ -83,7 +93,11 @@
* Multicast API. Similar to NETSTACK, each engine must define a driver and * Multicast API. Similar to NETSTACK, each engine must define a driver and
* populate the fields with suitable function pointers * populate the fields with suitable function pointers
*/ */
/**
* \brief The data structure used to represent a multicast engine
*/
struct uip_mcast6_driver { struct uip_mcast6_driver {
/** The driver's name */
char *name; char *name;
/** Initialize the multicast engine */ /** Initialize the multicast engine */
@ -110,6 +124,7 @@ struct uip_mcast6_driver {
* *
* \return 0: Drop, 1: Deliver * \return 0: Drop, 1: Deliver
* *
*
* When a datagram with a multicast destination address is received, * When a datagram with a multicast destination address is received,
* the forwarding logic in core is bypassed. Instead, we let the * the forwarding logic in core is bypassed. Instead, we let the
* multicast engine handle forwarding internally if and as necessary. * multicast engine handle forwarding internally if and as necessary.
@ -158,5 +173,7 @@ extern const struct uip_mcast6_driver UIP_MCAST6;
#error "Check the value of UIP_CONF_IPV6_RPL in conf files." #error "Check the value of UIP_CONF_IPV6_RPL in conf files."
#endif #endif
/*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/
#endif /* UIP_MCAST6_H_ */ #endif /* UIP_MCAST6_H_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */