Skip to content

Commit

Permalink
Tidy-up multicast documentation
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@g-oikonomou
g-oikonomou committed Feb 15, 2015
1 parent a4e7cc2 commit 5efb3f0
Show file tree
Hide file tree
Showing 10 changed files with 200 additions and 69 deletions.
21 changes: 10 additions & 11 deletions core/net/ipv6/multicast/roll-tm.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#include "contiki.h"
Expand Down Expand Up @@ -1440,10 +1435,14 @@ init()
return;
}
/*---------------------------------------------------------------------------*/
/**
* \brief The ROLL TM engine driver
*/
const struct uip_mcast6_driver roll_tm_driver = {
"ROLL TM",
init,
out,
in,
};
/*---------------------------------------------------------------------------*/
/** @} */
64 changes: 42 additions & 22 deletions core/net/ipv6/multicast/roll-tm.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,24 +30,33 @@
*/

/**
* \file
* Header file for IPv6 multicast according to the algorithm in the
* "MCAST Forwarding Using Trickle" internet draft.
* \addtogroup uip6-multicast
* @{
*/
/**
* \defgroup roll-tm ROLL Trickle Multicast
*
* The current version of the draft can always be found in
* http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
* IPv6 multicast according to the algorithm in the
* "MCAST Forwarding Using Trickle" internet draft.
*
* This implementation is based on the draft version stored in
* ROLL_TM_VER.
* The current version of the draft can always be found in
* http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
*
* 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.
* 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 the implementation of the ROLL-TM multicast engine
* \author
* George Oikonomou - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#ifndef ROLL_TM_H_
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
*
Expand All @@ -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)
Expand All @@ -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_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */
14 changes: 10 additions & 4 deletions core/net/ipv6/multicast/smrf.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#include "contiki.h"
Expand Down Expand Up @@ -199,10 +201,14 @@ out()
return;
}
/*---------------------------------------------------------------------------*/
/**
* \brief The SMRF engine driver
*/
const struct uip_mcast6_driver smrf_driver = {
"SMRF",
init,
out,
in,
};
/*---------------------------------------------------------------------------*/
/** @} */
19 changes: 16 additions & 3 deletions core/net/ipv6/multicast/smrf.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#ifndef SMRF_H_
Expand Down Expand Up @@ -71,5 +81,8 @@ struct smrf_stats {
uint16_t mcast_bad;
uint16_t mcast_dropped;
};

/*---------------------------------------------------------------------------*/
#endif /* SMRF_H_ */
/*---------------------------------------------------------------------------*/
/** @} */
/** @} */
19 changes: 12 additions & 7 deletions core/net/ipv6/multicast/uip-mcast6-engines.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#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_ */
/** @} */
9 changes: 7 additions & 2 deletions core/net/ipv6/multicast/uip-mcast6-route.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/

#include "contiki.h"
Expand Down Expand Up @@ -128,3 +132,4 @@ uip_mcast6_route_init()
list_init(mcast_route_list);
}
/*---------------------------------------------------------------------------*/
/** @} */
49 changes: 42 additions & 7 deletions core/net/ipv6/multicast/uip-mcast6-route.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 - <oikonomou@users.sourceforge.net>
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/
#ifndef UIP_MCAST6_ROUTE_H_
#define UIP_MCAST6_ROUTE_H_
Expand All @@ -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);
/*---------------------------------------------------------------------------*/
/**
Expand All @@ -73,3 +107,4 @@ void uip_mcast6_route_init(void);
/** @} */

#endif /* UIP_MCAST6_ROUTE_H_ */
/** @} */
Loading

0 comments on commit 5efb3f0

Please sign in to comment.