blob: 7e3e22f2c49b0dee5b69da4c6e81d8727e0515d2 [file] [log] [blame]
/** @file
* @brief Network timer with wrap around
*
* Timer that runs longer than about 49 days needs to calculate wraps.
*/
/*
* Copyright (c) 2018 Intel Corporation
* Copyright (c) 2020 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_
#define ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_
/**
* @brief Network long timeout primitives and helpers
* @defgroup net_timeout Network long timeout primitives and helpers
* @ingroup networking
* @{
*/
#include <string.h>
#include <stdbool.h>
#include <limits.h>
#include <zephyr/types.h>
#include <sys/slist.h>
#ifdef __cplusplus
extern "C" {
#endif
/** @brief Divisor used to support ms resolution timeouts.
*
* Because delays are processed in work queues which are not invoked
* synchronously with clock changes we need to be able to detect timeouts
* after they occur, which requires comparing "deadline" to "now" with enough
* "slop" to handle any observable latency due to "now" advancing past
* "deadline".
*
* The simplest solution is to use the native conversion of the well-defined
* 32-bit unsigned difference to a 32-bit signed difference, which caps the
* maximum delay at INT32_MAX. This is compatible with the standard mechanism
* for detecting completion of deadlines that do not overflow their
* representation.
*/
#define NET_TIMEOUT_MAX_VALUE ((uint32_t)INT32_MAX)
/** Generic struct for handling network timeouts.
*
* Except for the linking node, all access to state from these objects must go
* through the defined API.
*/
struct net_timeout {
/** Used to link multiple timeouts that share a common timer infrastructure.
*
* For examples a set of related timers may use a single delayed work
* structure, which is always scheduled at the shortest time to a
* timeout event.
*/
sys_snode_t node;
/* Time at which the timer was last set.
*
* This usually corresponds to the low 32 bits of k_uptime_get(). */
uint32_t timer_start;
/* Portion of remaining timeout that does not exceed
* NET_TIMEOUT_MAX_VALUE.
*
* This value is updated in parallel with timer_start and wrap_counter
* by net_timeout_evaluate().
*/
uint32_t timer_timeout;
/* Timer wrap count.
*
* This tracks multiples of NET_TIMEOUT_MAX_VALUE milliseconds that
* have yet to pass. It is also updated along with timer_start and
* wrap_counter by net_timeout_evaluate().
*/
uint32_t wrap_counter;
};
/** @brief Configure a network timeout structure.
*
* @param timeout a pointer to the timeout state.
*
* @param lifetime the duration of the timeout in seconds.
*
* @param now the time at which the timeout started counting down, in
* milliseconds. This is generally a captured value of k_uptime_get_32().
*/
void net_timeout_set(struct net_timeout *timeout,
uint32_t lifetime,
uint32_t now);
/** @brief Return the 64-bit system time at which the timeout will complete.
*
* @note Correct behavior requires invocation of net_timeout_evaluate() at its
* specified intervals.
*
* @param timeout state a pointer to the timeout state, initialized by
* net_timeout_set() and maintained by net_timeout_evaluate().
*
* @param now the full-precision value of k_uptime_get() relative to which the
* deadline will be calculated.
*
* @return the value of k_uptime_get() at which the timeout will expire.
*/
int64_t net_timeout_deadline(const struct net_timeout *timeout,
int64_t now);
/** @brief Calculate the remaining time to the timeout in whole seconds.
*
* @note This function rounds the remaining time down, i.e. if the timeout
* will occur in 3500 milliseconds the value 3 will be returned.
*
* @note Correct behavior requires invocation of net_timeout_evaluate() at its
* specified intervals.
*
* @param timeout a pointer to the timeout state
*
* @param now the time relative to which the estimate of remaining time should
* be calculated. This should be recently captured value from
* k_uptime_get_32().
*
* @retval 0 if the timeout has completed.
* @retval positive the remaining duration of the timeout, in seconds.
*/
uint32_t net_timeout_remaining(const struct net_timeout *timeout,
uint32_t now);
/** @brief Update state to reflect elapsed time and get new delay.
*
* This function must be invoked periodically to (1) apply the effect of
* elapsed time on what remains of a total delay that exceeded the maximum
* representable delay, and (2) determine that either the timeout has
* completed or that the infrastructure must wait a certain period before
* checking again for completion.
*
* @param timeout a pointer to the timeout state
*
* @param now the time relative to which the estimate of remaining time should
* be calculated. This should be recently captured value from
* k_uptime_get_32().
*
* @retval 0 if the timeout has completed
* @retval positive the maximum delay until the state of this timeout should
* be re-evaluated, in milliseconds.
*/
uint32_t net_timeout_evaluate(struct net_timeout *timeout,
uint32_t now);
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_ */