Line data Source code
1 1 : /* 2 : * Copyright (c) 2015 Wind River Systems, Inc. 3 : * Copyright (c) 2019 Intel Corporation 4 : * 5 : * SPDX-License-Identifier: Apache-2.0 6 : */ 7 : 8 : /** 9 : * @file 10 : * @brief Timer driver API 11 : * 12 : * Declare API implemented by system timer driver and used by kernel components. 13 : */ 14 : 15 : #ifndef ZEPHYR_INCLUDE_DRIVERS_SYSTEM_TIMER_H_ 16 : #define ZEPHYR_INCLUDE_DRIVERS_SYSTEM_TIMER_H_ 17 : 18 : #include <stdbool.h> 19 : #include <zephyr/types.h> 20 : 21 : #ifdef __cplusplus 22 : extern "C" { 23 : #endif 24 : 25 : /** 26 : * @brief System Clock APIs 27 : * @defgroup clock_apis System Clock APIs 28 : * @{ 29 : */ 30 : 31 : /** 32 : * @brief Set system clock timeout 33 : * 34 : * Informs the system clock driver that the next needed call to 35 : * sys_clock_announce() will not be until the specified number of ticks 36 : * from the current time have elapsed. Note that spurious calls 37 : * to sys_clock_announce() are allowed (i.e. it's legal to announce 38 : * every tick and implement this function as a noop), the requirement 39 : * is that one tick announcement should occur within one tick BEFORE 40 : * the specified expiration (that is, passing ticks==1 means "announce 41 : * the next tick", this convention was chosen to match legacy usage). 42 : * Similarly a ticks value of zero (or even negative) is legal and 43 : * treated identically: it simply indicates the kernel would like the 44 : * next tick announcement as soon as possible. 45 : * 46 : * Note that ticks can also be passed the special value K_TICKS_FOREVER, 47 : * indicating that no future timer interrupts are expected or required 48 : * and that the system is permitted to enter an indefinite sleep even 49 : * if this could cause rollover of the internal counter (i.e. the 50 : * system uptime counter is allowed to be wrong 51 : * 52 : * Note also that it is conventional for the kernel to pass INT_MAX 53 : * for ticks if it wants to preserve the uptime tick count but doesn't 54 : * have a specific event to await. The intent here is that the driver 55 : * will schedule any needed timeout as far into the future as 56 : * possible. For the specific case of INT_MAX, the next call to 57 : * sys_clock_announce() may occur at any point in the future, not just 58 : * at INT_MAX ticks. But the correspondence between the announced 59 : * ticks and real-world time must be correct. 60 : * 61 : * A final note about SMP: note that the call to sys_clock_set_timeout() 62 : * is made on any CPU, and reflects the next timeout desired globally. 63 : * The resulting calls(s) to sys_clock_announce() must be properly 64 : * serialized by the driver such that a given tick is announced 65 : * exactly once across the system. The kernel does not (cannot, 66 : * really) attempt to serialize things by "assigning" timeouts to 67 : * specific CPUs. 68 : * 69 : * @param ticks Timeout in tick units 70 : * @param idle Hint to the driver that the system is about to enter 71 : * the idle state immediately after setting the timeout 72 : */ 73 1 : void sys_clock_set_timeout(int32_t ticks, bool idle); 74 : 75 : /** 76 : * @brief Timer idle exit notification 77 : * 78 : * This notifies the timer driver that the system is exiting the idle 79 : * and allows it to do whatever bookkeeping is needed to restore timer 80 : * operation and compute elapsed ticks. 81 : * 82 : * @note Legacy timer drivers also use this opportunity to call back 83 : * into sys_clock_announce() to notify the kernel of expired ticks. 84 : * This is allowed for compatibility, but not recommended. The kernel 85 : * will figure that out on its own. 86 : */ 87 1 : void sys_clock_idle_exit(void); 88 : 89 : /** 90 : * @brief Announce time progress to the kernel 91 : * 92 : * Informs the kernel that the specified number of ticks have elapsed 93 : * since the last call to sys_clock_announce() (or system startup for 94 : * the first call). The timer driver is expected to delivery these 95 : * announcements as close as practical (subject to hardware and 96 : * latency limitations) to tick boundaries. 97 : * 98 : * @param ticks Elapsed time, in ticks 99 : */ 100 1 : void sys_clock_announce(int32_t ticks); 101 : 102 : /** 103 : * @brief Ticks elapsed since last sys_clock_announce() call 104 : * 105 : * Queries the clock driver for the current time elapsed since the 106 : * last call to sys_clock_announce() was made. The kernel will call 107 : * this with appropriate locking, the driver needs only provide an 108 : * instantaneous answer. 109 : */ 110 1 : uint32_t sys_clock_elapsed(void); 111 : 112 : /** 113 : * @brief Disable system timer. 114 : * 115 : * @note Not all system timer drivers has the capability of being disabled. 116 : * The config @kconfig{CONFIG_SYSTEM_TIMER_HAS_DISABLE_SUPPORT} can be used to 117 : * check if the system timer has the capability of being disabled. 118 : */ 119 1 : void sys_clock_disable(void); 120 : 121 : /** 122 : * @brief Hardware cycle counter 123 : * 124 : * Timer drivers are generally responsible for the system cycle 125 : * counter as well as the tick announcements. This function is 126 : * generally called out of the architecture layer (@see 127 : * arch_k_cycle_get_32()) to implement the cycle counter, though the 128 : * user-facing API is owned by the architecture, not the driver. The 129 : * rate must match CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC. 130 : * 131 : * @note 132 : * If the counter clock is large enough for this to wrap its full range 133 : * within a few seconds (i.e. CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC is greater 134 : * than 50Mhz) then it is recommended to also implement 135 : * sys_clock_cycle_get_64(). 136 : * 137 : * @return The current cycle time. This should count up monotonically 138 : * through the full 32 bit space, wrapping at 0xffffffff. Hardware 139 : * with fewer bits of precision in the timer is expected to synthesize 140 : * a 32 bit count. 141 : */ 142 1 : uint32_t sys_clock_cycle_get_32(void); 143 : 144 : /** 145 : * @brief 64 bit hardware cycle counter 146 : * 147 : * As for sys_clock_cycle_get_32(), but with a 64 bit return value. 148 : * Not all hardware has 64 bit counters. This function need be 149 : * implemented only if CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER is set. 150 : * 151 : * @note 152 : * If the counter clock is large enough for sys_clock_cycle_get_32() to wrap 153 : * its full range within a few seconds (i.e. CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC 154 : * is greater than 50Mhz) then it is recommended to implement this API. 155 : * 156 : * @return The current cycle time. This should count up monotonically 157 : * through the full 64 bit space, wrapping at 2^64-1. Hardware with 158 : * fewer bits of precision in the timer is generally not expected to 159 : * implement this API. 160 : */ 161 1 : uint64_t sys_clock_cycle_get_64(void); 162 : 163 : /** 164 : * @} 165 : */ 166 : 167 : #ifdef __cplusplus 168 : } 169 : #endif 170 : 171 : #endif /* ZEPHYR_INCLUDE_DRIVERS_SYSTEM_TIMER_H_ */
