Factor out multicast stats

This commit is contained in:
George Oikonomou 2014-02-27 13:06:23 +00:00
parent cc41efaadd
commit e044fa5cab
8 changed files with 199 additions and 85 deletions

View file

@ -87,10 +87,13 @@ In order to extend multicast with a new engine, perform the following steps:
`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
* Standard multicast stats are maintained in `uip_mcast6_stats`. Don't access
this struct directly, use the macros provided in `uip-mcast6-stats.h` instead
* You can add your own stats extensions. To do so, declare your own stats
struct in your engine's module, e.g `struct foo_stats`
* When you initialise the stats module with `UIP_MCAST6_STATS_INIT`, pass
a pointer to your stats variable as the macro's argument.
An example of how to extend multicast stats, look at the ROLL TM engine
- Open `uip-mcast6.h` and add a section in the `#if` spree. This aims to
configure the uIPv6 core. More specifically, you need to:

View file

@ -433,15 +433,14 @@ struct hbho_mcast {
#endif
/*---------------------------------------------------------------------------*/
/* Maintain Stats */
#if UIP_MCAST6_CONF_STATS
struct roll_tm_stats roll_tm_stats;
#if UIP_MCAST6_STATS
static struct roll_tm_stats stats;
#define STATS_ADD(x) roll_tm_stats.x++
#define STATS_RESET() do { \
memset(&roll_tm_stats, 0, sizeof(roll_tm_stats)); } while(0)
#else
#define STATS_ADD(x)
#define STATS_RESET()
#define ROLL_TM_STATS_ADD(x) stats.x++
#define ROLL_TM_STATS_INIT() do { memset(&stats, 0, sizeof(stats)); } while(0)
#else /* UIP_MCAST6_STATS */
#define ROLL_TM_STATS_ADD(x)
#define ROLL_TM_STATS_INIT()
#endif
/*---------------------------------------------------------------------------*/
/* Internal Data Structures */
@ -627,7 +626,7 @@ handle_timer(void *ptr)
uip_len = locmpptr->buff_len;
memcpy(UIP_IP_BUF, &locmpptr->buff, uip_len);
STATS_ADD(mcast_fwd);
UIP_MCAST6_STATS_ADD(mcast_fwd);
tcpip_output(NULL);
MCAST_PACKET_SEND_CLR(locmpptr);
watchdog_periodic();
@ -879,7 +878,7 @@ icmp_output()
VERBOSE_PRINTF("ROLL TM: ICMPv6 Out - %u bytes\n", payload_len);
tcpip_ipv6_output();
STATS_ADD(icmp_out);
ROLL_TM_STATS_ADD(icmp_out);
return;
}
/*---------------------------------------------------------------------------*/
@ -912,7 +911,7 @@ accept(uint8_t in)
*/
if(uip_is_addr_unspecified(&UIP_IP_BUF->srcipaddr)) {
PRINTF("ROLL TM: Mcast I/O, bad source\n");
STATS_ADD(mcast_bad);
UIP_MCAST6_STATS_ADD(mcast_bad);
return UIP_MCAST6_DROP;
}
#endif
@ -920,13 +919,13 @@ accept(uint8_t in)
/* Check the Next Header field: Must be HBHO */
if(UIP_IP_BUF->proto != UIP_PROTO_HBHO) {
PRINTF("ROLL TM: Mcast I/O, bad proto\n");
STATS_ADD(mcast_bad);
UIP_MCAST6_STATS_ADD(mcast_bad);
return UIP_MCAST6_DROP;
} else {
/* Check the Option Type */
if(UIP_EXT_OPT_FIRST->type != HBHO_OPT_TYPE_TRICKLE) {
PRINTF("ROLL TM: Mcast I/O, bad HBHO type\n");
STATS_ADD(mcast_bad);
UIP_MCAST6_STATS_ADD(mcast_bad);
return UIP_MCAST6_DROP;
}
}
@ -941,21 +940,21 @@ accept(uint8_t in)
/* Short Seed ID: Len MUST be 4 */
if(lochbhmptr->len != HBHO_LEN_SHORT_SEED) {
PRINTF("ROLL TM: Mcast I/O, bad length\n");
STATS_ADD(mcast_bad);
UIP_MCAST6_STATS_ADD(mcast_bad);
return UIP_MCAST6_DROP;
}
#else
/* Long Seed ID: Len MUST be 2 (Seed ID is elided) */
if(lochbhmptr->len != HBHO_LEN_LONG_SEED) {
PRINTF("ROLL TM: Mcast I/O, bad length\n");
STATS_ADD(mcast_bad);
UIP_MCAST6_STATS_ADD(mcast_bad);
return UIP_MCAST6_DROP;
}
#endif
#if UIP_MCAST6_CONF_STATS
#if UIP_MCAST6_STATS
if(in == ROLL_TM_DGRAM_IN) {
STATS_ADD(mcast_in_all);
UIP_MCAST6_STATS_ADD(mcast_in_all);
}
#endif
@ -976,7 +975,7 @@ accept(uint8_t in)
if(SEQ_VAL_IS_LT(seq_val, locswptr->lower_bound)) {
/* Too old, drop */
PRINTF("ROLL TM: Too old\n");
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
for(locmpptr = &buffered_msgs[ROLL_TM_BUFF_NUM - 1];
@ -987,7 +986,7 @@ accept(uint8_t in)
SEQ_VAL_IS_EQ(seq_val, locmpptr->seq_val)) {
/* Seen before , drop */
PRINTF("ROLL TM: Seen before\n");
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
}
@ -1004,7 +1003,7 @@ accept(uint8_t in)
if(!locswptr) {
/* Couldn't allocate window, drop */
PRINTF("ROLL TM: Failed to allocate window\n");
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
@ -1021,13 +1020,13 @@ accept(uint8_t in)
PRINTF("ROLL TM: Buffer reclaim failed\n");
if(locswptr->count == 0) {
window_free(locswptr);
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
}
#if UIP_MCAST6_CONF_STATS
#if UIP_MCAST6_STATS
if(in == ROLL_TM_DGRAM_IN) {
STATS_ADD(mcast_in_unique);
UIP_MCAST6_STATS_ADD(mcast_in_unique);
}
#endif
@ -1106,26 +1105,26 @@ roll_tm_icmp_input()
PRINTF(" to ");
PRINT6ADDR(&UIP_IP_BUF->destipaddr);
PRINTF("\n");
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
return;
}
if(!uip_is_addr_linklocal_allnodes_mcast(&UIP_IP_BUF->destipaddr)
&& !uip_is_addr_linklocal_allrouters_mcast(&UIP_IP_BUF->destipaddr)) {
PRINTF("ROLL TM: ICMPv6 In, bad destination\n");
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
return;
}
if(UIP_ICMP_BUF->icode != ROLL_TM_ICMP_CODE) {
PRINTF("ROLL TM: ICMPv6 In, bad ICMP code\n");
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
return;
}
if(UIP_IP_BUF->ttl != ROLL_TM_IP_HOP_LIMIT) {
PRINTF("ROLL TM: ICMPv6 In, bad TTL\n");
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
return;
}
#endif
@ -1134,7 +1133,7 @@ roll_tm_icmp_input()
PRINT6ADDR(&UIP_IP_BUF->srcipaddr);
PRINTF(" len %u, ext %u\n", uip_len, uip_ext_len);
STATS_ADD(icmp_in);
ROLL_TM_STATS_ADD(icmp_in);
/* Reset Is-Listed bit for all windows */
for(iterswptr = &windows[ROLL_TM_WINS - 1]; iterswptr >= windows;
@ -1167,12 +1166,12 @@ roll_tm_icmp_input()
/* Drop unsupported Seed ID Lengths. S bit: 0->short, 1->long */
#if ROLL_TM_SHORT_SEEDS
if(!SEQUENCE_LIST_GET_S(locslhptr)) {
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
goto drop;
}
#else
if(SEQUENCE_LIST_GET_S(locslhptr)) {
STATS_ADD(icmp_bad);
ROLL_TM_STATS_ADD(icmp_bad);
goto drop;
}
#endif
@ -1375,7 +1374,7 @@ out()
*/
if(accept(ROLL_TM_DGRAM_OUT)) {
tcpip_output(NULL);
STATS_ADD(mcast_out);
UIP_MCAST6_STATS_ADD(mcast_out);
}
drop:
@ -1401,7 +1400,7 @@ in()
return UIP_MCAST6_DROP;
} else {
PRINTF("ROLL TM: Ours. Deliver to upper layers\n");
STATS_ADD(mcast_in_ours);
UIP_MCAST6_STATS_ADD(mcast_in_ours);
return UIP_MCAST6_ACCEPT;
}
}
@ -1414,7 +1413,9 @@ init()
memset(windows, 0, sizeof(windows));
memset(buffered_msgs, 0, sizeof(buffered_msgs));
memset(t, 0, sizeof(t));
STATS_RESET();
ROLL_TM_STATS_INIT();
UIP_MCAST6_STATS_INIT(&stats);
for(iterswptr = &windows[ROLL_TM_WINS - 1]; iterswptr >= windows;
iterswptr--) {

View file

@ -54,6 +54,7 @@
#define ROLL_TM_H_
#include "contiki-conf.h"
#include "net/ipv6/multicast/uip-mcast6-stats.h"
#include <stdint.h>
/*---------------------------------------------------------------------------*/
@ -223,16 +224,9 @@ void roll_tm_icmp_input();
/* Stats datatype */
/*---------------------------------------------------------------------------*/
struct roll_tm_stats {
uint16_t mcast_in_unique;
uint16_t mcast_in_all; /* At layer 3 */
uint16_t mcast_in_ours; /* Unique and we are a group member */
uint16_t mcast_fwd; /* Forwarded by us but we are not the seed */
uint16_t mcast_out; /* We are the seed */
uint16_t mcast_bad;
uint16_t mcast_dropped;
uint16_t icmp_in;
uint16_t icmp_out;
uint16_t icmp_bad;
UIP_MCAST6_STATS_DATATYPE icmp_in;
UIP_MCAST6_STATS_DATATYPE icmp_out;
UIP_MCAST6_STATS_DATATYPE icmp_bad;
};
#endif /* ROLL_TM_H_ */

View file

@ -43,6 +43,7 @@
#include "contiki-net.h"
#include "net/ipv6/multicast/uip-mcast6.h"
#include "net/ipv6/multicast/uip-mcast6-route.h"
#include "net/ipv6/multicast/uip-mcast6-stats.h"
#include "net/ipv6/multicast/smrf.h"
#include "net/rpl/rpl.h"
#include "net/netstack.h"
@ -67,16 +68,6 @@ static uint8_t mcast_len;
static uip_buf_t mcast_buf;
static uint8_t fwd_delay;
static uint8_t fwd_spread;
/* Maintain Stats */
#if UIP_MCAST6_CONF_STATS
struct smrf_stats smrf_stats;
#define STATS_ADD(x) smrf_stats.x++
#define STATS_RESET() do { memset(&smrf_stats, 0, sizeof(smrf_stats)); } while(0)
#else
#define STATS_ADD(x)
#define STATS_RESET()
#endif
/*---------------------------------------------------------------------------*/
/* uIPv6 Pointers */
/*---------------------------------------------------------------------------*/
@ -109,7 +100,7 @@ in()
*/
d = rpl_get_any_dag();
if(!d) {
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
@ -118,7 +109,7 @@ in()
parent_lladdr = uip_ds6_nbr_lladdr_from_ipaddr(parent_ipaddr);
if(parent_lladdr == NULL) {
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
@ -129,23 +120,23 @@ in()
if(memcmp(parent_lladdr, packetbuf_addr(PACKETBUF_ADDR_SENDER),
UIP_LLADDR_LEN)) {
PRINTF("SMRF: Routable in but SMRF ignored it\n");
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
if(UIP_IP_BUF->ttl <= 1) {
STATS_ADD(mcast_dropped);
UIP_MCAST6_STATS_ADD(mcast_dropped);
return UIP_MCAST6_DROP;
}
STATS_ADD(mcast_in_all);
STATS_ADD(mcast_in_unique);
UIP_MCAST6_STATS_ADD(mcast_in_all);
UIP_MCAST6_STATS_ADD(mcast_in_unique);
/* If we have an entry in the mcast routing table, something with
* a higher RPL rank (somewhere down the tree) is a group member */
if(uip_mcast6_route_lookup(&UIP_IP_BUF->destipaddr)) {
/* If we enter here, we will definitely forward */
STATS_ADD(mcast_fwd);
UIP_MCAST6_STATS_ADD(mcast_fwd);
/*
* Add a delay (D) of at least SMRF_FWD_DELAY() to compensate for how
@ -190,7 +181,7 @@ in()
return UIP_MCAST6_DROP;
} else {
PRINTF("SMRF: Ours. Deliver to upper layers\n");
STATS_ADD(mcast_in_ours);
UIP_MCAST6_STATS_ADD(mcast_in_ours);
return UIP_MCAST6_ACCEPT;
}
}
@ -198,7 +189,8 @@ in()
static void
init()
{
STATS_RESET();
UIP_MCAST6_STATS_INIT(NULL);
uip_mcast6_route_init();
}
/*---------------------------------------------------------------------------*/

View file

@ -43,9 +43,6 @@
#ifndef UIP_MCAST6_ENGINES_H_
#define UIP_MCAST6_ENGINES_H_
#include "net/ipv6/multicast/smrf.h"
#include "net/ipv6/multicast/roll-tm.h"
#define UIP_MCAST6_ENGINE_NONE 0 /* Selecting this disables mcast */
#define UIP_MCAST6_ENGINE_SMRF 1
#define UIP_MCAST6_ENGINE_ROLL_TM 2

View file

@ -0,0 +1,49 @@
/*
* Copyright (c) 2014, University of Bristol - http://www.bris.ac.uk
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* \file
* IPv6 multicast forwarding stats maintenance
*
* \author
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/
#include "net/ipv6/multicast/uip-mcast6-stats.h"
#include <string.h>
/*---------------------------------------------------------------------------*/
uip_mcast6_stats_t uip_mcast6_stats;
/*---------------------------------------------------------------------------*/
void
uip_mcast6_stats_init(void *stats)
{
memset(&uip_mcast6_stats, 0, sizeof(uip_mcast6_stats));
uip_mcast6_stats.engine_stats = stats;
}
/*---------------------------------------------------------------------------*/

View file

@ -0,0 +1,91 @@
/*
* Copyright (c) 2014, University of Bristol - http://www.bris.ac.uk
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* \file
* Header file for IPv6 multicast forwarding stats maintenance
*
* \author
* George Oikonomou - <oikonomou@users.sourceforge.net>
*/
#ifndef UIP_MCAST6_STATS_H_
#define UIP_MCAST6_STATS_H_
/*---------------------------------------------------------------------------*/
#include "contiki-conf.h"
#include <stdint.h>
/*---------------------------------------------------------------------------*/
/* The platform can override the stats datatype */
#ifdef UIP_MCAST6_CONF_STATS_DATATYPE
#define UIP_MCAST6_STATS_DATATYPE UIP_MCAST6_CONF_STATS_DATATYPE
#else
#define UIP_MCAST6_STATS_DATATYPE uint16_t
#endif
/*---------------------------------------------------------------------------*/
#ifdef UIP_MCAST6_CONF_STATS
#define UIP_MCAST6_STATS UIP_MCAST6_CONF_STATS
#else
#define UIP_MCAST6_STATS 0
#endif
/*---------------------------------------------------------------------------*/
/* Stats datatype */
/*---------------------------------------------------------------------------*/
typedef struct uip_mcast6_stats {
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 */
UIP_MCAST6_STATS_DATATYPE mcast_bad;
UIP_MCAST6_STATS_DATATYPE mcast_dropped;
void *engine_stats; /* Opaque pointer to an engine's additional stats */
} uip_mcast6_stats_t;
/*---------------------------------------------------------------------------*/
/* Access macros */
/*---------------------------------------------------------------------------*/
#if UIP_MCAST6_STATS
/* Don't access this variable directly, use the macros below */
extern uip_mcast6_stats_t uip_mcast6_stats;
#define UIP_MCAST6_STATS_ADD(x) uip_mcast6_stats.x++
#define UIP_MCAST6_STATS_GET(x) uip_mcast6_stats.x
#define UIP_MCAST6_STATS_INIT(s) uip_mcast6_stats_init(s)
#else /* UIP_MCAST6_STATS */
#define UIP_MCAST6_STATS_ADD(x)
#define UIP_MCAST6_STATS_GET(x) 0
#define UIP_MCAST6_STATS_INIT(s)
#endif /* UIP_MCAST6_STATS */
/*---------------------------------------------------------------------------*/
/**
* \brief Initialise multicast stats
* \param stats A pointer to a struct holding an engine's additional statistics
*/
void uip_mcast6_stats_init(void *stats);
/*---------------------------------------------------------------------------*/
#endif /* UIP_MCAST6_STATS_H_ */

View file

@ -52,6 +52,8 @@
#include "contiki-conf.h"
#include "net/ipv6/multicast/uip-mcast6-engines.h"
#include "net/ipv6/multicast/uip-mcast6-route.h"
#include "net/ipv6/multicast/smrf.h"
#include "net/ipv6/multicast/roll-tm.h"
#include <string.h>
/*---------------------------------------------------------------------------*/
@ -119,12 +121,6 @@ struct uip_mcast6_driver {
*/
uint8_t (* in)(void);
};
/*---------------------------------------------------------------------------
* Multicast Statistics.
*---------------------------------------------------------------------------*/
#ifndef UIP_MCAST6_CONF_STATS
#define UIP_MCAST6_CONF_STATS 0
#endif
/*---------------------------------------------------------------------------*/
/**
* \brief Get a multicast address' scope.
@ -142,27 +138,18 @@ struct uip_mcast6_driver {
#define RPL_CONF_MULTICAST 0 /* Not used by trickle */
#define UIP_CONF_IPV6_ROLL_TM 1 /* ROLL Trickle ICMP type support */
typedef struct roll_tm_stats uip_mcast6_stats_t;
#define UIP_MCAST6_STATS roll_tm_stats
#define UIP_MCAST6 roll_tm_driver
#elif UIP_MCAST6_ENGINE == UIP_MCAST6_ENGINE_SMRF
#define RPL_CONF_MULTICAST 1
typedef struct smrf_stats uip_mcast6_stats_t;
#define UIP_MCAST6_STATS smrf_stats
#define UIP_MCAST6 smrf_driver
#else
#error "Multicast Enabled with an Unknown Engine."
#error "Check the value of UIP_MCAST6_CONF_ENGINE in conf files."
#endif
#endif /* UIP_MCAST6_ENGINE */
extern const struct uip_mcast6_driver UIP_MCAST6;
#if UIP_MCAST6_CONF_STATS
extern uip_mcast6_stats_t UIP_MCAST6_STATS;
#endif
#endif /* UIP_IPV6_MULTICAST */
/*---------------------------------------------------------------------------*/
/* Configuration Checks */
/*---------------------------------------------------------------------------*/