Line data Source code
1 0 : /* 2 : * Copyright (c) 2016-2020 Nordic Semiconductor ASA 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : #ifndef ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_RTC_TIMER_H 8 : #define ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_RTC_TIMER_H 9 : 10 : #include <zephyr/sys_clock.h> 11 : 12 : #ifdef __cplusplus 13 : extern "C" { 14 : #endif 15 : 16 : /** @brief Maximum allowed time span that is considered to be in the future. 17 : */ 18 1 : #define NRF_RTC_TIMER_MAX_SCHEDULE_SPAN BIT(23) 19 : 20 : /** @brief RTC timer compare event handler. 21 : * 22 : * Called from RTC ISR context when processing a compare event. 23 : * 24 : * @param id Compare channel ID. 25 : * 26 : * @param expire_time An actual absolute expiration time set for a compare 27 : * channel. It can differ from the requested target time 28 : * and the difference can be used to determine whether the 29 : * time set was delayed. 30 : * 31 : * @param user_data Pointer to a user context data. 32 : */ 33 : typedef void (*z_nrf_rtc_timer_compare_handler_t)(int32_t id, 34 : uint64_t expire_time, 35 : void *user_data); 36 : 37 : /** @brief Allocate RTC compare channel. 38 : * 39 : * Channel 0 is used for the system clock. 40 : * 41 : * @retval Non-negative indicates allocated channel ID. 42 : * @retval -ENOMEM if channel cannot be allocated. 43 : */ 44 : int32_t z_nrf_rtc_timer_chan_alloc(void); 45 : 46 : /** @brief Free RTC compare channel. 47 : * 48 : * @param chan Previously allocated channel ID. 49 : */ 50 : void z_nrf_rtc_timer_chan_free(int32_t chan); 51 : 52 : /** @brief Read current absolute time. 53 : * 54 : * @return Current absolute time. 55 : */ 56 : uint64_t z_nrf_rtc_timer_read(void); 57 : 58 : /** @brief Get COMPARE event register address. 59 : * 60 : * Address can be used for (D)PPI. 61 : * 62 : * @param chan Channel ID between 0 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 63 : * 64 : * @return Register address. 65 : */ 66 : uint32_t z_nrf_rtc_timer_compare_evt_address_get(int32_t chan); 67 : 68 : /** @brief Get CAPTURE task register address. 69 : * 70 : * Address can be used for (D)PPI. 71 : * 72 : * @note Not all platforms have CAPTURE task. 73 : * 74 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 75 : * 76 : * @return Register address. 77 : */ 78 : uint32_t z_nrf_rtc_timer_capture_task_address_get(int32_t chan); 79 : 80 : /** @brief Safely disable compare event interrupt. 81 : * 82 : * Function returns key indicating whether interrupt was already disabled. 83 : * 84 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 85 : * 86 : * @return key passed to @ref z_nrf_rtc_timer_compare_int_unlock. 87 : */ 88 : bool z_nrf_rtc_timer_compare_int_lock(int32_t chan); 89 : 90 : /** @brief Safely enable compare event interrupt. 91 : * 92 : * Event interrupt is conditionally enabled based on @p key. 93 : * 94 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 95 : * 96 : * @param key Key returned by @ref z_nrf_rtc_timer_compare_int_lock. 97 : */ 98 : void z_nrf_rtc_timer_compare_int_unlock(int32_t chan, bool key); 99 : 100 : /** @brief Read compare register value. 101 : * 102 : * @param chan Channel ID between 0 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 103 : * 104 : * @return Value set in the compare register. 105 : */ 106 : uint32_t z_nrf_rtc_timer_compare_read(int32_t chan); 107 : 108 : /** @brief Try to set compare channel to given value. 109 : * 110 : * Provided value is absolute and cannot be further in the future than 111 : * @c NRF_RTC_TIMER_MAX_SCHEDULE_SPAN. If given value is in the past then an RTC 112 : * interrupt is triggered immediately. Otherwise function continuously retries 113 : * to set compare register until value that is written is far enough in the 114 : * future and will generate an event. Because of that, compare register value 115 : * may be different than the one requested. During this operation interrupt 116 : * from that compare channel is disabled. Other interrupts are not locked during 117 : * this operation. 118 : * 119 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 120 : * 121 : * @param target_time Absolute target time in ticks. 122 : * 123 : * @param handler User function called in the context of the RTC interrupt. 124 : * 125 : * @param user_data Data passed to the handler. 126 : * 127 : * @retval 0 if the compare channel was set successfully. 128 : * @retval -EINVAL if provided target time was further than 129 : * @c NRF_RTC_TIMER_MAX_SCHEDULE_SPAN ticks in the future. 130 : * 131 : * @sa @ref z_nrf_rtc_timer_exact_set 132 : */ 133 : int z_nrf_rtc_timer_set(int32_t chan, uint64_t target_time, 134 : z_nrf_rtc_timer_compare_handler_t handler, 135 : void *user_data); 136 : 137 : /** @brief Try to set compare channel exactly to given value. 138 : * 139 : * @note This function is similar to @ref z_nrf_rtc_timer_set, but the compare 140 : * channel will be set to expected value only when it can be guaranteed that 141 : * the hardware event will be generated exactly at expected @c target_time in 142 : * the future. If the @c target_time is in the past or so close in the future 143 : * that the reliable generation of event would require adjustment of compare 144 : * value (as would @ref z_nrf_rtc_timer_set function do), neither the hardware 145 : * event nor interrupt will be generated and the function fails. 146 : * 147 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 148 : * 149 : * @param target_time Absolute target time in ticks. 150 : * 151 : * @param handler User function called in the context of the RTC interrupt. 152 : * 153 : * @param user_data Data passed to the handler. 154 : * 155 : * @retval 0 if the compare channel was set successfully. 156 : * @retval -EINVAL if provided target time was further than 157 : * @c NRF_RTC_TIMER_MAX_SCHEDULE_SPAN ticks in the future 158 : * or the target time is in the past or is so close in the future that 159 : * event generation could not be guaranteed without adjusting 160 : * compare value of that channel. 161 : */ 162 : int z_nrf_rtc_timer_exact_set(int32_t chan, uint64_t target_time, 163 : z_nrf_rtc_timer_compare_handler_t handler, 164 : void *user_data); 165 : 166 : /** @brief Abort a timer requested with @ref z_nrf_rtc_timer_set. 167 : * 168 : * If an abort operation is performed too late it is still possible for an event 169 : * to fire. The user can detect a spurious event by comparing absolute time 170 : * provided in callback and a result of @ref z_nrf_rtc_timer_read. During this 171 : * operation interrupt from that compare channel is disabled. Other interrupts 172 : * are not locked during this operation. 173 : * 174 : * @param chan Channel ID between 1 and @kconfig{CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT}. 175 : */ 176 : void z_nrf_rtc_timer_abort(int32_t chan); 177 : 178 : /** @brief Convert system clock time to RTC ticks. 179 : * 180 : * @p t can be absolute or relative. @p t cannot be further into the future 181 : * from now than the RTC range (e.g. 512 seconds if RTC is running at 32768 Hz). 182 : * 183 : * @retval Positive value represents @p t in RTC tick value. 184 : * @retval -EINVAL if @p t is out of range. 185 : */ 186 : uint64_t z_nrf_rtc_timer_get_ticks(k_timeout_t t); 187 : 188 : /** @brief Get offset between nrf53 network cpu system clock and application cpu 189 : * system clock. 190 : * 191 : * Returned value added to the current system tick on network cpu gives current 192 : * application cpu system tick. Function can only be used on network cpu. It 193 : * requires @kconfig{CONFIG_NRF53_SYNC_RTC} being enabled. 194 : * 195 : * @retval Non-negative offset given in RTC ticks. 196 : * @retval -ENOSYS if operation is not supported. 197 : * @retval -EBUSY if synchronization is not yet completed. 198 : */ 199 : int z_nrf_rtc_timer_nrf53net_offset_get(void); 200 : 201 : /** @brief Move RTC counter forward using TRIGOVRFLW hardware feature. 202 : * 203 : * RTC has a hardware feature which can force counter to jump to 0xFFFFF0 value 204 : * which is close to overflow. Function is using this feature and updates 205 : * driver internal to perform time shift to the future. Operation can only be 206 : * performed when there are no active alarms set. It should be used for testing 207 : * only. 208 : * 209 : * @retval 0 on successful shift. 210 : * @retval -EBUSY if there are active alarms. 211 : * @retval -EAGAIN if current counter value is too close to overflow. 212 : * @retval -ENOTSUP if option is disabled in Kconfig or additional channels are enabled. 213 : */ 214 : int z_nrf_rtc_timer_trigger_overflow(void); 215 : 216 : #ifdef __cplusplus 217 : } 218 : #endif 219 : 220 : #endif /* ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_RTC_TIMER_H */
