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 <sys/util.h>
20 #include <sys/dlist.h>
21 
22 #include <toolchain.h>
23 #include <zephyr/types.h>
24 
25 #include <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) {})
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 returend 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 microseconds per millisecond */
127 #define USEC_PER_MSEC 1000U
128 
129 /* number of milliseconds per second */
130 #define MSEC_PER_SEC 1000U
131 
132 /* number of microseconds per second */
133 #define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC))
134 
135 /* number of nanoseconds per second */
136 #define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))
137 
138 
139 /* kernel clocks */
140 
141 /*
142  * We default to using 64-bit intermediates in timescale conversions,
143  * but if the HW timer cycles/sec, ticks/sec and ms/sec are all known
144  * to be nicely related, then we can cheat with 32 bits instead.
145  */
146 
147 #ifdef CONFIG_SYS_CLOCK_EXISTS
148 
149 #if defined(CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME) || \
150 	(MSEC_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) || \
151 	(CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC)
152 #define _NEED_PRECISE_TICK_MS_CONVERSION
153 #endif
154 
155 #endif
156 
157 /* added tick needed to account for tick in progress */
158 #define _TICK_ALIGN 1
159 
160 /*
161  * SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds
162  * and calculates the average cycle time
163  */
164 #define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) \
165 	(uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)
166 
167 /**
168  *
169  * @brief Return the lower part of the current system tick count
170  *
171  * @return the current system tick count
172  *
173  */
174 uint32_t sys_clock_tick_get_32(void);
175 
176 /**
177  *
178  * @brief Return the current system tick count
179  *
180  * @return the current system tick count
181  *
182  */
183 int64_t sys_clock_tick_get(void);
184 
185 #ifndef CONFIG_SYS_CLOCK_EXISTS
186 #define sys_clock_tick_get() (0)
187 #define sys_clock_tick_get_32() (0)
188 #endif
189 
190 uint64_t sys_clock_timeout_end_calc(k_timeout_t timeout);
191 
192 #ifdef __cplusplus
193 }
194 #endif
195 
196 #endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */
197