deac/osd-contiki
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Tidy-up multicast documentation

Browse source 
* 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
Show stats Download patch file Download diff file Expand all files Collapse all files

19
core/net/ipv6/multicast/roll-tm.c
View file

@ -29,18 +29,13 @@
* 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 - <oikonomou@users.sourceforge.net>
*/
@ -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,
};
/*---------------------------------------------------------------------------*/
/** @} */

44
core/net/ipv6/multicast/roll-tm.h
View file

@ -30,8 +30,13 @@
*/
/**
* \file
* Header file for IPv6 multicast according to the algorithm in the
* \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
@ -45,7 +50,11 @@
* 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 the implementation of the ROLL-TM multicast engine
* \author
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/
@ -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_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */

10
core/net/ipv6/multicast/smrf.c
View file

@ -29,12 +29,14 @@
* 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"
*
* \author
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/
@ -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,
};
/*---------------------------------------------------------------------------*/
/** @} */

17
core/net/ipv6/multicast/smrf.h
View file

@ -29,9 +29,19 @@
* 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 - <oikonomou@users.sourceforge.net>
@ -71,5 +81,8 @@ struct smrf_stats {
uint16_t mcast_bad;
uint16_t mcast_dropped;
};
/*---------------------------------------------------------------------------*/
#endif /* SMRF_H_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */

11
core/net/ipv6/multicast/uip-mcast6-engines.h
View file

@ -29,6 +29,10 @@
* This file is part of the Contiki operating system.
*/
/**
* \addtogroup uip6-multicast
* @{
*/
/**
* \file
* Header file with definition of multicast engine constants
@ -43,8 +47,9 @@
#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_ */
/** @} */

5
core/net/ipv6/multicast/uip-mcast6-route.c
View file

@ -28,6 +28,10 @@
* 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
@ -128,3 +132,4 @@ uip_mcast6_route_init()
list_init(mcast_route_list);
}
/*---------------------------------------------------------------------------*/
/** @} */

47
core/net/ipv6/multicast/uip-mcast6-route.h
View file

@ -28,9 +28,13 @@
* 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 - <oikonomou@users.sourceforge.net>
@ -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_ */
/** @} */

5
core/net/ipv6/multicast/uip-mcast6-stats.c
View file

@ -27,6 +27,10 @@
* 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
@ -47,3 +51,4 @@ uip_mcast6_stats_init(void *stats)
uip_mcast6_stats.engine_stats = stats;
}
/*---------------------------------------------------------------------------*/
/** @} */

36
core/net/ipv6/multicast/uip-mcast6-stats.h
View file

@ -27,6 +27,10 @@
* 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
@ -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_ */
/*---------------------------------------------------------------------------*/
/** @} */

25
core/net/ipv6/multicast/uip-mcast6.h
View file

@ -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 - <oikonomou@users.sourceforge.net>
*/
@ -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_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */