blob: 95b15882cc5fb8a69ed1572a408cbde973d1351b [file] [log] [blame]
Alphan Ulusoybb457d02020-08-11 23:44:38 -04001// 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_PWRMGR_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PWRMGR_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/pwrmgr/doc/">Power Manager</a> Device Interface
11 * Functions
12 */
13
14#include <stdint.h>
15
Timothy Trippele3f8a822021-09-17 06:09:28 +000016#include "sw/device/lib/base/macros.h"
Alphan Ulusoybb457d02020-08-11 23:44:38 -040017#include "sw/device/lib/base/mmio.h"
Timothy Trippeld71d1fd2021-10-01 22:29:01 +000018#include "sw/device/lib/dif/dif_base.h"
19
20#include "sw/device/lib/dif/autogen/dif_pwrmgr_autogen.h"
Alphan Ulusoybb457d02020-08-11 23:44:38 -040021
Alphan Ulusoybb457d02020-08-11 23:44:38 -040022#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
Alphan Ulusoybb457d02020-08-11 23:44:38 -040027 * A request type, i.e. wakeup or reset.
28 */
29typedef enum dif_pwrmgr_req_type {
30 /**
31 * A wakeup request.
32 */
33 kDifPwrmgrReqTypeWakeup,
34 /**
35 * A reset request.
36 */
37 kDifPwrmgrReqTypeReset,
38} dif_pwrmgr_req_type_t;
39
40/**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040041 * Options for enabling/disabling various clock and power domains
42 * in low and active power states.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040043 *
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040044 * Constants below are bitmasks that can be combined to define configurations.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040045 *
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040046 * See also: `dif_pwrmgr_domain_config_t`.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040047 */
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040048typedef enum dif_pwrmgr_domain_option {
Alphan Ulusoybb457d02020-08-11 23:44:38 -040049 /**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040050 * Enable core clock in low power state.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040051 */
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040052 kDifPwrmgrDomainOptionCoreClockInLowPower = (1u << 0),
Alphan Ulusoybb457d02020-08-11 23:44:38 -040053 /**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040054 * Enable input/output (IO) clock in low power state.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040055 */
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040056 kDifPwrmgrDomainOptionIoClockInLowPower = (1u << 1),
Alphan Ulusoybb457d02020-08-11 23:44:38 -040057 /**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040058 * Enable USB clock in low power state.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040059 */
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040060 kDifPwrmgrDomainOptionUsbClockInLowPower = (1u << 2),
61 /**
62 * Enable USB clock in active power state.
63 */
64 kDifPwrmgrDomainOptionUsbClockInActivePower = (1u << 3),
65 /**
66 * Enable main power domain in low power state.
67 */
68 kDifPwrmgrDomainOptionMainPowerInLowPower = (1u << 4),
69} dif_pwrmgr_domain_option_t;
Alphan Ulusoybb457d02020-08-11 23:44:38 -040070
71/**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040072 * A set of domain options.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040073 *
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040074 * This type is used for specifying and querying which clock and power domains
75 * are enabled in low and active power states.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040076 *
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040077 * See also: `dif_pwrmgr_domain_option_t`.
Alphan Ulusoybb457d02020-08-11 23:44:38 -040078 */
Alphan Ulusoy4fb80392020-09-30 17:30:43 -040079typedef uint8_t dif_pwrmgr_domain_config_t;
Alphan Ulusoybb457d02020-08-11 23:44:38 -040080
81/**
82 * A wakeup request source.
83 *
84 * Constants below are bitmasks that can be used to define sets of wakeup
85 * request sources.
86 *
87 * See also: `dif_pwrmgr_request_sources_t`.
88 *
89 * Note: This needs to be updated once the HW is finalized.
90 */
91typedef enum dif_pwrmgr_wakeup_request_source {
92 kDifPwrmgrWakeupRequestSourceOne = (1u << 0),
Timothy Chenbea7b6a2021-01-21 13:59:20 -080093 kDifPwrmgrWakeupRequestSourceTwo = (1u << 1),
Timothy Chen6f98f352021-03-10 16:27:29 -080094 kDifPwrmgrWakeupRequestSourceThree = (1u << 2),
95 kDifPwrmgrWakeupRequestSourceFour = (1u << 3),
Timothy Chenb74f6122021-04-26 16:57:22 -070096 kDifPwrmgrWakeupRequestSourceFive = (1u << 4),
Guillermo Maturana8ffc7102021-09-23 20:37:30 -070097 kDifPwrmgrWakeupRequestSourceSix = (1u << 5),
Alphan Ulusoybb457d02020-08-11 23:44:38 -040098} dif_pwrmgr_wakeup_request_source_t;
99
100/**
101 * A reset request source.
102 *
103 * Constants below are bitmasks that can be used to define sets of reset
104 * request sources.
105 *
106 * See also: `dif_pwrmgr_request_sources_t`.
107 *
108 * Note: This needs to be updated once the HW is finalized.
109 */
110typedef enum dif_pwrmgr_reset_request_source {
111 kDifPwrmgrResetRequestSourceOne = (1u << 0),
Guillermo Maturana8ffc7102021-09-23 20:37:30 -0700112 kDifPwrmgrResetRequestSourceTwo = (1u << 1),
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400113} dif_pwrmgr_reset_request_source_t;
114
115/**
116 * A set of request sources.
117 *
118 * This type is used for specifying which request sources are enabled for a
119 * particular request type, i.e. wakeup or reset, as well querying wakeup
120 * reasons.
121 *
122 * See also: `dif_pwrmgr_wakeup_request_source_t`,
123 * `dif_pwrmgr_reset_request_source_t`.
124 */
125typedef uint32_t dif_pwrmgr_request_sources_t;
126
127/**
128 * A wakeup type.
129 *
130 * Constants below are bitmasks that can be used to define sets of wakeup types.
131 *
132 * See also: `dif_pwrmgr_wakeup_types_t`.
133 */
134typedef enum dif_pwrmgr_wakeup_type {
135 /**
136 * Wakeup due to a peripheral request.
137 */
138 kDifPwrmgrWakeupTypeRequest = (1u << 0),
139 /**
140 * Despite low power mode being enabled and executing a wait for interrupt
141 * (WFI) instruction, an interrupt arrived at just the right time to break the
142 * executing core out of WFI.
143 */
144 kDifPwrmgrWakeupTypeFallThrough = (1u << 1),
145 /**
146 * Despite low power mode being enabled and executing a wait for interrupt
147 * (WFI) instruction, an active flash, life cycle, or OTP operation was
148 * in progress when the power controller attempted to initiate low power
149 * entry.
150 */
151 kDifPwrmgrWakeupTypeAbort = (1u << 2),
152} dif_pwrmgr_wakeup_type_t;
153
154/**
155 * A set of wakeup types.
156 *
157 * See also: `dif_pwrmgr_wakeup_type_t`.
158 */
159typedef uint8_t dif_pwrmgr_wakeup_types_t;
160
Guillermo Maturanae500fca2022-08-22 15:26:40 -0700161typedef enum dif_pwrmgr_fatal_err_type {
162 /**
163 * A fatal error for regfile integrity.
164 */
165 kDifPwrmgrFatalErrTypeRegfileIntegrity = 1u << 0,
166 /**
167 * A fatal error for escalation timeout.
168 */
169 kDifPwrmgrFatalErrTypeEscalationTimeout = 1u << 1,
170 /**
171 * A fatal error for main power glitch.
172 */
173 kDifPwrmgrFatalErrTypeMainPowerGlitch = 1u << 2,
174} dif_pwrmgr_fatal_err_type_t;
175
176/**
177 * A set of fatal errors.
178 *
179 * This type is used to read the fatal error codes.
180 */
181typedef uint32_t dif_pwrmgr_fatal_err_codes_t;
182
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400183/**
184 * Wakeup types and requests from sources since the last time recording started.
185 */
186typedef struct dif_pwrmgr_wakeup_reason {
187 /**
188 * Wakeup types since the last time recording started.
189 */
190 dif_pwrmgr_wakeup_types_t types;
191 /**
192 * Sources that requested wakeup since the last time recording started.
193 */
194 dif_pwrmgr_request_sources_t request_sources;
195} dif_pwrmgr_wakeup_reason_t;
196
197/**
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400198 * Enables or disables low power state.
199 *
200 * When enabled, the power manager transitions to low power state on the next
201 * wait for interrupt (WFI) instruction. Since the hardware clears the
202 * corresponding bit automatically, this function must be called before each
203 * transition to low power state.
204 *
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800205 * This function can be configured to skip synchronization to the slow clock
206 * domain, under the assumption that timely synchronization will be performed
207 * by some of the other functions that can trigger it.
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400208 *
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400209 * @param pwrmgr A power manager handle.
210 * @param new_state Whether low power state is enabled.
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800211 * @param sync_state Whether to wait for state to transfer to slow domain
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400212 * @return The result of the operation.
213 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000214OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000215dif_result_t dif_pwrmgr_low_power_set_enabled(const dif_pwrmgr_t *pwrmgr,
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800216 dif_toggle_t new_state,
217 dif_toggle_t sync_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400218
219/**
220 * Checks whether low power state is enabled.
221 *
222 * @param pwrmgr A power manager handle.
223 * @param[out] cur_state Whether low power state is enabled.
224 * @return The result of the operation.
225 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000226OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000227dif_result_t dif_pwrmgr_low_power_get_enabled(const dif_pwrmgr_t *pwrmgr,
228 dif_toggle_t *cur_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400229
230/**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400231 * Configures power manager to enable/disable various clock and power domains in
232 * low and active power states.
233 *
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800234 * This function can be configured to skip synchronization to the slow clock
235 * domain, under the assumption that timely synchronization will be performed
236 * by some of the other functions that can trigger it.
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400237 *
238 * @param pwrmgr A power manager handle.
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400239 * @param config A domain configuration.
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800240 * @param sync_state Whether to wait for state to transfer to slow domain
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400241 * @return The result of the operation.
242 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000243OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000244dif_result_t dif_pwrmgr_set_domain_config(const dif_pwrmgr_t *pwrmgr,
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800245 dif_pwrmgr_domain_config_t config,
246 dif_toggle_t sync_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400247
248/**
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400249 * Gets current power manager configuration.
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400250 *
251 * @param pwrmgr A power manager handle.
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400252 * @param[out] config Current configuration.
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400253 * @return The result of the operation.
254 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000255OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000256dif_result_t dif_pwrmgr_get_domain_config(const dif_pwrmgr_t *pwrmgr,
257 dif_pwrmgr_domain_config_t *config);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400258
259/**
260 * Sets sources enabled for a request type.
261 *
262 * A wakeup or reset request can be triggered by multiple sources, e.g. GPIO,
263 * watchdog timer, USB, etc. This function sets which sources are enabled for a
264 * particular request type.
265 *
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800266 * This function can be configured to skip synchronization to the slow clock
267 * domain, under the assumption that timely synchronization will be performed
268 * by some of the other functions that can trigger it.
Alphan Ulusoy4fb80392020-09-30 17:30:43 -0400269 *
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400270 * @param pwrmgr A power manager handle.
271 * @param req_type A request type.
272 * @param sources Sources enabled for the given request type.
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800273 * @param sync_state Whether to wait for state to transfer to slow domain
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400274 * @return The result of the operation.
275 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000276OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000277dif_result_t dif_pwrmgr_set_request_sources(
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400278 const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
Guillermo Maturanaa07ba272022-01-25 08:15:04 -0800279 dif_pwrmgr_request_sources_t sources, dif_toggle_t sync_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400280
281/**
282 * Gets sources enabled for a request type.
283 *
284 * A wakeup or reset request can be triggered by multiple sources, e.g. GPIO,
285 * watchdog timer, USB, etc. This function gets which sources are enabled for a
286 * particular request type.
287 *
288 * @param pwrmgr A power manager handle.
289 * @param req_type A request type.
290 * @param[out] sources Sources enabled for the given request type.
291 * @return The result of the operation.
292 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000293OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000294dif_result_t dif_pwrmgr_get_request_sources(
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400295 const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
296 dif_pwrmgr_request_sources_t *sources);
297
298/**
299 * Gets request sources that are currently active for a request type.
300 *
301 * @param pwrmgr A power manager handle.
302 * @param req_type A request type.
303 * @param[out] sources Request sources that are currently active for the given
304 * request type.
305 * @return The result of the operation.
306 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000307OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000308dif_result_t dif_pwrmgr_get_current_request_sources(
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400309 const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
310 dif_pwrmgr_request_sources_t *sources);
311
312/**
313 * Locks sources of a request type.
314 *
315 * Once the sources of a particular request type is locked, they cannot be
316 * changed until the hardware is reset.
317 *
318 * @param pwrmgr A power manager handle.
319 * @param req_type A request type.
320 * @return The result of the operation.
321 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000322OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000323dif_result_t dif_pwrmgr_request_sources_lock(const dif_pwrmgr_t *pwrmgr,
324 dif_pwrmgr_req_type_t req_type);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400325
326/**
327 * Checks whether sources of a request type is locked.
328 *
329 * @param pwrmgr A power manager handle.
330 * @param req_type A request type.
331 * @param[out] is_locked Whether sources of the given request type is locked.
332 * @return The result of the operation.
333 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000334OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000335dif_result_t dif_pwrmgr_request_sources_is_locked(
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400336 const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type,
337 bool *is_locked);
338
339/**
340 * Enables or disables recording of wakeup requests.
341 *
342 * Power manager automatically starts recording wakeup requests when it
343 * begins a valid low power entry. Recording continues until it is explicitly
344 * disabled by calling this function.
345 *
346 * @param pwrmgr A power manager handle.
347 * @param new_state Whether wakeup requests should be recorded.
348 * @return The result of the operation.
349 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000350OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000351dif_result_t dif_pwrmgr_wakeup_request_recording_set_enabled(
352 const dif_pwrmgr_t *pwrmgr, dif_toggle_t new_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400353
354/**
355 * Checks whether wakeup requests are being recorded.
356 *
357 * @param pwrmgr A power manager handle.
358 * @param[out] cur_state Whether wakeup requests are being recorded.
359 * @return The result of the operation.
360 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000361OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000362dif_result_t dif_pwrmgr_wakeup_request_recording_get_enabled(
363 const dif_pwrmgr_t *pwrmgr, dif_toggle_t *cur_state);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400364
365/**
366 * Gets wakeup reason and source requests since the last time recording
367 * started.
368 *
369 * Power manager automatically starts recording wakeup requests when it
370 * begins a valid low power entry. Recording continues until it is explicitly
371 * disabled by calling `dif_pwrmgr_wakeup_request_recording_set_enabled`. Thus,
372 * it is possible to record wakeup requests from multiple sources as well as
373 * multiple wakeup types.
374 *
375 * @param pwrmgr A power manager handle.
376 * @param[out] reason Wakeup reasons.
377 * @return The result of the operation.
378 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000379OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000380dif_result_t dif_pwrmgr_wakeup_reason_get(const dif_pwrmgr_t *pwrmgr,
381 dif_pwrmgr_wakeup_reason_t *reason);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400382
383/**
384 * Clears wakeup reason(s) recorded since the last time recording started.
385 *
386 * @param pwrmgr A power manager handle.
387 * @return The result of the operation.
388 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000389OT_WARN_UNUSED_RESULT
Timothy Trippeld71d1fd2021-10-01 22:29:01 +0000390dif_result_t dif_pwrmgr_wakeup_reason_clear(const dif_pwrmgr_t *pwrmgr);
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400391
Guillermo Maturanae500fca2022-08-22 15:26:40 -0700392/**
393 * Read the fatal error codes.
394 *
395 * @param pwrmgr Power Manager Handle.
396 * @param[out] codes The fatal error codes.
397 * @returns The result of the operation.
398 */
399OT_WARN_UNUSED_RESULT
400dif_result_t dif_pwrmgr_fatal_err_code_get_codes(
401 const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_fatal_err_codes_t *codes);
402
Alphan Ulusoybb457d02020-08-11 23:44:38 -0400403#ifdef __cplusplus
404} // extern "C"
405#endif // __cplusplus
406
407#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PWRMGR_H_