Software APIs
dif_aon_timer.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
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
20
21#include "sw/device/lib/dif/autogen/dif_aon_timer_autogen.h"
22
23#ifdef __cplusplus
24extern "C" {
25#endif // __cplusplus
26
27/**
28 * Starts Always-On Timer (wake-up timer).
29 *
30 * This operation starts the wake-up timer with the provided configuration.
31 * Note that the timer is stopped and counter cleared, before the timer is
32 * started with the new configuration.
33 *
34 * @param aon An Always-On Timer handle.
35 * @param threshold Threshold in ticks.
36 * @param prescaler 12 bit pre-scaler to enable very long timeouts (one tick
37 * every N + 1 clock cycles, where N is the pre-scaler value).
38 * @return The result of the operation.
39 */
42 uint64_t threshold, uint32_t prescaler);
43
44/** Stops Always-On Timer (wake-up timer).
45 *
46 * Stops the timer. Configuration is not touched, and can be restarted via
47 * `dif_aon_timer_wakeup_restart`.
48 *
49 * @param aon An Always-On Timer handle.
50 * @return The result of the operation.
51 */
54
55/** Restarts Always-On Timer (wake-up timer).
56 *
57 * Clears the counter and restarts the timer using the existing configuration.
58 *
59 * @param aon An Always-On Timer handle.
60 * @return The result of the operation.
61 */
64
65/**
66 * Checks whether this Always-On Timer (wake-up timer) is enabled.
67 *
68 * @param aon An Always-On Timer handle.
69 * @param[out] is_enabled Out-param for the enabled state.
70 * @return The result of the operation.
71 */
74 bool *is_enabled);
75/**
76 * Gets the wakeup cause.
77 *
78 * @param aon An Always-On Timer handle.
79 * @param[out] cause The current cause state.
80 * @return The result of the operation.
81 */
84 bool *cause);
85
86/** Clear Always-On Timer wakeup cause
87 *
88 * Clears WKUP_CAUSE register
89 *
90 * @param aon An Always-On Timer handle.
91 * @return The result of the operation.
92 */
95
96/** Retrieves Always-On Timer (wake-up timer) tick count.
97 *
98 * @param aon An Always-On Timer handle.
99 * @param[out] count Current timer tick count.
100 * @return The result of the operation.
101 */
104 uint64_t *count);
105
106/** Starts Always-On Timer (watchdog timer).
107 *
108 * This operation starts the watchdog timer with the provided configuration.
109 * Note that the timer is stopped and counter cleared, before the timer is
110 * started with the new configuration.
111 *
112 * @param aon An Always-On Timer handle.
113 * @param bark_threshold "Bark" threshold in ticks.
114 * @param bite_threshold "Bite" threshold in ticks.
115 * @param pause_in_sleep Watchdog is paused when device is in one of the low
116 * power modes.
117 * @param lock Lock access to watchdog configuration registers.
118 * @return The result of the operation.
119 */
122 uint32_t bark_threshold,
123 uint32_t bite_threshold,
124 bool pause_in_sleep, bool lock);
125
126/** Stops Always-On Timer (watchdog timer).
127 *
128 * Stops the timer. Configuration is not touched, and can be restarted via
129 * `dif_aon_timer_watchdog_restart`.
130 *
131 * @param aon An Always-On Timer handle.
132 * @return The result of the operation.
133 */
136
137/** Restarts Always-On Timer (watchdog timer).
138 *
139 * Clears the counter and restarts the timer using the existing configuration.
140 *
141 * @param aon An Always-On Timer handle.
142 * @return The result of the operation.
143 */
146
147/**
148 * Checks whether this Always-On Timer (watchdog timer) is enabled.
149 *
150 * @param aon An Always-On Timer handle.
151 * @param[out] is_enabled Out-param for the enabled state.
152 * @return The result of the operation.
153 */
156 bool *is_enabled);
157
158/** Retrieves Always-On Timer (watchdog timer) tick count.
159 *
160 * @param aon An Always-On Timer handle.
161 * @param[out] count Current timer tick count.
162 * @return The result of the operation.
163 */
166 uint32_t *count);
167
168/** Clears Always-On Timer (watchdog timer).
169 *
170 * This function must be called periodically to satisfy "Bite" and "Bark"
171 * thresholds. The semantics of this function are similar to
172 * `dif_aon_timer_watchdog_restart`, however it does not write to the control
173 * register, and is guaranteed to succeed even when the watchdog is locked.
174 *
175 * @param aon An Always-On Timer handle.
176 * @return The result of the operation.
177 */
180
181/**
182 * Locks Always-On Timer (watchdog timer).
183 *
184 * The watchdog configuration will be locked until the next reset. This means
185 * that this timer cannot be stopped, restarted or reconfigured, however the
186 * count can be cleared via `dif_aon_timer_watchdog_pet`.
187 *
188 * @param aon An Always-On Timer handle.
189 * @return The result of the operation.
190 */
193
194/**
195 * Checks whether this Always-On Timer (watchdog timer) is locked.
196 *
197 * @param aon An Always-On Timer handle.
198 * @param[out] is_locked Out-param for the locked state.
199 * @return The result of the operation.
200 */
203 bool *is_locked);
204
205#ifdef __cplusplus
206} // extern "C"
207#endif // __cplusplus
208
209#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_AON_TIMER_H_