diff --git a/core/net/ipv6/multicast/roll-tm.c b/core/net/ipv6/multicast/roll-tm.c index cfb4e66d5..20a562084 100644 --- a/core/net/ipv6/multicast/roll-tm.c +++ b/core/net/ipv6/multicast/roll-tm.c @@ -29,20 +29,15 @@ * This file is part of the Contiki operating system. */ +/** + * \addtogroup roll-tm + * @{ + */ /** * \file - * This file implements IPv6 MCAST forwarding according to the - * 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 - * + * Implementation of the ROLL TM multicast engine * \author - * George Oikonomou - + * George Oikonomou - */ #include "contiki.h" @@ -1440,6 +1435,9 @@ init() return; } /*---------------------------------------------------------------------------*/ +/** + * \brief The ROLL TM engine driver + */ const struct uip_mcast6_driver roll_tm_driver = { "ROLL TM", init, @@ -1447,3 +1445,4 @@ const struct uip_mcast6_driver roll_tm_driver = { in, }; /*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/ipv6/multicast/roll-tm.h b/core/net/ipv6/multicast/roll-tm.h index 97dabb552..3ab22cc20 100644 --- a/core/net/ipv6/multicast/roll-tm.h +++ b/core/net/ipv6/multicast/roll-tm.h @@ -29,25 +29,34 @@ * This file is part of the Contiki operating system. */ +/** + * \addtogroup uip6-multicast + * @{ + */ +/** + * \defgroup roll-tm ROLL Trickle Multicast + * + * IPv6 multicast according to the algorithm 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. + * + * In draft v2, the document was renamed to + * "Multicast Protocol for Low power and Lossy Networks (MPL)" + * Due to very significant changes between draft versions 1 and 2, + * MPL will be implemented as a separate engine and this file here + * will provide legacy support for Draft v1. + * @{ + */ /** * \file - * Header file for IPv6 multicast according to the algorithm 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. - * - * In draft v2, the document was renamed to - * "Multicast Protocol for Low power and Lossy Networks (MPL)" - * Due to very significant changes between draft versions 1 and 2, - * MPL will be implemented as a separate engine and this file here - * will provide legacy support for Draft v1. - * + * Header file for the implementation of the ROLL-TM multicast engine * \author - * George Oikonomou - + * George Oikonomou - */ #ifndef ROLL_TM_H_ @@ -60,9 +69,9 @@ /*---------------------------------------------------------------------------*/ /* Protocol Constants */ /*---------------------------------------------------------------------------*/ -#define ROLL_TM_VER 1 /* Supported Draft Version */ -#define ROLL_TM_ICMP_CODE 0 /* ICMPv6 code field */ -#define ROLL_TM_IP_HOP_LIMIT 0xFF /* Hop limit for ICMP messages */ +#define ROLL_TM_VER 1 /**< Supported Draft Version */ +#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_INFINITE_REDUNDANCY 0xFF #define ROLL_TM_DGRAM_OUT 0 #define ROLL_TM_DGRAM_IN 1 @@ -153,7 +162,7 @@ /*---------------------------------------------------------------------------*/ /* Configuration */ /*---------------------------------------------------------------------------*/ -/* +/** * Number of Sliding Windows * In essence: How many unique sources of simultaneous multicast traffic do we * want to support for our lowpan @@ -166,7 +175,7 @@ #define ROLL_TM_WINS 2 #endif /*---------------------------------------------------------------------------*/ -/* +/** * Maximum Number of Buffered Multicast Messages * 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 @@ -178,7 +187,7 @@ #define ROLL_TM_BUFF_NUM 6 #endif /*---------------------------------------------------------------------------*/ -/* +/** * 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 * 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 #endif /*---------------------------------------------------------------------------*/ -/* +/** * Destination address for our ICMPv6 advertisements. The draft gives us a * choice between LL all-nodes or LL all-routers * @@ -202,7 +211,7 @@ #define ROLL_TM_DEST_ALL_NODES 0 #endif /*---------------------------------------------------------------------------*/ -/* +/** * M param for our outgoing messages * By default, we set the M bit (conservative). Define this as 0 to clear the * M bit in our outgoing messages (aggressive) @@ -215,10 +224,21 @@ /*---------------------------------------------------------------------------*/ /* Stats datatype */ /*---------------------------------------------------------------------------*/ +/** + * \brief Multicast stats extension for the ROLL TM engine + */ struct roll_tm_stats { + /** Number of received ICMP datagrams */ UIP_MCAST6_STATS_DATATYPE icmp_in; + + /** Number of ICMP datagrams sent */ UIP_MCAST6_STATS_DATATYPE icmp_out; + + /** Number of malformed ICMP datagrams seen by us */ UIP_MCAST6_STATS_DATATYPE icmp_bad; }; - +/*---------------------------------------------------------------------------*/ #endif /* ROLL_TM_H_ */ +/*---------------------------------------------------------------------------*/ +/** @} */ +/** @} */ diff --git a/core/net/ipv6/multicast/smrf.c b/core/net/ipv6/multicast/smrf.c index 9e49fdc40..b1dccbd19 100644 --- a/core/net/ipv6/multicast/smrf.c +++ b/core/net/ipv6/multicast/smrf.c @@ -29,14 +29,16 @@ * This file is part of the Contiki operating system. */ +/** + * \addtogroup smrf-multicast + * @{ + */ /** * \file - * This file implements 'Stateless Multicast RPL Forwarding' (SMRF) - * - * It will only work in RPL networks in MOP 3 "Storing with Multicast" + * This file implements 'Stateless Multicast RPL Forwarding' (SMRF) * * \author - * George Oikonomou - + * George Oikonomou - */ #include "contiki.h" @@ -199,6 +201,9 @@ out() return; } /*---------------------------------------------------------------------------*/ +/** + * \brief The SMRF engine driver + */ const struct uip_mcast6_driver smrf_driver = { "SMRF", init, @@ -206,3 +211,4 @@ const struct uip_mcast6_driver smrf_driver = { in, }; /*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/ipv6/multicast/smrf.h b/core/net/ipv6/multicast/smrf.h index d19fd6de8..51dcf216e 100644 --- a/core/net/ipv6/multicast/smrf.h +++ b/core/net/ipv6/multicast/smrf.h @@ -29,12 +29,22 @@ * 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 - * Header file for 'Stateless Multicast RPL Forwarding' (SMRF) + * Header file for the SMRF forwarding engine * * \author - * George Oikonomou - + * George Oikonomou - */ #ifndef SMRF_H_ @@ -71,5 +81,8 @@ struct smrf_stats { uint16_t mcast_bad; uint16_t mcast_dropped; }; - +/*---------------------------------------------------------------------------*/ #endif /* SMRF_H_ */ +/*---------------------------------------------------------------------------*/ +/** @} */ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6-engines.h b/core/net/ipv6/multicast/uip-mcast6-engines.h index cea3c9ecc..f4bff657a 100644 --- a/core/net/ipv6/multicast/uip-mcast6-engines.h +++ b/core/net/ipv6/multicast/uip-mcast6-engines.h @@ -29,22 +29,27 @@ * This file is part of the Contiki operating system. */ +/** + * \addtogroup uip6-multicast + * @{ + */ /** * \file - * Header file with definition of multicast engine constants + * Header file with definition of multicast engine constants * - * When writing a new engine, add it here with a unique number and - * then modify uip-mcast6.h accordingly + * When writing a new engine, add it here with a unique number and + * then modify uip-mcast6.h accordingly * * \author - * George Oikonomou - + * George Oikonomou - */ #ifndef UIP_MCAST6_ENGINES_H_ #define UIP_MCAST6_ENGINES_H_ -#define UIP_MCAST6_ENGINE_NONE 0 /* Selecting this disables mcast */ -#define UIP_MCAST6_ENGINE_SMRF 1 -#define UIP_MCAST6_ENGINE_ROLL_TM 2 +#define UIP_MCAST6_ENGINE_NONE 0 /**< Selecting this disables mcast */ +#define UIP_MCAST6_ENGINE_SMRF 1 /**< The SMRF engine */ +#define UIP_MCAST6_ENGINE_ROLL_TM 2 /**< The ROLL TM engine */ #endif /* UIP_MCAST6_ENGINES_H_ */ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6-route.c b/core/net/ipv6/multicast/uip-mcast6-route.c index e414fbf17..f6b9737fc 100644 --- a/core/net/ipv6/multicast/uip-mcast6-route.c +++ b/core/net/ipv6/multicast/uip-mcast6-route.c @@ -28,12 +28,16 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \addtogroup uip6-multicast + * @{ + */ /** * \file - * Multicast routing table manipulation + * Multicast routing table manipulation * * \author - * George Oikonomou - + * George Oikonomou - */ #include "contiki.h" @@ -128,3 +132,4 @@ uip_mcast6_route_init() list_init(mcast_route_list); } /*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6-route.h b/core/net/ipv6/multicast/uip-mcast6-route.h index ef5d43f77..95e808676 100644 --- a/core/net/ipv6/multicast/uip-mcast6-route.h +++ b/core/net/ipv6/multicast/uip-mcast6-route.h @@ -28,12 +28,16 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \addtogroup uip6-multicast + * @{ + */ /** * \file - * Multicast routing table manipulation + * Header file for multicast routing table manipulation * * \author - * George Oikonomou - + * George Oikonomou - */ #ifndef UIP_MCAST6_ROUTE_H_ #define UIP_MCAST6_ROUTE_H_ @@ -45,18 +49,48 @@ /*---------------------------------------------------------------------------*/ /** \brief An entry in the multicast routing table */ typedef struct uip_mcast6_route { - struct uip_mcast6_route *next; - uip_ipaddr_t group; - uint32_t lifetime; /* seconds */ - void *dag; /* Pointer to an rpl_dag_t struct */ + struct uip_mcast6_route *next; /**< Routes are arranged in a linked list */ + uip_ipaddr_t group; /**< The multicast group */ + uint32_t lifetime; /**< Entry lifetime seconds */ + void *dag; /**< Pointer to an rpl_dag_t struct */ } uip_mcast6_route_t; /*---------------------------------------------------------------------------*/ /** \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); + +/** + * \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); -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); + +/** + * \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); /*---------------------------------------------------------------------------*/ /** @@ -73,3 +107,4 @@ void uip_mcast6_route_init(void); /** @} */ #endif /* UIP_MCAST6_ROUTE_H_ */ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6-stats.c b/core/net/ipv6/multicast/uip-mcast6-stats.c index ed23747f1..d617358ba 100644 --- a/core/net/ipv6/multicast/uip-mcast6-stats.c +++ b/core/net/ipv6/multicast/uip-mcast6-stats.c @@ -27,12 +27,16 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \addtogroup uip6-multicast + * @{ + */ /** * \file - * IPv6 multicast forwarding stats maintenance + * IPv6 multicast forwarding stats maintenance * * \author - * George Oikonomou - + * George Oikonomou - */ #include "net/ipv6/multicast/uip-mcast6-stats.h" @@ -47,3 +51,4 @@ uip_mcast6_stats_init(void *stats) uip_mcast6_stats.engine_stats = stats; } /*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6-stats.h b/core/net/ipv6/multicast/uip-mcast6-stats.h index 1e3775934..263758b66 100644 --- a/core/net/ipv6/multicast/uip-mcast6-stats.h +++ b/core/net/ipv6/multicast/uip-mcast6-stats.h @@ -27,12 +27,16 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + * \addtogroup uip6-multicast + * @{ + */ /** * \file - * Header file for IPv6 multicast forwarding stats maintenance + * Header file for IPv6 multicast forwarding stats maintenance * * \author - * George Oikonomou - + * George Oikonomou - */ #ifndef UIP_MCAST6_STATS_H_ #define UIP_MCAST6_STATS_H_ @@ -56,15 +60,35 @@ /*---------------------------------------------------------------------------*/ /* 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 { + /** Count of unique datagrams received */ 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 */ - UIP_MCAST6_STATS_DATATYPE mcast_fwd; /* Forwarded by us but we are not the seed */ - UIP_MCAST6_STATS_DATATYPE mcast_out; /* We are the seed */ + + /** Count of all datagrams received */ + UIP_MCAST6_STATS_DATATYPE mcast_in_all; + + /** 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; + + /** Count of multicast datagrams correclty formed but dropped by us */ 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; /*---------------------------------------------------------------------------*/ /* Access macros */ @@ -89,3 +113,5 @@ extern uip_mcast6_stats_t uip_mcast6_stats; void uip_mcast6_stats_init(void *stats); /*---------------------------------------------------------------------------*/ #endif /* UIP_MCAST6_STATS_H_ */ +/*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/net/ipv6/multicast/uip-mcast6.h b/core/net/ipv6/multicast/uip-mcast6.h index 9bd2b2b2d..de2003839 100644 --- a/core/net/ipv6/multicast/uip-mcast6.h +++ b/core/net/ipv6/multicast/uip-mcast6.h @@ -30,9 +30,11 @@ */ /** - * \file - * This header file contains configuration directives for uIPv6 - * multicast support. + * \addtogroup uip6 + * @{ + */ +/** + * \defgroup uip6-multicast IPv6 Multicast Forwarding * * We currently support 2 engines: * - 'Stateless Multicast RPL Forwarding' (SMRF) @@ -42,6 +44,14 @@ * in the internet draft: * http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast * + * @{ + */ + +/** + * \file + * This header file contains configuration directives for uIPv6 + * multicast support. + * * \author * George Oikonomou - */ @@ -83,7 +93,11 @@ * Multicast API. Similar to NETSTACK, each engine must define a driver and * populate the fields with suitable function pointers */ +/** + * \brief The data structure used to represent a multicast engine + */ struct uip_mcast6_driver { + /** The driver's name */ char *name; /** Initialize the multicast engine */ @@ -110,6 +124,7 @@ struct uip_mcast6_driver { * * \return 0: Drop, 1: Deliver * + * * When a datagram with a multicast destination address is received, * the forwarding logic in core is bypassed. Instead, we let the * 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." #endif /*---------------------------------------------------------------------------*/ - #endif /* UIP_MCAST6_H_ */ +/*---------------------------------------------------------------------------*/ +/** @} */ +/** @} */