Line data Source code
1 1 : /** @file 2 : * @brief Network timer with wrap around 3 : * 4 : * Timer that runs longer than about 49 days needs to calculate wraps. 5 : */ 6 : 7 : /* 8 : * Copyright (c) 2018 Intel Corporation 9 : * Copyright (c) 2020 Nordic Semiconductor ASA 10 : * 11 : * SPDX-License-Identifier: Apache-2.0 12 : */ 13 : 14 : #ifndef ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_ 15 : #define ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_ 16 : 17 : /** 18 : * @brief Network long timeout primitives and helpers 19 : * @defgroup net_timeout Network long timeout primitives and helpers 20 : * @since 1.14 21 : * @version 0.8.0 22 : * @ingroup networking 23 : * @{ 24 : */ 25 : 26 : #include <string.h> 27 : #include <stdbool.h> 28 : #include <limits.h> 29 : #include <zephyr/types.h> 30 : #include <zephyr/sys/slist.h> 31 : 32 : #ifdef __cplusplus 33 : extern "C" { 34 : #endif 35 : 36 : /** @brief Divisor used to support ms resolution timeouts. 37 : * 38 : * Because delays are processed in work queues which are not invoked 39 : * synchronously with clock changes we need to be able to detect timeouts 40 : * after they occur, which requires comparing "deadline" to "now" with enough 41 : * "slop" to handle any observable latency due to "now" advancing past 42 : * "deadline". 43 : * 44 : * The simplest solution is to use the native conversion of the well-defined 45 : * 32-bit unsigned difference to a 32-bit signed difference, which caps the 46 : * maximum delay at INT32_MAX. This is compatible with the standard mechanism 47 : * for detecting completion of deadlines that do not overflow their 48 : * representation. 49 : */ 50 1 : #define NET_TIMEOUT_MAX_VALUE ((uint32_t)INT32_MAX) 51 : 52 : /** Generic struct for handling network timeouts. 53 : * 54 : * Except for the linking node, all access to state from these objects must go 55 : * through the defined API. 56 : */ 57 1 : struct net_timeout { 58 : /** Used to link multiple timeouts that share a common timer infrastructure. 59 : * 60 : * For examples a set of related timers may use a single delayed work 61 : * structure, which is always scheduled at the shortest time to a 62 : * timeout event. 63 : */ 64 1 : sys_snode_t node; 65 : 66 : /** Time at which the timer was last set. 67 : * 68 : * This usually corresponds to the low 32 bits of k_uptime_get(). 69 : */ 70 1 : uint32_t timer_start; 71 : 72 : /** Portion of remaining timeout that does not exceed 73 : * NET_TIMEOUT_MAX_VALUE. 74 : * 75 : * This value is updated in parallel with timer_start and wrap_counter 76 : * by net_timeout_evaluate(). 77 : */ 78 1 : uint32_t timer_timeout; 79 : 80 : /** Timer wrap count. 81 : * 82 : * This tracks multiples of NET_TIMEOUT_MAX_VALUE milliseconds that 83 : * have yet to pass. It is also updated along with timer_start and 84 : * wrap_counter by net_timeout_evaluate(). 85 : */ 86 1 : uint32_t wrap_counter; 87 : }; 88 : 89 : /** @brief Configure a network timeout structure. 90 : * 91 : * @param timeout a pointer to the timeout state. 92 : * 93 : * @param lifetime the duration of the timeout in seconds. 94 : * 95 : * @param now the time at which the timeout started counting down, in 96 : * milliseconds. This is generally a captured value of k_uptime_get_32(). 97 : */ 98 1 : void net_timeout_set(struct net_timeout *timeout, 99 : uint32_t lifetime, 100 : uint32_t now); 101 : 102 : /** @brief Return the 64-bit system time at which the timeout will complete. 103 : * 104 : * @note Correct behavior requires invocation of net_timeout_evaluate() at its 105 : * specified intervals. 106 : * 107 : * @param timeout state a pointer to the timeout state, initialized by 108 : * net_timeout_set() and maintained by net_timeout_evaluate(). 109 : * 110 : * @param now the full-precision value of k_uptime_get() relative to which the 111 : * deadline will be calculated. 112 : * 113 : * @return the value of k_uptime_get() at which the timeout will expire. 114 : */ 115 1 : int64_t net_timeout_deadline(const struct net_timeout *timeout, 116 : int64_t now); 117 : 118 : /** @brief Calculate the remaining time to the timeout in whole seconds. 119 : * 120 : * @note This function rounds the remaining time down, i.e. if the timeout 121 : * will occur in 3500 milliseconds the value 3 will be returned. 122 : * 123 : * @note Correct behavior requires invocation of net_timeout_evaluate() at its 124 : * specified intervals. 125 : * 126 : * @param timeout a pointer to the timeout state 127 : * 128 : * @param now the time relative to which the estimate of remaining time should 129 : * be calculated. This should be recently captured value from 130 : * k_uptime_get_32(). 131 : * 132 : * @retval 0 if the timeout has completed. 133 : * @retval positive the remaining duration of the timeout, in seconds. 134 : */ 135 1 : uint32_t net_timeout_remaining(const struct net_timeout *timeout, 136 : uint32_t now); 137 : 138 : /** @brief Update state to reflect elapsed time and get new delay. 139 : * 140 : * This function must be invoked periodically to (1) apply the effect of 141 : * elapsed time on what remains of a total delay that exceeded the maximum 142 : * representable delay, and (2) determine that either the timeout has 143 : * completed or that the infrastructure must wait a certain period before 144 : * checking again for completion. 145 : * 146 : * @param timeout a pointer to the timeout state 147 : * 148 : * @param now the time relative to which the estimate of remaining time should 149 : * be calculated. This should be recently captured value from 150 : * k_uptime_get_32(). 151 : * 152 : * @retval 0 if the timeout has completed 153 : * @retval positive the maximum delay until the state of this timeout should 154 : * be re-evaluated, in milliseconds. 155 : */ 156 1 : uint32_t net_timeout_evaluate(struct net_timeout *timeout, 157 : uint32_t now); 158 : 159 : #ifdef __cplusplus 160 : } 161 : #endif 162 : 163 : /** 164 : * @} 165 : */ 166 : 167 : 168 : #endif /* ZEPHYR_INCLUDE_NET_NET_TIMEOUT_H_ */
