Software APIs
dif_pwrmgr.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_PWRMGR_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PWRMGR_H_
7 
8 /**
9  * @file
10  * @brief <a href="/book/hw/top_earlgrey/ip_autogen/pwrmgr/">Power Manager</a>
11  * Device Interface Functions
12  */
13 
14 #include <stdint.h>
15 
19 
20 #include "sw/device/lib/dif/autogen/dif_pwrmgr_autogen.h"
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif // __cplusplus
25 
26 /**
27  * A request type, i.e. wakeup or reset.
28  */
29 typedef enum dif_pwrmgr_req_type {
30  /**
31  * A wakeup request.
32  */
34  /**
35  * A reset request.
36  */
39 
40 /**
41  * Options for enabling/disabling various clock and power domains
42  * in low and active power states.
43  *
44  * Constants below are bitmasks that can be combined to define configurations.
45  *
46  * See also: `dif_pwrmgr_domain_config_t`.
47  */
49  /**
50  * Enable core clock in low power state.
51  */
53  /**
54  * Enable input/output (IO) clock in low power state.
55  */
57 #if defined(OPENTITAN_IS_EARLGREY) || defined(OPENTITAN_IS_ENGLISHBREAKFAST)
58  /**
59  * Enable USB clock in low power state.
60  */
61  kDifPwrmgrDomainOptionUsbClockInLowPower = (1u << 2),
62  /**
63  * Enable USB clock in active power state.
64  */
65  kDifPwrmgrDomainOptionUsbClockInActivePower = (1u << 3),
66  /**
67  * Enable main power domain in low power state.
68  */
69  kDifPwrmgrDomainOptionMainPowerInLowPower = (1u << 4),
70 #elif defined(OPENTITAN_IS_DARJEELING)
71  /**
72  * Enable main power domain in low power state.
73  */
74  kDifPwrmgrDomainOptionMainPowerInLowPower = (1u << 2),
75 #else /* OPENTITAN_IS_ */
76 #error "dif_pwrmgr does not support this top"
77 #endif /* OPENTITAN_IS_ */
79 
80 /**
81  * A set of domain options.
82  *
83  * This type is used for specifying and querying which clock and power domains
84  * are enabled in low and active power states.
85  *
86  * See also: `dif_pwrmgr_domain_option_t`.
87  */
89 
90 /**
91  * A set of request sources.
92  *
93  * This type is used for specifying which request sources are enabled for a
94  * particular request type, i.e. wakeup or reset, as well querying wakeup
95  * reasons.
96  *
97  * See also: `dt_pwrmgr_wakeup_src_t`, `dt_pwrmgr_reset_req_src_t` and
98  * associated functions.
99  */
101 
102 /**
103  * A wakeup type.
104  *
105  * Constants below are bitmasks that can be used to define sets of wakeup types.
106  *
107  * See also: `dif_pwrmgr_wakeup_types_t`.
108  */
110  /**
111  * Wakeup due to a peripheral request.
112  */
114  /**
115  * Despite low power mode being enabled and executing a wait for interrupt
116  * (WFI) instruction, an interrupt arrived at just the right time to break the
117  * executing core out of WFI.
118  */
120  /**
121  * Despite low power mode being enabled and executing a wait for interrupt
122  * (WFI) instruction, an active flash, life cycle, or OTP operation was
123  * in progress when the power controller attempted to initiate low power
124  * entry.
125  */
128 
129 /**
130  * A set of wakeup types.
131  *
132  * See also: `dif_pwrmgr_wakeup_type_t`.
133  */
135 
137  /**
138  * A fatal error for regfile integrity.
139  */
141  /**
142  * A fatal error for escalation timeout.
143  */
145  /**
146  * A fatal error for main power glitch.
147  */
149 } dif_pwrmgr_fatal_err_type_t;
150 
151 /**
152  * A set of fatal errors.
153  *
154  * This type is used to read the fatal error codes.
155  */
157 
158 /**
159  * Wakeup types and requests from sources since the last time recording started.
160  */
161 typedef struct dif_pwrmgr_wakeup_reason {
162  /**
163  * Wakeup types since the last time recording started.
164  */
166  /**
167  * Sources that requested wakeup since the last time recording started.
168  */
171 
172 /**
173  * Obtain a bit mask of wakeups/reset requests for a device.
174  *
175  * Given a module instance (identified by its instance ID) and a wakeup
176  * or reset request index from this module, return a bitmask of sources which
177  * can be used with the pwrmgr DIF or testutils.
178  *
179  * Example (find request source of the aon_timer wakeup):
180  * ```c
181  * dif_pwrmgr_request_sources_t wakeup_sources;
182  * CHECK_DIF_OK(dif_pwrmgr_find_request_source(
183  * pwrmgr,
184  * kDifPwrmgrReqTypeWakeup,
185  * dt_aon_timer_instance_id(kDtAonTimerAon),
186  * kDtAonTimerWakeupWkupReq,
187  * &wakeup_sources));
188  * ```
189  *
190  * @param pwrmgr A power manager handle.
191  * @param req_type Request type (wake up or reset request).
192  * @param inst_id An instance ID.
193  * @param idx Signal index.
194  * @param[out] sources The bitmask corresponding to the wakeup or reset
195  * requested.
196  * @return `kDifError` if no signal matches the description or the DIF
197  * was not initialized by DT, `kDifOk` otherwise.
198  */
201  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
202  dt_instance_id_t inst_id, size_t idx,
204 
205 /**
206  * Obtain a bit mask of all wakeups/reset requests.
207  *
208  * @param pwrmgr A power manager handle.
209  * @param req_type Request type (wake up or reset request).
210  * @param[out] sources The bitmask corresponding to all wakeups or resets
211  * @return `kDifError` if no DIF was not initialized by DT, `kDifOk` otherwise.
212  */
215  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
217 
218 /**
219  * Enables or disables low power state.
220  *
221  * When enabled, the power manager transitions to low power state on the next
222  * wait for interrupt (WFI) instruction. Since the hardware clears the
223  * corresponding bit automatically, this function must be called before each
224  * transition to low power state.
225  *
226  * This function can be configured to skip synchronization to the slow clock
227  * domain, under the assumption that timely synchronization will be performed
228  * by some of the other functions that can trigger it.
229  *
230  * @param pwrmgr A power manager handle.
231  * @param new_state Whether low power state is enabled.
232  * @param sync_state Whether to wait for state to transfer to slow domain
233  * @return The result of the operation.
234  */
236 dif_result_t dif_pwrmgr_low_power_set_enabled(const dif_pwrmgr_t *pwrmgr,
237  dif_toggle_t new_state,
238  dif_toggle_t sync_state);
239 
240 /**
241  * Checks whether low power state is enabled.
242  *
243  * @param pwrmgr A power manager handle.
244  * @param[out] cur_state Whether low power state is enabled.
245  * @return The result of the operation.
246  */
248 dif_result_t dif_pwrmgr_low_power_get_enabled(const dif_pwrmgr_t *pwrmgr,
249  dif_toggle_t *cur_state);
250 
251 /**
252  * Configures power manager to enable/disable various clock and power domains in
253  * low and active power states.
254  *
255  * This function can be configured to skip synchronization to the slow clock
256  * domain, under the assumption that timely synchronization will be performed
257  * by some of the other functions that can trigger it.
258  *
259  * @param pwrmgr A power manager handle.
260  * @param config A domain configuration.
261  * @param sync_state Whether to wait for state to transfer to slow domain
262  * @return The result of the operation.
263  */
265 dif_result_t dif_pwrmgr_set_domain_config(const dif_pwrmgr_t *pwrmgr,
267  dif_toggle_t sync_state);
268 
269 /**
270  * Gets current power manager configuration.
271  *
272  * @param pwrmgr A power manager handle.
273  * @param[out] config Current configuration.
274  * @return The result of the operation.
275  */
277 dif_result_t dif_pwrmgr_get_domain_config(const dif_pwrmgr_t *pwrmgr,
279 
280 /**
281  * Sets sources enabled for a request type.
282  *
283  * A wakeup or reset request can be triggered by multiple sources, e.g. GPIO,
284  * watchdog timer, USB, etc. This function sets which sources are enabled for a
285  * particular request type.
286  *
287  * This function can be configured to skip synchronization to the slow clock
288  * domain, under the assumption that timely synchronization will be performed
289  * by some of the other functions that can trigger it.
290  *
291  * @param pwrmgr A power manager handle.
292  * @param req_type A request type.
293  * @param sources Sources enabled for the given request type.
294  * @param sync_state Whether to wait for state to transfer to slow domain
295  * @return The result of the operation.
296  */
299  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
300  dif_pwrmgr_request_sources_t sources, dif_toggle_t sync_state);
301 
302 /**
303  * Gets sources enabled for a request type.
304  *
305  * A wakeup or reset request can be triggered by multiple sources, e.g. GPIO,
306  * watchdog timer, USB, etc. This function gets which sources are enabled for a
307  * particular request type.
308  *
309  * @param pwrmgr A power manager handle.
310  * @param req_type A request type.
311  * @param[out] sources Sources enabled for the given request type.
312  * @return The result of the operation.
313  */
316  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
318 
319 /**
320  * Gets request sources that are currently active for a request type.
321  *
322  * @param pwrmgr A power manager handle.
323  * @param req_type A request type.
324  * @param[out] sources Request sources that are currently active for the given
325  * request type.
326  * @return The result of the operation.
327  */
330  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
332 
333 /**
334  * Locks sources of a request type.
335  *
336  * Once the sources of a particular request type is locked, they cannot be
337  * changed until the hardware is reset.
338  *
339  * @param pwrmgr A power manager handle.
340  * @param req_type A request type.
341  * @return The result of the operation.
342  */
344 dif_result_t dif_pwrmgr_request_sources_lock(const dif_pwrmgr_t *pwrmgr,
345  dif_pwrmgr_req_type_t req_type);
346 
347 /**
348  * Checks whether sources of a request type is locked.
349  *
350  * @param pwrmgr A power manager handle.
351  * @param req_type A request type.
352  * @param[out] is_locked Whether sources of the given request type is locked.
353  * @return The result of the operation.
354  */
357  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
358  bool *is_locked);
359 
360 /**
361  * Enables or disables recording of wakeup requests.
362  *
363  * Power manager automatically starts recording wakeup requests when it
364  * begins a valid low power entry. Recording continues until it is explicitly
365  * disabled by calling this function.
366  *
367  * @param pwrmgr A power manager handle.
368  * @param new_state Whether wakeup requests should be recorded.
369  * @return The result of the operation.
370  */
373  const dif_pwrmgr_t *pwrmgr, dif_toggle_t new_state);
374 
375 /**
376  * Checks whether wakeup requests are being recorded.
377  *
378  * @param pwrmgr A power manager handle.
379  * @param[out] cur_state Whether wakeup requests are being recorded.
380  * @return The result of the operation.
381  */
384  const dif_pwrmgr_t *pwrmgr, dif_toggle_t *cur_state);
385 
386 /**
387  * Gets wakeup reason and source requests since the last time recording
388  * started.
389  *
390  * Power manager automatically starts recording wakeup requests when it
391  * begins a valid low power entry. Recording continues until it is explicitly
392  * disabled by calling `dif_pwrmgr_wakeup_request_recording_set_enabled`. Thus,
393  * it is possible to record wakeup requests from multiple sources as well as
394  * multiple wakeup types.
395  *
396  * @param pwrmgr A power manager handle.
397  * @param[out] reason Wakeup reasons.
398  * @return The result of the operation.
399  */
401 dif_result_t dif_pwrmgr_wakeup_reason_get(const dif_pwrmgr_t *pwrmgr,
403 
404 /**
405  * Clears wakeup reason(s) recorded since the last time recording started.
406  *
407  * @param pwrmgr A power manager handle.
408  * @return The result of the operation.
409  */
411 dif_result_t dif_pwrmgr_wakeup_reason_clear(const dif_pwrmgr_t *pwrmgr);
412 
413 /**
414  * Read the fatal error codes.
415  *
416  * @param pwrmgr Power Manager Handle.
417  * @param[out] codes The fatal error codes.
418  * @returns The result of the operation.
419  */
422  const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_fatal_err_codes_t *codes);
423 
424 #ifdef __cplusplus
425 } // extern "C"
426 #endif // __cplusplus
427 
428 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PWRMGR_H_