Software APIs
dif_aon_timer.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors.
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_AON_TIMER_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_AON_TIMER_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/aon_timer/doc/">Always-On Timer</a> Device Interface
11  * Functions
12  */
13 
14 #include <stdbool.h>
15 #include <stdint.h>
16 
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif // __cplusplus
23 
24 /**
25  * Hardware instantiation parameters for Always-On Timer.
26  *
27  * This struct describes information about the underlying hardware that is
28  * not determined until the hardware design is used as part of a top-level
29  * design.
30  */
31 typedef struct dif_aon_timer_params {
32  /**
33  * The base address for the Always-On Timer hardware registers.
34  */
37 
38 /**
39  * A handle to Always-On Timer.
40  *
41  * This type should be treated as opaque by users.
42  */
43 typedef struct dif_aon_timer {
46 
47 /**
48  * The result of a Always-On Timer operation.
49  */
50 typedef enum dif_aon_timer_result {
51  /**
52  * Indicates that the operation succeeded.
53  */
55  /**
56  * Indicates some unspecified failure.
57  */
59  /**
60  * Indicates that some parameter passed into a function failed a
61  * precondition.
62  *
63  * When this value is returned, no hardware operations occurred.
64  */
67 
68 /**
69  * The result of a Always-On Timer (watchdog timer) operation.
70  */
72  /**
73  * Indicates that the operation succeeded.
74  */
76  /**
77  * Indicates some unspecified failure.
78  */
80  /**
81  * Indicates that some parameter passed into a function failed a
82  * precondition.
83  *
84  * When this value is returned, no hardware operations occurred.
85  */
87  /**
88  * Indicates that this operation has been locked out, and can never
89  * succeed until hardware reset.
90  */
93 
94 /**
95  * An Always-On Timer interrupt request type.
96  */
97 typedef enum dif_aon_timer_irq {
98  /**
99  * Wake-up timer has expired.
100  */
102  /**
103  * Watchdog timer "Bark" threshold has expired.
104  */
107 
108 /**
109  * Creates a new handle for Always-On Timer.
110  *
111  * This function does not actuate the hardware.
112  *
113  * @param params Hardware instantiation parameters.
114  * @param[out] aon Out param for the initialised handle.
115  * @return The result of the operation.
116  */
119  dif_aon_timer_t *aon);
120 
121 /**
122  * Starts Always-On Timer (wake-up timer).
123  *
124  * This operation starts the wake-up timer with the provided configuration.
125  * Note that the timer is stopped and counter cleared, before the timer is
126  * started with the new configuration.
127  *
128  * @param aon An Always-On Timer handle.
129  * @param threshold Threshold in ticks.
130  * @param prescaler 12 bit pre-scaler to enable very long timeouts (one tick
131  * every N + 1 clock cycles, where N is the pre-scaler value).
132  * @return The result of the operation.
133  */
136  uint32_t threshold,
137  uint32_t prescaler);
138 
139 /** Stops Always-On Timer (wake-up timer).
140  *
141  * Stops the timer. Configuration is not touched, and can be restarted via
142  * `dif_aon_timer_wakeup_restart`.
143  *
144  * @param aon An Always-On Timer handle.
145  * @return The result of the operation.
146  */
149 
150 /** Restarts Always-On Timer (wake-up timer).
151  *
152  * Clears the counter and restarts the timer using the existing configuration.
153  *
154  * @param aon An Always-On Timer handle.
155  * @return The result of the operation.
156  */
159 
160 /** Retrieves Always-On Timer (wake-up timer) tick count.
161  *
162  * @param aon An Always-On Timer handle.
163  * @param[out] count Current timer tick count.
164  * @return The result of the operation.
165  */
168  const dif_aon_timer_t *aon, uint32_t *count);
169 
170 /** Starts Always-On Timer (watchdog timer).
171  *
172  * This operation starts the watchdog timer with the provided configuration.
173  * Note that the timer is stopped and counter cleared, before the timer is
174  * started with the new configuration.
175  *
176  * @param aon An Always-On Timer handle.
177  * @param bark_threshold "Bark" threshold in ticks.
178  * @param bite_threshold "Bite" threshold in ticks.
179  * @param pause_in_sleep Watchdog is paused when device is in one of the low
180  * power modes.
181  * @param lock Lock access to watchdog configuration registers.
182  * @return The result of the operation.
183  */
186  const dif_aon_timer_t *aon, uint32_t bark_threshold,
187  uint32_t bite_threshold, bool pause_in_sleep, bool lock);
188 
189 /** Stops Always-On Timer (watchdog timer).
190  *
191  * Stops the timer. Configuration is not touched, and can be restarted via
192  * `dif_aon_timer_watchdog_restart`.
193  *
194  * @param aon An Always-On Timer handle.
195  * @return The result of the operation.
196  */
199  const dif_aon_timer_t *aon);
200 
201 /** Restarts Always-On Timer (watchdog timer).
202  *
203  * Clears the counter and restarts the timer using the existing configuration.
204  *
205  * @param aon An Always-On Timer handle.
206  * @return The result of the operation.
207  */
210  const dif_aon_timer_t *aon);
211 
212 /** Retrieves Always-On Timer (watchdog timer) tick count.
213  *
214  * @param aon An Always-On Timer handle.
215  * @param[out] count Current timer tick count.
216  * @return The result of the operation.
217  */
220  const dif_aon_timer_t *aon, uint32_t *count);
221 
222 /** Clears Always-On Timer (watchdog timer).
223  *
224  * This function must be called periodically to satisfy "Bite" and "Bark"
225  * thresholds. The semantics of this function are similar to
226  * `dif_aon_timer_watchdog_restart`, however it does not write to the control
227  * register, and is guaranteed to succeed even when the watchdog is locked.
228  *
229  * @param aon An Always-On Timer handle.
230  * @return The result of the operation.
231  */
234 
235 /**
236  * Locks Always-On Timer (watchdog timer).
237  *
238  * The watchdog configuration will be locked until the next reset. This means
239  * that this timer cannot be stopped, restarted or reconfigured, however the
240  * count can be cleared via `dif_aon_timer_watchdog_pet`.
241  *
242  * @param aon An Always-On Timer handle.
243  * @return The result of the operation.
244  */
247  const dif_aon_timer_t *aon);
248 
249 /**
250  * Checks whether this Always-On Timer (watchdog timer) is locked.
251  *
252  * @param aon An Always-On Timer handle.
253  * @param[out] is_locked Out-param for the locked state.
254  * @return The result of the operation.
255  */
258  const dif_aon_timer_t *aon, bool *is_locked);
259 
260 /**
261  * Returns whether a particular interrupt is currently pending.
262  *
263  * @param aon An Always-On Timer handle.
264  * @param irq An interrupt type.
265  * @param[out] is_pending Out-param for whether the interrupt is pending.
266  * @return The result of the operation.
267  */
270  dif_aon_timer_irq_t irq,
271  bool *is_pending);
272 
273 /**
274  * Acknowledges a particular interrupt.
275  *
276  * This operation indicates to the hardware that the interrupt has been
277  * successfully serviced.
278  *
279  * @param aon An Always-On Timer handle.
280  * @param irq An interrupt type.
281  * @return The result of the operation.
282  */
285  dif_aon_timer_irq_t irq);
286 
287 /**
288  * Forces a particular interrupt, causing it to be serviced as if hardware had
289  * asserted it.
290  *
291  * @param aon An Always-On Timer handle.
292  * @param irq An interrupt type.
293  * @return The result of the operation.
294  */
297  dif_aon_timer_irq_t irq);
298 
299 #ifdef __cplusplus
300 } // extern "C"
301 #endif // __cplusplus
302 
303 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_AON_TIMER_H_