From ffeceb9164e91814a2b76586ed13ee22e4925ee3 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Mon, 16 Apr 2012 10:27:43 +0100 Subject: [PATCH] Add a Trickle Timer Library (RFC 6206) --- Makefile.include | 2 +- core/lib/trickle-timer.c | 407 ++++++++++++++++++++++++++++++++ core/lib/trickle-timer.h | 491 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 899 insertions(+), 1 deletion(-) create mode 100755 core/lib/trickle-timer.c create mode 100755 core/lib/trickle-timer.h diff --git a/Makefile.include b/Makefile.include index 68b35e62d..3abdbb493 100644 --- a/Makefile.include +++ b/Makefile.include @@ -59,7 +59,7 @@ include $(CONTIKI)/core/net/mac/Makefile.mac SYSTEM = process.c procinit.c autostart.c elfloader.c profile.c \ timetable.c timetable-aggregate.c compower.c serial-line.c THREADS = mt.c -LIBS = memb.c mmem.c timer.c list.c etimer.c ctimer.c energest.c rtimer.c stimer.c \ +LIBS = memb.c mmem.c timer.c list.c etimer.c ctimer.c energest.c rtimer.c stimer.c trickle-timer.c \ print-stats.c ifft.c crc16.c random.c checkpoint.c ringbuf.c settings.c DEV = nullradio.c diff --git a/core/lib/trickle-timer.c b/core/lib/trickle-timer.c new file mode 100755 index 000000000..1297fdb4d --- /dev/null +++ b/core/lib/trickle-timer.c @@ -0,0 +1,407 @@ +/** + * \addtogroup trickle-timer + * @{ + */ + +/** + * \file + * Trickle timer library implementation. + * \author + * George Oikonomou - + */ + +/* + * Copyright (c) 2012, George Oikonomou - + * 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. + */ +#include "contiki-conf.h" +#include "lib/trickle-timer.h" +#include "sys/ctimer.h" +#include "sys/cc.h" +#include "lib/random.h" +/*---------------------------------------------------------------------------*/ +#define DEBUG 0 + +#if DEBUG +#include +#define PRINTF(...) printf(__VA_ARGS__) +#else +#define PRINTF(...) +#endif +/*---------------------------------------------------------------------------*/ +/** + * \brief Wide randoms for platforms using a 4-byte wide clock + * (see ::TRICKLE_TIMER_WIDE_RAND) + */ +#if TRICKLE_TIMER_WIDE_RAND +#define tt_rand() wide_rand() +#else +#define tt_rand() random_rand() +#endif +/*---------------------------------------------------------------------------*/ +/* Declarations of variables of local interest */ +/*---------------------------------------------------------------------------*/ +static struct trickle_timer *loctt; /* Pointer to a struct for local use */ +static clock_time_t loc_clock; /* A local, general-purpose placeholder */ + +static void fire(void *ptr); +static void double_interval(void *ptr); +/*---------------------------------------------------------------------------*/ +/* Local utilities and functions to be used as ctimer callbacks */ +/*---------------------------------------------------------------------------*/ +#if TRICKLE_TIMER_WIDE_RAND +/* Returns a 4-byte wide, unsigned random number */ +static uint32_t +wide_rand() +{ + return ((uint32_t)random_rand() << 16 | random_rand()); +} +#endif +/*---------------------------------------------------------------------------*/ +/* + * Returns the maximum sane Imax value for a given Imin + * + * This function is a variant of a fairly standard 'Count Leading Zeros'. It + * has three flavours. The most suitable one for a specific platform can be + * configured by changing the value of TRICKLE_TIMER_CONF_MAX_IMAX_WIDTH + * in the platform's contiki-conf.h + */ +#if TRICKLE_TIMER_ERROR_CHECKING +static uint8_t +max_imax(clock_time_t value) +{ + uint8_t zeros = 0; +#if (TRICKLE_TIMER_MAX_IMAX_WIDTH==TRICKLE_TIMER_MAX_IMAX_GENERIC) + uint8_t i; + clock_time_t mask = 0xFFFF; + + value--; + + for(i = sizeof(clock_time_t) << 2; i > 0; i >>= 1) { + if((value & (mask <<= i)) == 0) { + zeros += i; + value <<= i; + } + } + +#elif (TRICKLE_TIMER_MAX_IMAX_WIDTH==TRICKLE_TIMER_MAX_IMAX_16_BIT) + if((value & 0xFF00) == 0) { + zeros += 8; + value <<= 8; + } + if((value & 0xF000) == 0) { + zeros += 4; + value <<= 4; + } + if((value & 0xC000) == 0) { + zeros += 2; + value <<= 2; + } + if((value & 0x8000) == 0) { + zeros++; + } +#elif (TRICKLE_TIMER_MAX_IMAX_WIDTH==TRICKLE_TIMER_MAX_IMAX_32_BIT) + if((value & 0xFFFF0000) == 0) { + zeros += 16; + value <<= 16; + } + if((value & 0xFF000000) == 0) { + zeros += 8; + value <<= 8; + } + if((value & 0xF0000000) == 0) { + zeros += 4; + value <<= 4; + } + if((value & 0xC0000000) == 0) { + zeros += 2; + value <<= 2; + } + if((value & 0x80000000) == 0) { + zeros += 1; + } +#endif + + return zeros - 1; /* Always non-negative due to the range of 'value' */ +} +#endif /* TRICKLE_TIMER_ERROR_CHECKING */ +/*---------------------------------------------------------------------------*/ +/* Returns a random time point t in [I/2 , I) */ +static clock_time_t +get_t(clock_time_t i_cur) +{ + i_cur >>= 1; + + PRINTF("trickle_timer get t: [%lu, %lu)\n", (unsigned long)i_cur, + (unsigned long)(i_cur << 1)); + + return i_cur + (tt_rand() % i_cur); +} +/*---------------------------------------------------------------------------*/ +static void +schedule_for_end(struct trickle_timer *tt) +{ + /* Reset our ctimer, schedule interval_end to run at time I */ + clock_time_t now = clock_time(); + + loc_clock = TRICKLE_TIMER_INTERVAL_END(tt) - now; + + PRINTF("trickle_timer sched for end: at %lu, end in %ld\n", + (unsigned long)clock_time(), (signed long)loc_clock); + + /* Interval's end will happen in loc_clock ticks. Make sure this isn't in + * the past... */ + if(loc_clock > (TRICKLE_TIMER_CLOCK_MAX >> 1)) { + loc_clock = 0; /* Interval ended in the past, schedule for in 0 */ + PRINTF("trickle_timer doubling: Was in the past. Compensating\n"); + } + + ctimer_set(&tt->ct, loc_clock, double_interval, tt); +} +/*---------------------------------------------------------------------------*/ +/* This is used as a ctimer callback, thus its argument must be void *. ptr is + * a pointer to the struct trickle_timer that fired */ +static void +double_interval(void *ptr) +{ + clock_time_t last_end; + + /* 'cast' ptr to a struct trickle_timer */ + loctt = (struct trickle_timer *)ptr; + + loctt->c = 0; + + PRINTF("trickle_timer doubling: at %lu, (was for %lu), ", + (unsigned long)clock_time(), + (unsigned long)TRICKLE_TIMER_INTERVAL_END(loctt)); + + /* Remember the previous interval's end (absolute time), before we double */ + last_end = TRICKLE_TIMER_INTERVAL_END(loctt); + + /* Double the interval if we have to */ + if(loctt->i_cur <= TRICKLE_TIMER_INTERVAL_MAX(loctt) >> 1) { + /* If I <= Imax/2, we double */ + loctt->i_cur <<= 1; + PRINTF("I << 1 = %lu\n", (unsigned long)loctt->i_cur); + } else { + /* We may have I > Imax/2 but I <> Imax, in which case we set to Imax + * This will happen when I didn't start as Imin (before the first reset) */ + loctt->i_cur = TRICKLE_TIMER_INTERVAL_MAX(loctt); + PRINTF("I = Imax = %lu\n", (unsigned long)loctt->i_cur); + } + + /* Random t in [I/2, I) */ + loc_clock = get_t(loctt->i_cur); + + PRINTF("trickle_timer doubling: t=%lu\n", (unsigned long)loc_clock); + +#if TRICKLE_TIMER_COMPENSATE_DRIFT + /* Schedule for t ticks after the previous interval's end, not after now. If + * that is in the past, schedule in 0 */ + loc_clock = (last_end + loc_clock) - clock_time(); + PRINTF("trickle_timer doubling: at %lu, in %ld ticks\n", + (unsigned long)clock_time(), (signed long)loc_clock); + if(loc_clock > (TRICKLE_TIMER_CLOCK_MAX >> 1)) { + /* Oops, that's in the past */ + loc_clock = 0; + PRINTF("trickle_timer doubling: Was in the past. Compensating\n"); + } + ctimer_set(&loctt->ct, loc_clock, fire, loctt); + + /* Store the actual interval start (absolute time), we need it later. + * We pretend that it started at the same time when the last one ended */ + loctt->i_start = last_end; +#else + /* Assumed that the previous interval's end is 'now' and schedule in t ticks + * after 'now', ignoring potential offsets */ + ctimer_set(&loctt->ct, loc_clock, fire, loctt); + /* Store the actual interval start (absolute time), we need it later */ + loctt->i_start = loctt->ct.etimer.timer.start; +#endif + + PRINTF("trickle_timer doubling: Last end %lu, new end %lu, for %lu, I=%lu\n", + (unsigned long)last_end, + (unsigned long)TRICKLE_TIMER_INTERVAL_END(loctt), + (unsigned long)(loctt->ct.etimer.timer.start + + loctt->ct.etimer.timer.interval), + (unsigned long)(loctt->i_cur)); +} +/*---------------------------------------------------------------------------*/ +/* Called by the ctimer module at time t within the current interval. ptr is + * a pointer to the struct trickle_timer of interest */ +static void +fire(void *ptr) +{ + /* 'cast' c to a struct trickle_timer */ + loctt = (struct trickle_timer *)ptr; + + PRINTF("trickle_timer fire: at %lu (was for %lu)\n", + (unsigned long)clock_time(), + (unsigned long)(loctt->ct.etimer.timer.start + + loctt->ct.etimer.timer.interval)); + + if(loctt->cb) { + /* + * Call the protocol's TX callback, with the suppression status as an + * argument. + */ + PRINTF("trickle_timer fire: Suppression Status %u (%u < %u)\n", + TRICKLE_TIMER_PROTO_TX_ALLOW(loctt), loctt->c, loctt->k); + loctt->cb(loctt->cb_arg, TRICKLE_TIMER_PROTO_TX_ALLOW(loctt)); + } + + schedule_for_end(loctt); +} +/*---------------------------------------------------------------------------*/ +/* New trickle interval, either due to a newly set trickle timer or due to an + * inconsistency. Schedule 'fire' to be called in t ticks. */ +static void +new_interval(struct trickle_timer *tt) +{ + tt->c = 0; + + /* Random t in [I/2, I) */ + loc_clock = get_t(tt->i_cur); + + ctimer_set(&tt->ct, loc_clock, fire, tt); + + /* Store the actual interval start (absolute time), we need it later */ + tt->i_start = tt->ct.etimer.timer.start; + PRINTF("trickle_timer new interval: at %lu, ends %lu, ", + (unsigned long)clock_time(), + (unsigned long)TRICKLE_TIMER_INTERVAL_END(tt)); + PRINTF("t=%lu, I=%lu\n", (unsigned long)loc_clock, (unsigned long)tt->i_cur); +} +/*---------------------------------------------------------------------------*/ +/* Functions to be called by the protocol implementation */ +/*---------------------------------------------------------------------------*/ +void +trickle_timer_consistency(struct trickle_timer *tt) +{ + if(tt->c < 0xFF) { + tt->c++; + } + PRINTF("trickle_timer consistency: c=%u\n", tt->c); +} +/*---------------------------------------------------------------------------*/ +void +trickle_timer_inconsistency(struct trickle_timer *tt) +{ + /* "If I is equal to Imin when Trickle hears an "inconsistent" transmission, + * Trickle does nothing." */ + if(tt->i_cur != tt->i_min) { + PRINTF("trickle_timer inconsistency\n"); + tt->i_cur = tt->i_min; + + new_interval(tt); + } +} +/*---------------------------------------------------------------------------*/ +uint8_t +trickle_timer_config(struct trickle_timer *tt, clock_time_t i_min, + uint8_t i_max, uint8_t k) +{ +#if TRICKLE_TIMER_ERROR_CHECKING + /* + * Although in theory Imin=1 is a valid value, it would break get_t() and + * doesn't make sense anyway. Thus Valid Imin values are in the range: + * 1 < Imin <= (TRICKLE_TIMER_CLOCK_MAX >> 1) + 1 + */ + if(TRICKLE_TIMER_IMIN_IS_BAD(i_min)) { + PRINTF("trickle_timer config: Bad Imin value\n"); + return TRICKLE_TIMER_ERROR; + } + + if(tt == NULL || i_max == 0 || k == 0) { + PRINTF("trickle_timer config: Bad arguments\n"); + return TRICKLE_TIMER_ERROR; + } + + /* + * If clock_time_t is not wide enough to store Imin << Imax, we adjust Imax + * + * This means that 'we' are likely to have a different Imax than 'them' + * See RFC 6206, sec 6.3 for the consequences of this situation + */ + if(TRICKLE_TIMER_IPAIR_IS_BAD(i_min, i_max)) { + PRINTF("trickle_timer config: %lu << %u would exceed clock boundaries. ", + (unsigned long)i_min, i_max); + + /* For this Imin, get the maximum sane Imax */ + i_max = max_imax(i_min); + PRINTF("trickle_timer config: Using Imax=%u\n", i_max); + } +#endif + + tt->i_min = i_min; + tt->i_max = i_max; + tt->i_max_abs = i_min << i_max; + tt->k = k; + + PRINTF("trickle_timer config: Imin=%lu, Imax=%u, k=%u\n", + (unsigned long)tt->i_min, tt->i_max, tt->k); + + return TRICKLE_TIMER_SUCCESS; +} +/*---------------------------------------------------------------------------*/ +uint8_t +trickle_timer_set(struct trickle_timer *tt, trickle_timer_cb_t proto_cb, + void *ptr) +{ +#if TRICKLE_TIMER_ERROR_CHECKING + /* Sanity checks */ + if(tt == NULL || proto_cb == NULL) { + PRINTF("trickle_timer set: Bad arguments\n"); + return TRICKLE_TIMER_ERROR; + } +#endif + + tt->cb = proto_cb; + tt->cb_arg = ptr; + + /* Random I in [Imin , Imax] */ + tt->i_cur = tt->i_min + + (tt_rand() % (TRICKLE_TIMER_INTERVAL_MAX(tt) - tt->i_min + 1)); + + PRINTF("trickle_timer set: I=%lu in [%lu , %lu]\n", (unsigned long)tt->i_cur, + (unsigned long)tt->i_min, + (unsigned long)TRICKLE_TIMER_INTERVAL_MAX(tt)); + + new_interval(tt); + + PRINTF("trickle_timer set: at %lu, ends %lu, t=%lu in [%lu , %lu)\n", + (unsigned long)tt->i_start, + (unsigned long)TRICKLE_TIMER_INTERVAL_END(tt), + (unsigned long)tt->ct.etimer.timer.interval, + (unsigned long)tt->i_cur >> 1, (unsigned long)tt->i_cur); + + return TRICKLE_TIMER_SUCCESS; +} +/*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/core/lib/trickle-timer.h b/core/lib/trickle-timer.h new file mode 100755 index 000000000..c7c004748 --- /dev/null +++ b/core/lib/trickle-timer.h @@ -0,0 +1,491 @@ +/** \addtogroup lib + * @{ */ + +/** + * \defgroup trickle-timer Trickle timers + * + * This library implements timers which behave in accordance with RFC 6206 + * "The Trickle Algorithm" (http://tools.ietf.org/html/rfc6206) + * + * Protocols wishing to use trickle timers, may use this library instead of + * implementing the trickle algorithm internally. + * + * The protocol implementation will declare one (or more) variable(s) of type + * struct ::trickle_timer and will then populate its fields by calling + * trickle_timer_config(). trickle_timer_set() will start the timer. + * + * When the timer reaches time t within the current trickle interval, the + * library will call a protocol-provided callback, which will signal to the + * protocol that it is time to TX (see algorithm step 4 in the RFC). + * + * The proto does not need to check the suppression conditions. This is done by + * the library and if TX must be suppressed, the callback won't be called at + * all. + * + * The library also provides functions to be called when the protocol hears a + * 'consistent' or 'inconsistent' message and when an 'external event' occurs + * (in this context, those terms have the exact same meaning as in the RFC). + * + * @{ + */ + + +/** + * \file + * Trickle timer library header file. + * + * \author + * George Oikonomou - + */ + +/* + * Copyright (c) 2012, George Oikonomou - + * 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. + */ +#ifndef __TRICKLE_TIMER_H__ +#define __TRICKLE_TIMER_H__ + +#include "contiki-conf.h" +#include "sys/ctimer.h" +/*---------------------------------------------------------------------------*/ +/* Trickle Timer Library Constants */ +/*---------------------------------------------------------------------------*/ +/** + * \name Trickle Timer Library: Constants + * @{ + */ +/*---------------------------------------------------------------------------*/ +/** + * \brief Set as value of k to disable suppression + */ +#define TRICKLE_TIMER_INFINITE_REDUNDANCY 0x00 + +#define TRICKLE_TIMER_ERROR 0 +#define TRICKLE_TIMER_SUCCESS 1 + +/** + * \brief Use as the value of TRICKLE_TIMER_MAX_IMAX_WIDTH to enable the + * generic 'Find max Imax' routine + */ +#define TRICKLE_TIMER_MAX_IMAX_GENERIC 0 +/** + * \brief Use as the value of TRICKLE_TIMER_MAX_IMAX_WIDTH to enable the 16-bit + * 'Find max Imax' routine + */ +#define TRICKLE_TIMER_MAX_IMAX_16_BIT 1 +/** + * \brief Use as the value of TRICKLE_TIMER_MAX_IMAX_WIDTH to enable the 32-bit + * 'Find max Imax' routine + */ +#define TRICKLE_TIMER_MAX_IMAX_32_BIT 2 + +/** + * \brief Constants used as values for the \e suppress param of + * trickle_timer_cb_t + */ +#define TRICKLE_TIMER_TX_SUPPRESS 0 +#define TRICKLE_TIMER_TX_OK 1 +/** @} */ +/*---------------------------------------------------------------------------*/ +/** + * \brief Controls whether the library will try to compensate for time drifts + * caused by getting called later than scheduled. + * + * 1: Enabled (default). 0: Disabled + * + * To override the default, define TRICKLE_TIMER_CONF_COMPENSATE_DRIFT in + * contiki-conf.h + * + * Bear in mind that this controls the behaviour of the entire library (i.e. + * all trickle timers) and not of an individual timer + */ +#ifdef TRICKLE_TIMER_CONF_COMPENSATE_DRIFT +#define TRICKLE_TIMER_COMPENSATE_DRIFT TRICKLE_TIMER_CONF_COMPENSATE_DRIFT +#else +#define TRICKLE_TIMER_COMPENSATE_DRIFT 1 +#endif +/*---------------------------------------------------------------------------*/ +/** + * \brief Turns on support for 4-byte wide, unsigned random numbers + * + * We need this for platforms which have a 4-byte wide clock_time_t. For those + * platforms and if Imin << Imax is GT 0xFFFF, random_rand alone is not always + * enough to generate a correct t in [I/2, I). Specifically, we need wide + * randoms when I > 0x1FFFF. + * + * For platforms with a 2-byte wide clock_time_t, this can be defined as 0 + * to reduce code footprint and increase speed. + */ +#ifdef TRICKLE_TIMER_CONF_WIDE_RAND +#define TRICKLE_TIMER_WIDE_RAND TRICKLE_TIMER_CONF_WIDE_RAND +#else +#define TRICKLE_TIMER_WIDE_RAND 1 +#endif +/*---------------------------------------------------------------------------*/ +/** + * \brief Selects a flavor for the 'Find maximum Imax' (max_imax) function. + * + * When configuring a new trickle timer, the library verifies that the (Imin , + * Imax) pair will fit in the platform's clock_time_t boundaries. If this is + * not the case, Imax will be adjusted down. In order to achieve this, we use + * an internal function which is a slight variant of a standard 'Count Leading + * Zeros'. + * + * This functionality is disabled when ::TRICKLE_TIMER_ERROR_CHECKING is 0 + * + * This define helps us generate, at the pre-processing stage, the desired + * version of this function. We start with a generic version by default. The + * platform's contiki-conf.h can change this to use the 16- or 32-bit specific + * flavor by defining TRICKLE_TIMER_CONF_MAX_IMAX_WIDTH. + * + * Depending on the toolchain, the generic variant may actually result in a + * smaller code size. Do your own experiments. + * + * TRICKLE_TIMER_MAX_IMAX_GENERIC (0): Generic function which will work + * regardless whether the platform uses a 16 or 32 bit wide clock type + * + * TRICKLE_TIMER_MAX_IMAX_16_BIT (1): You can select this in your + * contiki-conf.h if your platform's clock_time_t is 16 bits wide + * + * TRICKLE_TIMER_MAX_IMAX_32_BIT (2): You can select this in your + * contiki-conf.h if your platform's clock_time_t is 32 bits wide + */ +#ifdef TRICKLE_TIMER_CONF_MAX_IMAX_WIDTH +#define TRICKLE_TIMER_MAX_IMAX_WIDTH TRICKLE_TIMER_CONF_MAX_IMAX_WIDTH +#else +#define TRICKLE_TIMER_MAX_IMAX_WIDTH TRICKLE_TIMER_MAX_IMAX_GENERIC +#endif + +/** + * \brief Enables/Disables error checking + * + * 1: Enabled (default). The library checks the validity of Imin and Imax + * 0: Disabled. All error checking is turned off. This reduces code size. + */ +#ifdef TRICKLE_TIMER_CONF_ERROR_CHECKING +#define TRICKLE_TIMER_ERROR_CHECKING TRICKLE_TIMER_CONF_ERROR_CHECKING +#else +#define TRICKLE_TIMER_ERROR_CHECKING 1 +#endif +/*---------------------------------------------------------------------------*/ +/* Trickle Timer Library Macros */ +/*---------------------------------------------------------------------------*/ +/** + * \name Trickle Timer Library: Macros + * @{ + */ +/** + * \brief cross-platform method to get the maximum clock_time_t value + */ +#define TRICKLE_TIMER_CLOCK_MAX ((clock_time_t)~0) + + +/** + * \brief Checks if the trickle timer's suppression feature is enabled + * + * \param tt A pointer to a ::trickle_timer structure + * + * \retval non-zero Suppression is enabled + * \retval 0 Suppression is disabled + */ +#define TRICKLE_TIMER_SUPPRESSION_ENABLED(tt) \ + ((tt)->k != TRICKLE_TIMER_INFINITE_REDUNDANCY) + +/** + * \brief Checks if the trickle timer's suppression feature is disabled + * + * \param tt A pointer to a ::trickle_timer structure + * + * \retval non-zero Suppression is disabled + * \retval 0 Suppression is enabled + */ +#define TRICKLE_TIMER_SUPPRESSION_DISABLED(tt) \ + ((tt)->k == TRICKLE_TIMER_INFINITE_REDUNDANCY) + +/** + * \brief Determines whether the protocol must go ahead with a transmission + * + * \param tt A pointer to a ::trickle_timer structure + * + * \retval non-zero Go ahead with TX + * \retval 0 Suppress + */ +#define TRICKLE_TIMER_PROTO_TX_ALLOW(tt) \ + (TRICKLE_TIMER_SUPPRESSION_DISABLED(tt) || ((tt)->c < (tt)->k)) + +/** + * \brief Determines whether the protocol must suppress a transmission + * + * \param tt A pointer to a ::trickle_timer structure + * + * \retval non-zero Suppress + * \retval 0 Go ahead with TX + */ +#define TRICKLE_TIMER_PROTO_TX_SUPPRESS(tt) \ + (TRICKLE_TIMER_SUPPRESSION_ENABLED(tt) && ((tt)->c >= (tt)->k)) + +/** + * \brief Returns a timer's maximum interval size (Imin << Imax) as a number of + * clock ticks + * + * \param tt A pointer to a ::trickle_timer structure + * + * \return Maximum trickle interval length in clock ticks + */ +#define TRICKLE_TIMER_INTERVAL_MAX(tt) ((tt)->i_max_abs) + +/** + * \brief Returns the current trickle interval's end (absolute time in ticks) + * + * \param tt A pointer to a ::trickle_timer structure + * + * \return The absolute number of clock ticks when the current trickle interval + * will expire + */ +#define TRICKLE_TIMER_INTERVAL_END(tt) ((tt)->i_start + (tt)->i_cur) + +/** + * \brief Checks whether an Imin value is suitable considering the various + * restrictions imposed by our platform's clock as well as by the library itself + * + * \param imin An Imin value in clock ticks + * + * \retval 1 The Imin value is valid + * \retval 0 The Imin value is invalid + */ +#define TRICKLE_TIMER_IMIN_IS_OK(imin) \ + ((imin > 1) && (i_min <= (TRICKLE_TIMER_CLOCK_MAX >> 1))) + +/** + * \brief Checks whether an Imin value is invalid considering the various + * restrictions imposed by our platform's clock as well as by the library itself + * + * \param imin An Imin value in clock ticks + * + * \retval 1 The Imin value is invalid + * \retval 0 The Imin value is valid + */ +#define TRICKLE_TIMER_IMIN_IS_BAD(imin) \ + ((imin < 2) || (i_min > (TRICKLE_TIMER_CLOCK_MAX >> 1))) + +/** + * \brief Checks whether Imin << Imax is unsuitable considering the boundaries + * of our platform's clock_time_t + * + * \param i_min Imin value + * \param i_max Maximum number of doublings + * + * \retval non-zero The pair would exceed clock boundaries + * \retval 0 The pair is suitable for the platform + * + * Timers scheduled far in the future can be perceived as being scheduled in + * the past. + * Thus, we limit Imin << Imax to be LEQ(TRICKLE_TIMER_CLOCK_MAX >> 1) + 1 + */ +#define TRICKLE_TIMER_IPAIR_IS_BAD(i_min, i_max) \ + ((TRICKLE_TIMER_CLOCK_MAX >> (i_max + 1)) < i_min - 1) +/** @} */ +/*---------------------------------------------------------------------------*/ +/* Trickle Timer Library Data Representation */ +/*---------------------------------------------------------------------------*/ +/** + * \name Trickle Timer Library: Data Representation + * @{ + */ + +/** + * \brief typedef for a callback function to be defined in the protocol's + * implementation. + * + * Those callbaks are stored as a function pointer inside a ::trickle_timer + * structure and are called by the library at time t within the current trickle + * interval. + * + * Some protocols may rely on multiple trickle timers. For this reason, this + * function's argument will be an opaque pointer, aiming to help the protocol + * determine which timer triggered the call. + * + * The \e suppress argument is used so that the library can signal the protocol + * whether it should TX or suppress + */ +typedef void (* trickle_timer_cb_t)(void *ptr, uint8_t suppress); + +/** + * \struct trickle_timer + * + * A trickle timer. + * + * This structure is used for declaring a trickle timer. In order for the timer + * to start running, the protocol must first populate the structure's fields + * by calling trickle_timer_set(). Protocol implementations must NOT modify the + * contents of this structure directly. + * + * Protocol developers must also be careful to specify the values of Imin and + * Imax in such a way that the maximum interval size does not exceed the + * boundaries of clock_time_t + */ +struct trickle_timer { + clock_time_t i_min; /**< Imin: Clock ticks */ + clock_time_t i_cur; /**< I: Current interval in clock_ticks */ + clock_time_t i_start; /**< Start of this interval (absolute clock_time) */ + clock_time_t i_max_abs; /**< Maximum interval size in clock ticks (and not in + number of doublings). This is a cached value of + Imin << Imax used internally, so that we can + have direct access to the maximum interval size + without having to calculate it all the time */ + struct ctimer ct; /**< A \ref ctimer used internally */ + trickle_timer_cb_t cb; /**< Protocol's own callback, invoked at time t + within the current interval */ + void *cb_arg; /**< Opaque pointer to be used as the argument of the + protocol's callback */ + uint8_t i_max; /**< Imax: Max number of doublings */ + uint8_t k; /**< k: Redundancy Constant */ + uint8_t c; /**< c: Consistency Counter */ +}; +/** @} */ +/*---------------------------------------------------------------------------*/ +/* Trickle Timer Library Functions */ +/*---------------------------------------------------------------------------*/ +/** + * \name Trickle Timer Library: Functions called by protocol implementations + * @{ + */ + +/** + * \brief Configure a trickle timer + * \param tt A pointer to a ::trickle_timer structure + * \param i_min The timer's Imin configuration parameter, in units of + * clock_time_t + * \param i_max The timer's Imax configuration parameter (maximum number of + * doublings), specified as number of doublings + * \param k The timer's K (redundancy constant). If the value of K + * equals #TRICKLE_TIMER_INFINITE_REDUNDANCY, message + * suppression will be disabled + * \retval 0 Error (Bad argument) + * \retval non-zero Success. + * + * This function is used to set the initial configuration for a trickle timer. + * A trickle timer MUST be configured before the protocol calls + * trickle_timer_set(). + * + * If Imin<ct) + +/** + * \brief To be called by the protocol when it hears a consistent + * transmission + * \param tt A pointer to a ::trickle_timer structure + * + * When the trickle-based protocol hears a consistent transmission it must call + * this function to increment trickle's consistency counter, which is later + * used to determine whether the protocol must suppress or go ahead with its + * own transmissions. + * + * As the trickle timer library implementation may change in the future to + * perform further tasks upon reception of a consistent transmission, the + * protocol's implementation MUST use this call to increment the consistency + * counter instead of directly writing to the structure's field. + */ +void trickle_timer_consistency(struct trickle_timer *tt); + +/** + * \brief To be called by the protocol when it hears an inconsistent + * transmission + * \param tt A pointer to a ::trickle_timer structure + * + * When the protocol hears an inconsistent transmission, it must call this + * function to notify the library that the timer must be reset. + * + * Before resetting the timer, the library will perform a set of checks. + * Therefore, it is important that the protocol calls this function instead of + * trying to reset the timer by itself. + */ +void trickle_timer_inconsistency(struct trickle_timer *tt); + +/** + * \brief To be called by the protocol when an external event occurs that + * should trigger a timer reset + * \param tt A pointer to a ::trickle_timer structure + * + * When an external event occurs that should result in a timer reset, the + * protocol implementation must call this function to notify the library. + * + * Before resetting the timer, the library will perform a set of checks. + * Therefore, it is important that the protocol calls this function instead of + * trying to reset the timer by itself. + */ +#define trickle_timer_reset_event(tt) trickle_timer_inconsistency(tt) + +/** @} */ + +#endif /* __TRICKLE_TIMER_H__ */ +/** @} */ +/** @} */