1 /* 2 * Copyright (c) 2014-2015 Wind River Systems, Inc. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief Variables needed for system clock 10 * 11 * 12 * Declare variables used by both system timer device driver and kernel 13 * components that use timer functionality. 14 */ 15 16 #ifndef ZEPHYR_INCLUDE_SYS_CLOCK_H_ 17 #define ZEPHYR_INCLUDE_SYS_CLOCK_H_ 18 19 #include <zephyr/sys/util.h> 20 #include <zephyr/sys/dlist.h> 21 22 #include <zephyr/toolchain.h> 23 #include <zephyr/types.h> 24 25 #include <zephyr/sys/time_units.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * @addtogroup clock_apis 33 * @{ 34 */ 35 36 /** 37 * @brief Tick precision used in timeout APIs 38 * 39 * This type defines the word size of the timeout values used in 40 * k_timeout_t objects, and thus defines an upper bound on maximum 41 * timeout length (or equivalently minimum tick duration). Note that 42 * this does not affect the size of the system uptime counter, which 43 * is always a 64 bit count of ticks. 44 */ 45 #ifdef CONFIG_TIMEOUT_64BIT 46 typedef int64_t k_ticks_t; 47 #else 48 typedef uint32_t k_ticks_t; 49 #endif 50 51 #define K_TICKS_FOREVER ((k_ticks_t) -1) 52 53 /** 54 * @brief Kernel timeout type 55 * 56 * Timeout arguments presented to kernel APIs are stored in this 57 * opaque type, which is capable of representing times in various 58 * formats and units. It should be constructed from application data 59 * using one of the macros defined for this purpose (e.g. `K_MSEC()`, 60 * `K_TIMEOUT_ABS_TICKS()`, etc...), or be one of the two constants 61 * K_NO_WAIT or K_FOREVER. Applications should not inspect the 62 * internal data once constructed. Timeout values may be compared for 63 * equality with the `K_TIMEOUT_EQ()` macro. 64 */ 65 typedef struct { 66 k_ticks_t ticks; 67 } k_timeout_t; 68 69 /** 70 * @brief Compare timeouts for equality 71 * 72 * The k_timeout_t object is an opaque struct that should not be 73 * inspected by application code. This macro exists so that users can 74 * test timeout objects for equality with known constants 75 * (e.g. K_NO_WAIT and K_FOREVER) when implementing their own APIs in 76 * terms of Zephyr timeout constants. 77 * 78 * @return True if the timeout objects are identical 79 */ 80 #define K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks) 81 82 #define Z_TIMEOUT_NO_WAIT ((k_timeout_t) {0}) 83 #if defined(__cplusplus) && ((__cplusplus - 0) < 202002L) 84 #define Z_TIMEOUT_TICKS(t) ((k_timeout_t) { (t) }) 85 #else 86 #define Z_TIMEOUT_TICKS(t) ((k_timeout_t) { .ticks = (t) }) 87 #endif 88 #define Z_FOREVER Z_TIMEOUT_TICKS(K_TICKS_FOREVER) 89 90 #ifdef CONFIG_TIMEOUT_64BIT 91 # define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil64(MAX(t, 0))) 92 # define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil64(MAX(t, 0))) 93 # define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil64(MAX(t, 0))) 94 # define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil64(MAX(t, 0))) 95 #else 96 # define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil32(MAX(t, 0))) 97 # define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil32(MAX(t, 0))) 98 # define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil32(MAX(t, 0))) 99 # define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil32(MAX(t, 0))) 100 #endif 101 102 /* Converts between absolute timeout expiration values (packed into 103 * the negative space below K_TICKS_FOREVER) and (non-negative) delta 104 * timeout values. If the result of Z_TICK_ABS(t) is >= 0, then the 105 * value was an absolute timeout with the returned expiration time. 106 * Note that this macro is bidirectional: Z_TICK_ABS(Z_TICK_ABS(t)) == 107 * t for all inputs, and that the representation of K_TICKS_FOREVER is 108 * the same value in both spaces! Clever, huh? 109 */ 110 #define Z_TICK_ABS(t) (K_TICKS_FOREVER - 1 - (t)) 111 112 /** @} */ 113 114 #ifdef CONFIG_TICKLESS_KERNEL 115 extern void z_enable_sys_clock(void); 116 #endif 117 118 #if defined(CONFIG_SYS_CLOCK_EXISTS) && \ 119 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0) 120 #error "SYS_CLOCK_HW_CYCLES_PER_SEC must be non-zero!" 121 #endif 122 123 /* number of nsec per usec */ 124 #define NSEC_PER_USEC 1000U 125 126 /* number of nsec per msec */ 127 #define NSEC_PER_MSEC 1000000U 128 129 /* number of microseconds per millisecond */ 130 #define USEC_PER_MSEC 1000U 131 132 /* number of milliseconds per second */ 133 #define MSEC_PER_SEC 1000U 134 135 /* number of microseconds per second */ 136 #define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC)) 137 138 /* number of nanoseconds per second */ 139 #define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC)) 140 141 142 /* kernel clocks */ 143 144 /* 145 * We default to using 64-bit intermediates in timescale conversions, 146 * but if the HW timer cycles/sec, ticks/sec and ms/sec are all known 147 * to be nicely related, then we can cheat with 32 bits instead. 148 */ 149 150 #ifdef CONFIG_SYS_CLOCK_EXISTS 151 152 #if defined(CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME) || \ 153 (MSEC_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) || \ 154 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) 155 #define _NEED_PRECISE_TICK_MS_CONVERSION 156 #endif 157 158 #endif 159 160 /* added tick needed to account for tick in progress */ 161 #define _TICK_ALIGN 1 162 163 /* 164 * SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds 165 * and calculates the average cycle time 166 */ 167 #define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) \ 168 (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES) 169 170 /** 171 * 172 * @brief Return the lower part of the current system tick count 173 * 174 * @return the current system tick count 175 * 176 */ 177 uint32_t sys_clock_tick_get_32(void); 178 179 /** 180 * 181 * @brief Return the current system tick count 182 * 183 * @return the current system tick count 184 * 185 */ 186 int64_t sys_clock_tick_get(void); 187 188 #ifndef CONFIG_SYS_CLOCK_EXISTS 189 #define sys_clock_tick_get() (0) 190 #define sys_clock_tick_get_32() (0) 191 #endif 192 193 uint64_t sys_clock_timeout_end_calc(k_timeout_t timeout); 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */ 200
