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
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * A request type, i.e. wakeup or reset.
28 */
29typedef 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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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_