Line data Source code
1 0 : /*
2 : * Copyright (c) 2024 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H
8 : #define ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H
9 :
10 : #ifdef __cplusplus
11 : extern "C" {
12 : #endif
13 :
14 : #include <zephyr/sys_clock.h>
15 :
16 : /** @brief GRTC timer compare event handler.
17 : *
18 : * Called from GRTC ISR context when processing a compare event.
19 : *
20 : * @param id Compare channel ID.
21 : *
22 : * @param expire_time An actual absolute expiration time set for a compare
23 : * channel. It can differ from the requested target time
24 : * and the difference can be used to determine whether the
25 : * time set was delayed.
26 : *
27 : * @param user_data Pointer to a user context data.
28 : */
29 : typedef void (*z_nrf_grtc_timer_compare_handler_t)(int32_t id, uint64_t expire_time,
30 : void *user_data);
31 :
32 : /** @brief Allocate GRTC capture/compare channel.
33 : *
34 : * @retval >=0 Non-negative indicates allocated channel ID.
35 : * @retval -ENOMEM if channel cannot be allocated.
36 : */
37 : int32_t z_nrf_grtc_timer_chan_alloc(void);
38 :
39 : /** @brief Free GRTC capture/compare channel.
40 : *
41 : * @param chan Previously allocated channel ID.
42 : */
43 : void z_nrf_grtc_timer_chan_free(int32_t chan);
44 :
45 : /** @brief Read current absolute time.
46 : *
47 : * @return Current absolute time.
48 : */
49 : uint64_t z_nrf_grtc_timer_read(void);
50 :
51 : /** @brief Check COMPARE event state.
52 : *
53 : * @param chan Channel ID.
54 : *
55 : * @retval true The event has been generated.
56 : * @retval false The event has not been generated.
57 : */
58 : bool z_nrf_grtc_timer_compare_evt_check(int32_t chan);
59 :
60 : /** @brief Get COMPARE event register address.
61 : *
62 : * Address can be used for DPPIC.
63 : *
64 : * @param chan Channel ID.
65 : *
66 : * @return Register address.
67 : */
68 : uint32_t z_nrf_grtc_timer_compare_evt_address_get(int32_t chan);
69 :
70 : /** @brief Get CAPTURE task register address.
71 : *
72 : * Address can be used for DPPIC.
73 : *
74 : * @param chan Channel ID.
75 : *
76 : * @return Register address.
77 : */
78 : uint32_t z_nrf_grtc_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.
85 : *
86 : * @return key passed to z_nrf_grtc_timer_compare_int_unlock().
87 : */
88 : bool z_nrf_grtc_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.
95 : *
96 : * @param key Key returned by z_nrf_grtc_timer_compare_int_lock().
97 : */
98 : void z_nrf_grtc_timer_compare_int_unlock(int32_t chan, bool key);
99 :
100 : /** @brief Read compare register value.
101 : *
102 : * @param chan Channel ID.
103 : *
104 : * @param val Pointer to store the value.
105 : *
106 : * @retval 0 if the compare register was read successfully.
107 : * @retval -EAGAIN if compare for given channel is not set.
108 : * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running.
109 : */
110 : int z_nrf_grtc_timer_compare_read(int32_t chan, uint64_t *val);
111 :
112 : /** @brief Set compare channel to given value.
113 : *
114 : * @param chan Channel ID.
115 : *
116 : * @param target_time Absolute target time in GRTC ticks.
117 : *
118 : * @param handler User function called in the context of the GRTC interrupt.
119 : *
120 : * @param user_data Data passed to the handler.
121 : *
122 : * @retval 0 if the compare channel was set successfully.
123 : * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running.
124 : */
125 : int z_nrf_grtc_timer_set(int32_t chan, uint64_t target_time,
126 : z_nrf_grtc_timer_compare_handler_t handler, void *user_data);
127 :
128 : /** @brief Abort a timer requested with z_nrf_grtc_timer_set().
129 : *
130 : * If an abort operation is performed too late it is still possible for an event
131 : * to fire. The user can detect a spurious event by comparing absolute time
132 : * provided in callback and a result of z_nrf_grtc_timer_read(). During this
133 : * operation interrupt from that compare channel is disabled. Other interrupts
134 : * are not locked during this operation.
135 : *
136 : * @param chan Channel ID between 1 and CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT.
137 : */
138 : void z_nrf_grtc_timer_abort(int32_t chan);
139 :
140 : /** @brief Convert system clock time to GRTC ticks.
141 : *
142 : * @p t can be absolute or relative.
143 : *
144 : * @retval >=0 Positive value represents @p t in GRTC tick value.
145 : * @retval -EINVAL if @p t is out of range.
146 : */
147 : uint64_t z_nrf_grtc_timer_get_ticks(k_timeout_t t);
148 :
149 : /** @brief Prepare channel for timestamp capture.
150 : *
151 : * Use z_nrf_grtc_timer_capture_task_address_get() to determine the register
152 : * address that is used to trigger capture.
153 : *
154 : * @note Capture and compare are mutually exclusive features - they cannot be
155 : * used simultaneously on the same GRTC channel.
156 : *
157 : * @param chan Channel ID.
158 : *
159 : * @retval 0 if the channel was successfully prepared.
160 : * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running.
161 : */
162 : int z_nrf_grtc_timer_capture_prepare(int32_t chan);
163 :
164 : /** @brief Read timestamp value captured on the channel.
165 : *
166 : * The @p chan must be prepared using z_nrf_grtc_timer_capture_prepare().
167 : *
168 : * @param chan Channel ID.
169 : *
170 : * @param captured_time Pointer to store the value.
171 : *
172 : * @retval 0 if the timestamp was successfully caught and read.
173 : * @retval -EBUSY if capturing has not been triggered.
174 : * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running.
175 : */
176 : int z_nrf_grtc_timer_capture_read(int32_t chan, uint64_t *captured_time);
177 :
178 : /** @brief Prepare GRTC as a source of wake up event and set the wake up time.
179 : *
180 : * @note Calling this function should be immediately followed by low-power mode enter
181 : * (if it executed successfully).
182 : *
183 : * @param wake_time_us Relative wake up time in microseconds.
184 : *
185 : * @retval 0 if wake up time was successfully set.
186 : * @retval -EPERM if the SYSCOUNTER is not running.
187 : * @retval -ENOMEM if no available GRTC channels were found.
188 : * @retval -EINVAL if @p wake_time_us is too low.
189 : */
190 : int z_nrf_grtc_wakeup_prepare(uint64_t wake_time_us);
191 :
192 : /** @brief Get the GRTC counter value latched at startup.
193 : *
194 : * @note The GRTC timer is not cleared by software at startup,
195 : * while the system tick starts counting from zero.
196 : * In some cases, it may be necessary to compare the system tick
197 : * with the GRTC value — in such situations, this offset can be useful.
198 : *
199 : * @return GRTC value latched during system clock initialization.
200 : */
201 : uint64_t z_nrf_grtc_timer_startup_value_get(void);
202 :
203 : /**
204 : * @brief Initialize the GRTC clock timer driver from an application-
205 : * defined function.
206 : *
207 : * @retval 0 on success.
208 : * @retval -errno Negative error code on failure.
209 : */
210 1 : int nrf_grtc_timer_clock_driver_init(void);
211 :
212 : #ifdef __cplusplus
213 : }
214 : #endif
215 :
216 : #endif /* ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H */
|
