trickle.h

00001 /*
00002  * Copyright (c) 2014-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 /*
00018  * trickle.h
00019  *
00020  * Implement a generic RFC 6206 Trickle Algorithm
00021  */
00022 
00023 #ifndef TRICKLE_H_
00024 #define TRICKLE_H_
00025 
00026 #include <ns_types.h>
00027 
00028 /* Trickle time is in arbitrary ticks - users can choose appropriate size
00029  * per algorithm implementation
00030  */
00031 typedef uint16_t trickle_time_t;
00032 
00033 #define TRICKLE_TIME_MAX    UINT16_MAX
00034 
00035 #define TRICKLE_EXPIRATIONS_INFINITE UINT8_MAX
00036 
00037 /* Public structure - fill in with your Trickle algorithm parameters */
00038 typedef struct trickle_params {
00039     trickle_time_t Imin;    /* minimum interval */
00040     trickle_time_t Imax;    /* maximum interval */
00041     uint8_t k;              /* redundancy constant (0 = infinity) */
00042     uint8_t TimerExpirations; /* MPL: expirations before terminating (0 = don't run, 0xFF = infinity) */
00043 }
00044 trickle_params_t;
00045 
00046 /* This structure is read-only for users. Initialised by trickle_start() */
00047 typedef struct trickle {
00048     uint8_t c;              /* counter */
00049     uint8_t e;              /* MPL: expiration events since the Trickle timer was last reset */
00050     trickle_time_t I;       /* current interval */
00051     trickle_time_t t;       /* potential transmission time */
00052     trickle_time_t now;     /* time counter */
00053 }
00054 trickle_t;
00055 
00056 /* RFC 6206 Rule 2 */
00057 void trickle_begin_interval(trickle_t *t);
00058 
00059 /* RFC 6206 Rule 1 */
00060 void trickle_start(trickle_t *t, const trickle_params_t *params);
00061 
00062 /* RFC 6206 Rule 3 */
00063 void trickle_consistent_heard(trickle_t *t);
00064 
00065 /* RFC 6206 Rule 6 */
00066 void trickle_inconsistent_heard(trickle_t *t, const trickle_params_t *params);
00067 
00068 /* Call to say some time has passed.
00069  *
00070  * Returns true if you should transmit now
00071  */
00072 bool trickle_timer(trickle_t *t, const trickle_params_t *params, uint16_t ticks);
00073 
00074 /* Indicate whether the timer is running (e < TimerExpirations) */
00075 bool trickle_running(const trickle_t *t, const trickle_params_t *params);
00076 
00077 /* Stop the timer (by setting e to infinite) */
00078 void trickle_stop(trickle_t *t);
00079 
00080 #endif /* TRICKLE_H_ */