Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 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_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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 16 | #include "sw/device/lib/base/macros.h" |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 17 | #include "sw/device/lib/base/mmio.h" |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 18 | #include "sw/device/lib/dif/dif_base.h" |
| 19 | |
| 20 | #include "sw/device/lib/dif/autogen/dif_pwrmgr_autogen.h" |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 21 | |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 22 | #ifdef __cplusplus |
| 23 | extern "C" { |
| 24 | #endif // __cplusplus |
| 25 | |
| 26 | /** |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 27 | * A request type, i.e. wakeup or reset. |
| 28 | */ |
| 29 | typedef 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 Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 41 | * Options for enabling/disabling various clock and power domains |
| 42 | * in low and active power states. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 43 | * |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 44 | * Constants below are bitmasks that can be combined to define configurations. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 45 | * |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 46 | * See also: `dif_pwrmgr_domain_config_t`. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 47 | */ |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 48 | typedef enum dif_pwrmgr_domain_option { |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 49 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 50 | * Enable core clock in low power state. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 51 | */ |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 52 | kDifPwrmgrDomainOptionCoreClockInLowPower = (1u << 0), |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 53 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 54 | * Enable input/output (IO) clock in low power state. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 55 | */ |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 56 | kDifPwrmgrDomainOptionIoClockInLowPower = (1u << 1), |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 57 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 58 | * Enable USB clock in low power state. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 59 | */ |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 60 | 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 Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 70 | |
| 71 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 72 | * A set of domain options. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 73 | * |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 74 | * This type is used for specifying and querying which clock and power domains |
| 75 | * are enabled in low and active power states. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 76 | * |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 77 | * See also: `dif_pwrmgr_domain_option_t`. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 78 | */ |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 79 | typedef uint8_t dif_pwrmgr_domain_config_t; |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 80 | |
| 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 | */ |
| 91 | typedef enum dif_pwrmgr_wakeup_request_source { |
| 92 | kDifPwrmgrWakeupRequestSourceOne = (1u << 0), |
Timothy Chen | bea7b6a | 2021-01-21 13:59:20 -0800 | [diff] [blame] | 93 | kDifPwrmgrWakeupRequestSourceTwo = (1u << 1), |
Timothy Chen | 6f98f35 | 2021-03-10 16:27:29 -0800 | [diff] [blame] | 94 | kDifPwrmgrWakeupRequestSourceThree = (1u << 2), |
| 95 | kDifPwrmgrWakeupRequestSourceFour = (1u << 3), |
Timothy Chen | b74f612 | 2021-04-26 16:57:22 -0700 | [diff] [blame] | 96 | kDifPwrmgrWakeupRequestSourceFive = (1u << 4), |
Guillermo Maturana | 8ffc710 | 2021-09-23 20:37:30 -0700 | [diff] [blame] | 97 | kDifPwrmgrWakeupRequestSourceSix = (1u << 5), |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 98 | } 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 | */ |
| 110 | typedef enum dif_pwrmgr_reset_request_source { |
| 111 | kDifPwrmgrResetRequestSourceOne = (1u << 0), |
Guillermo Maturana | 8ffc710 | 2021-09-23 20:37:30 -0700 | [diff] [blame] | 112 | kDifPwrmgrResetRequestSourceTwo = (1u << 1), |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 113 | } 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 | */ |
| 125 | typedef 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 | */ |
| 134 | typedef 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 | */ |
| 159 | typedef uint8_t dif_pwrmgr_wakeup_types_t; |
| 160 | |
Guillermo Maturana | e500fca | 2022-08-22 15:26:40 -0700 | [diff] [blame] | 161 | typedef 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 | */ |
| 181 | typedef uint32_t dif_pwrmgr_fatal_err_codes_t; |
| 182 | |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 183 | /** |
| 184 | * Wakeup types and requests from sources since the last time recording started. |
| 185 | */ |
| 186 | typedef 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 Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 198 | * 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 Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 205 | * 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 Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 208 | * |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 209 | * @param pwrmgr A power manager handle. |
| 210 | * @param new_state Whether low power state is enabled. |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 211 | * @param sync_state Whether to wait for state to transfer to slow domain |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 212 | * @return The result of the operation. |
| 213 | */ |
Timothy Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 214 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 215 | dif_result_t dif_pwrmgr_low_power_set_enabled(const dif_pwrmgr_t *pwrmgr, |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 216 | dif_toggle_t new_state, |
| 217 | dif_toggle_t sync_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 218 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 226 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 227 | dif_result_t dif_pwrmgr_low_power_get_enabled(const dif_pwrmgr_t *pwrmgr, |
| 228 | dif_toggle_t *cur_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 229 | |
| 230 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 231 | * Configures power manager to enable/disable various clock and power domains in |
| 232 | * low and active power states. |
| 233 | * |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 234 | * 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 Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 237 | * |
| 238 | * @param pwrmgr A power manager handle. |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 239 | * @param config A domain configuration. |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 240 | * @param sync_state Whether to wait for state to transfer to slow domain |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 241 | * @return The result of the operation. |
| 242 | */ |
Timothy Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 243 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 244 | dif_result_t dif_pwrmgr_set_domain_config(const dif_pwrmgr_t *pwrmgr, |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 245 | dif_pwrmgr_domain_config_t config, |
| 246 | dif_toggle_t sync_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 247 | |
| 248 | /** |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 249 | * Gets current power manager configuration. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 250 | * |
| 251 | * @param pwrmgr A power manager handle. |
Alphan Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 252 | * @param[out] config Current configuration. |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 253 | * @return The result of the operation. |
| 254 | */ |
Timothy Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 255 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 256 | dif_result_t dif_pwrmgr_get_domain_config(const dif_pwrmgr_t *pwrmgr, |
| 257 | dif_pwrmgr_domain_config_t *config); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 258 | |
| 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 Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 266 | * 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 Ulusoy | 4fb8039 | 2020-09-30 17:30:43 -0400 | [diff] [blame] | 269 | * |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 270 | * @param pwrmgr A power manager handle. |
| 271 | * @param req_type A request type. |
| 272 | * @param sources Sources enabled for the given request type. |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 273 | * @param sync_state Whether to wait for state to transfer to slow domain |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 274 | * @return The result of the operation. |
| 275 | */ |
Timothy Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 276 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 277 | dif_result_t dif_pwrmgr_set_request_sources( |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 278 | const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type, |
Guillermo Maturana | a07ba27 | 2022-01-25 08:15:04 -0800 | [diff] [blame] | 279 | dif_pwrmgr_request_sources_t sources, dif_toggle_t sync_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 280 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 293 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 294 | dif_result_t dif_pwrmgr_get_request_sources( |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 295 | 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 307 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 308 | dif_result_t dif_pwrmgr_get_current_request_sources( |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 309 | 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 322 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 323 | dif_result_t dif_pwrmgr_request_sources_lock(const dif_pwrmgr_t *pwrmgr, |
| 324 | dif_pwrmgr_req_type_t req_type); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 325 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 334 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 335 | dif_result_t dif_pwrmgr_request_sources_is_locked( |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 336 | 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 350 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 351 | dif_result_t dif_pwrmgr_wakeup_request_recording_set_enabled( |
| 352 | const dif_pwrmgr_t *pwrmgr, dif_toggle_t new_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 353 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 361 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 362 | dif_result_t dif_pwrmgr_wakeup_request_recording_get_enabled( |
| 363 | const dif_pwrmgr_t *pwrmgr, dif_toggle_t *cur_state); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 364 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 379 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 380 | dif_result_t dif_pwrmgr_wakeup_reason_get(const dif_pwrmgr_t *pwrmgr, |
| 381 | dif_pwrmgr_wakeup_reason_t *reason); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 382 | |
| 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 Trippel | e3f8a82 | 2021-09-17 06:09:28 +0000 | [diff] [blame] | 389 | OT_WARN_UNUSED_RESULT |
Timothy Trippel | d71d1fd | 2021-10-01 22:29:01 +0000 | [diff] [blame] | 390 | dif_result_t dif_pwrmgr_wakeup_reason_clear(const dif_pwrmgr_t *pwrmgr); |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 391 | |
Guillermo Maturana | e500fca | 2022-08-22 15:26:40 -0700 | [diff] [blame] | 392 | /** |
| 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 | */ |
| 399 | OT_WARN_UNUSED_RESULT |
| 400 | dif_result_t dif_pwrmgr_fatal_err_code_get_codes( |
| 401 | const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_fatal_err_codes_t *codes); |
| 402 | |
Alphan Ulusoy | bb457d0 | 2020-08-11 23:44:38 -0400 | [diff] [blame] | 403 | #ifdef __cplusplus |
| 404 | } // extern "C" |
| 405 | #endif // __cplusplus |
| 406 | |
| 407 | #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PWRMGR_H_ |