Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_pwrmgr.h File Reference

(de38ce3)

Power Manager Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_pwrmgr_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_pwrmgr_wakeup_reason
 Wakeup types and requests from sources since the last time recording started. More...
 

Typedefs

typedef enum dif_pwrmgr_req_type dif_pwrmgr_req_type_t
 A request type, i.e. More...
 
typedef enum dif_pwrmgr_domain_option dif_pwrmgr_domain_option_t
 Options for enabling/disabling various clock and power domains in low and active power states. More...
 
typedef uint8_t dif_pwrmgr_domain_config_t
 A set of domain options. More...
 
typedef enum dif_pwrmgr_wakeup_request_source dif_pwrmgr_wakeup_request_source_t
 A wakeup request source. More...
 
typedef enum dif_pwrmgr_reset_request_source dif_pwrmgr_reset_request_source_t
 A reset request source. More...
 
typedef uint32_t dif_pwrmgr_request_sources_t
 A set of request sources. More...
 
typedef enum dif_pwrmgr_wakeup_type dif_pwrmgr_wakeup_type_t
 A wakeup type. More...
 
typedef uint8_t dif_pwrmgr_wakeup_types_t
 A set of wakeup types. More...
 
typedef enum dif_pwrmgr_fatal_err_type dif_pwrmgr_fatal_err_type_t
 
typedef uint32_t dif_pwrmgr_fatal_err_codes_t
 A set of fatal errors. More...
 
typedef struct dif_pwrmgr_wakeup_reason dif_pwrmgr_wakeup_reason_t
 Wakeup types and requests from sources since the last time recording started.
 

Enumerations

enum  dif_pwrmgr_req_type {
  kDifPwrmgrReqTypeWakeup,
  kDifPwrmgrReqTypeReset
}
 A request type, i.e. More...
 
enum  dif_pwrmgr_domain_option {
  kDifPwrmgrDomainOptionCoreClockInLowPower = (1u << 0),
  kDifPwrmgrDomainOptionIoClockInLowPower = (1u << 1),
  kDifPwrmgrDomainOptionUsbClockInLowPower = (1u << 2),
  kDifPwrmgrDomainOptionUsbClockInActivePower = (1u << 3),
  kDifPwrmgrDomainOptionMainPowerInLowPower = (1u << 4)
}
 Options for enabling/disabling various clock and power domains in low and active power states. More...
 
enum  dif_pwrmgr_wakeup_request_source {
  kDifPwrmgrWakeupRequestSourceOne = (1u << 0),
  kDifPwrmgrWakeupRequestSourceTwo = (1u << 1),
  kDifPwrmgrWakeupRequestSourceThree = (1u << 2),
  kDifPwrmgrWakeupRequestSourceFour = (1u << 3),
  kDifPwrmgrWakeupRequestSourceFive = (1u << 4),
  kDifPwrmgrWakeupRequestSourceSix = (1u << 5)
}
 A wakeup request source. More...
 
enum  dif_pwrmgr_reset_request_source {
  kDifPwrmgrResetRequestSourceOne = (1u << 0),
  kDifPwrmgrResetRequestSourceTwo = (1u << 1)
}
 A reset request source. More...
 
enum  dif_pwrmgr_wakeup_type {
  kDifPwrmgrWakeupTypeRequest = (1u << 0),
  kDifPwrmgrWakeupTypeFallThrough = (1u << 1),
  kDifPwrmgrWakeupTypeAbort = (1u << 2)
}
 A wakeup type. More...
 
enum  dif_pwrmgr_fatal_err_type {
  kDifPwrmgrFatalErrTypeRegfileIntegrity = 1u << 0,
  kDifPwrmgrFatalErrTypeEscalationTimeout = 1u << 1,
  kDifPwrmgrFatalErrTypeMainPowerGlitch = 1u << 2
}
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_low_power_set_enabled (const dif_pwrmgr_t *pwrmgr, dif_toggle_t new_state, dif_toggle_t sync_state)
 Enables or disables low power state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_low_power_get_enabled (const dif_pwrmgr_t *pwrmgr, dif_toggle_t *cur_state)
 Checks whether low power state is enabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_set_domain_config (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_domain_config_t config, dif_toggle_t sync_state)
 Configures power manager to enable/disable various clock and power domains in low and active power states. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_domain_config (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_domain_config_t *config)
 Gets current power manager configuration. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_set_request_sources (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type, dif_pwrmgr_request_sources_t sources, dif_toggle_t sync_state)
 Sets sources enabled for a request type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_request_sources (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type, dif_pwrmgr_request_sources_t *sources)
 Gets sources enabled for a request type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_current_request_sources (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type, dif_pwrmgr_request_sources_t *sources)
 Gets request sources that are currently active for a request type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_request_sources_lock (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type)
 Locks sources of a request type. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_request_sources_is_locked (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_req_type_t req_type, bool *is_locked)
 Checks whether sources of a request type is locked. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_request_recording_set_enabled (const dif_pwrmgr_t *pwrmgr, dif_toggle_t new_state)
 Enables or disables recording of wakeup requests. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_request_recording_get_enabled (const dif_pwrmgr_t *pwrmgr, dif_toggle_t *cur_state)
 Checks whether wakeup requests are being recorded. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_reason_get (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_wakeup_reason_t *reason)
 Gets wakeup reason and source requests since the last time recording started. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_reason_clear (const dif_pwrmgr_t *pwrmgr)
 Clears wakeup reason(s) recorded since the last time recording started. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_fatal_err_code_get_codes (const dif_pwrmgr_t *pwrmgr, dif_pwrmgr_fatal_err_codes_t *codes)
 Read the fatal error codes. More...
 

Detailed Description

Power Manager Device Interface Functions

Definition in file dif_pwrmgr.h.


Data Structure Documentation

◆ dif_pwrmgr_wakeup_reason

struct dif_pwrmgr_wakeup_reason

Wakeup types and requests from sources since the last time recording started.

Definition at line 186 of file dif_pwrmgr.h.

Data Fields
dif_pwrmgr_request_sources_t request_sources Sources that requested wakeup since the last time recording started.
dif_pwrmgr_wakeup_types_t types Wakeup types since the last time recording started.

Typedef Documentation

◆ dif_pwrmgr_domain_config_t

typedef uint8_t dif_pwrmgr_domain_config_t

A set of domain options.

This type is used for specifying and querying which clock and power domains are enabled in low and active power states.

See also: dif_pwrmgr_domain_option_t.

Definition at line 79 of file dif_pwrmgr.h.

◆ dif_pwrmgr_domain_option_t

Options for enabling/disabling various clock and power domains in low and active power states.

Constants below are bitmasks that can be combined to define configurations.

See also: dif_pwrmgr_domain_config_t.

◆ dif_pwrmgr_fatal_err_codes_t

typedef uint32_t dif_pwrmgr_fatal_err_codes_t

A set of fatal errors.

This type is used to read the fatal error codes.

Definition at line 181 of file dif_pwrmgr.h.

◆ dif_pwrmgr_req_type_t

A request type, i.e.

wakeup or reset.

◆ dif_pwrmgr_request_sources_t

typedef uint32_t dif_pwrmgr_request_sources_t

A set of request sources.

This type is used for specifying which request sources are enabled for a particular request type, i.e. wakeup or reset, as well querying wakeup reasons.

See also: dif_pwrmgr_wakeup_request_source_t, dif_pwrmgr_reset_request_source_t.

Definition at line 125 of file dif_pwrmgr.h.

◆ dif_pwrmgr_reset_request_source_t

A reset request source.

Constants below are bitmasks that can be used to define sets of reset request sources.

See also: dif_pwrmgr_request_sources_t.

Note: This needs to be updated once the HW is finalized.

◆ dif_pwrmgr_wakeup_request_source_t

A wakeup request source.

Constants below are bitmasks that can be used to define sets of wakeup request sources.

See also: dif_pwrmgr_request_sources_t.

Note: This needs to be updated once the HW is finalized.

◆ dif_pwrmgr_wakeup_type_t

A wakeup type.

Constants below are bitmasks that can be used to define sets of wakeup types.

See also: dif_pwrmgr_wakeup_types_t.

◆ dif_pwrmgr_wakeup_types_t

typedef uint8_t dif_pwrmgr_wakeup_types_t

A set of wakeup types.

See also: dif_pwrmgr_wakeup_type_t.

Definition at line 159 of file dif_pwrmgr.h.

Enumeration Type Documentation

◆ dif_pwrmgr_domain_option

Options for enabling/disabling various clock and power domains in low and active power states.

Constants below are bitmasks that can be combined to define configurations.

See also: dif_pwrmgr_domain_config_t.

Enumerator
kDifPwrmgrDomainOptionCoreClockInLowPower 

Enable core clock in low power state.

kDifPwrmgrDomainOptionIoClockInLowPower 

Enable input/output (IO) clock in low power state.

kDifPwrmgrDomainOptionUsbClockInLowPower 

Enable USB clock in low power state.

kDifPwrmgrDomainOptionUsbClockInActivePower 

Enable USB clock in active power state.

kDifPwrmgrDomainOptionMainPowerInLowPower 

Enable main power domain in low power state.

Definition at line 48 of file dif_pwrmgr.h.

◆ dif_pwrmgr_fatal_err_type

Enumerator
kDifPwrmgrFatalErrTypeRegfileIntegrity 

A fatal error for regfile integrity.

kDifPwrmgrFatalErrTypeEscalationTimeout 

A fatal error for escalation timeout.

kDifPwrmgrFatalErrTypeMainPowerGlitch 

A fatal error for main power glitch.

Definition at line 161 of file dif_pwrmgr.h.

◆ dif_pwrmgr_req_type

A request type, i.e.

wakeup or reset.

Enumerator
kDifPwrmgrReqTypeWakeup 

A wakeup request.

kDifPwrmgrReqTypeReset 

A reset request.

Definition at line 29 of file dif_pwrmgr.h.

◆ dif_pwrmgr_reset_request_source

A reset request source.

Constants below are bitmasks that can be used to define sets of reset request sources.

See also: dif_pwrmgr_request_sources_t.

Note: This needs to be updated once the HW is finalized.

Definition at line 110 of file dif_pwrmgr.h.

◆ dif_pwrmgr_wakeup_request_source

A wakeup request source.

Constants below are bitmasks that can be used to define sets of wakeup request sources.

See also: dif_pwrmgr_request_sources_t.

Note: This needs to be updated once the HW is finalized.

Definition at line 91 of file dif_pwrmgr.h.

◆ dif_pwrmgr_wakeup_type

A wakeup type.

Constants below are bitmasks that can be used to define sets of wakeup types.

See also: dif_pwrmgr_wakeup_types_t.

Enumerator
kDifPwrmgrWakeupTypeRequest 

Wakeup due to a peripheral request.

kDifPwrmgrWakeupTypeFallThrough 

Despite low power mode being enabled and executing a wait for interrupt (WFI) instruction, an interrupt arrived at just the right time to break the executing core out of WFI.

kDifPwrmgrWakeupTypeAbort 

Despite low power mode being enabled and executing a wait for interrupt (WFI) instruction, an active flash, life cycle, or OTP operation was in progress when the power controller attempted to initiate low power entry.

Definition at line 134 of file dif_pwrmgr.h.

Function Documentation

◆ dif_pwrmgr_fatal_err_code_get_codes()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_fatal_err_code_get_codes ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_fatal_err_codes_t codes 
)

Read the fatal error codes.

Parameters
pwrmgrPower Manager Handle.
[out]codesThe fatal error codes.
Returns
The result of the operation.

Definition at line 456 of file dif_pwrmgr.c.

◆ dif_pwrmgr_get_current_request_sources()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_current_request_sources ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_req_type_t  req_type,
dif_pwrmgr_request_sources_t sources 
)

Gets request sources that are currently active for a request type.

Parameters
pwrmgrA power manager handle.
req_typeA request type.
[out]sourcesRequest sources that are currently active for the given request type.
Returns
The result of the operation.

Definition at line 342 of file dif_pwrmgr.c.

◆ dif_pwrmgr_get_domain_config()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_domain_config ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_domain_config_t config 
)

Gets current power manager configuration.

Parameters
pwrmgrA power manager handle.
[out]configCurrent configuration.
Returns
The result of the operation.

Definition at line 283 of file dif_pwrmgr.c.

◆ dif_pwrmgr_get_request_sources()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_get_request_sources ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_req_type_t  req_type,
dif_pwrmgr_request_sources_t sources 
)

Gets sources enabled for a request type.

A wakeup or reset request can be triggered by multiple sources, e.g. GPIO, watchdog timer, USB, etc. This function gets which sources are enabled for a particular request type.

Parameters
pwrmgrA power manager handle.
req_typeA request type.
[out]sourcesSources enabled for the given request type.
Returns
The result of the operation.

Definition at line 327 of file dif_pwrmgr.c.

◆ dif_pwrmgr_low_power_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_low_power_get_enabled ( const dif_pwrmgr_t pwrmgr,
dif_toggle_t cur_state 
)

Checks whether low power state is enabled.

Parameters
pwrmgrA power manager handle.
[out]cur_stateWhether low power state is enabled.
Returns
The result of the operation.

Definition at line 245 of file dif_pwrmgr.c.

◆ dif_pwrmgr_low_power_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_low_power_set_enabled ( const dif_pwrmgr_t pwrmgr,
dif_toggle_t  new_state,
dif_toggle_t  sync_state 
)

Enables or disables low power state.

When enabled, the power manager transitions to low power state on the next wait for interrupt (WFI) instruction. Since the hardware clears the corresponding bit automatically, this function must be called before each transition to low power state.

This function can be configured to skip synchronization to the slow clock domain, under the assumption that timely synchronization will be performed by some of the other functions that can trigger it.

Parameters
pwrmgrA power manager handle.
new_stateWhether low power state is enabled.
sync_stateWhether to wait for state to transfer to slow domain
Returns
The result of the operation.

Definition at line 220 of file dif_pwrmgr.c.

◆ dif_pwrmgr_request_sources_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_request_sources_is_locked ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_req_type_t  req_type,
bool *  is_locked 
)

Checks whether sources of a request type is locked.

Parameters
pwrmgrA power manager handle.
req_typeA request type.
[out]is_lockedWhether sources of the given request type is locked.
Returns
The result of the operation.

Definition at line 371 of file dif_pwrmgr.c.

◆ dif_pwrmgr_request_sources_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_request_sources_lock ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_req_type_t  req_type 
)

Locks sources of a request type.

Once the sources of a particular request type is locked, they cannot be changed until the hardware is reset.

Parameters
pwrmgrA power manager handle.
req_typeA request type.
Returns
The result of the operation.

Definition at line 357 of file dif_pwrmgr.c.

◆ dif_pwrmgr_set_domain_config()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_set_domain_config ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_domain_config_t  config,
dif_toggle_t  sync_state 
)

Configures power manager to enable/disable various clock and power domains in low and active power states.

This function can be configured to skip synchronization to the slow clock domain, under the assumption that timely synchronization will be performed by some of the other functions that can trigger it.

Parameters
pwrmgrA power manager handle.
configA domain configuration.
sync_stateWhether to wait for state to transfer to slow domain
Returns
The result of the operation.

Definition at line 259 of file dif_pwrmgr.c.

◆ dif_pwrmgr_set_request_sources()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_set_request_sources ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_req_type_t  req_type,
dif_pwrmgr_request_sources_t  sources,
dif_toggle_t  sync_state 
)

Sets sources enabled for a request type.

A wakeup or reset request can be triggered by multiple sources, e.g. GPIO, watchdog timer, USB, etc. This function sets which sources are enabled for a particular request type.

This function can be configured to skip synchronization to the slow clock domain, under the assumption that timely synchronization will be performed by some of the other functions that can trigger it.

Parameters
pwrmgrA power manager handle.
req_typeA request type.
sourcesSources enabled for the given request type.
sync_stateWhether to wait for state to transfer to slow domain
Returns
The result of the operation.

Definition at line 297 of file dif_pwrmgr.c.

◆ dif_pwrmgr_wakeup_reason_clear()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_reason_clear ( const dif_pwrmgr_t pwrmgr)

Clears wakeup reason(s) recorded since the last time recording started.

Parameters
pwrmgrA power manager handle.
Returns
The result of the operation.

Definition at line 445 of file dif_pwrmgr.c.

◆ dif_pwrmgr_wakeup_reason_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_reason_get ( const dif_pwrmgr_t pwrmgr,
dif_pwrmgr_wakeup_reason_t reason 
)

Gets wakeup reason and source requests since the last time recording started.

Power manager automatically starts recording wakeup requests when it begins a valid low power entry. Recording continues until it is explicitly disabled by calling dif_pwrmgr_wakeup_request_recording_set_enabled. Thus, it is possible to record wakeup requests from multiple sources as well as multiple wakeup types.

Parameters
pwrmgrA power manager handle.
[out]reasonWakeup reasons.
Returns
The result of the operation.

Definition at line 414 of file dif_pwrmgr.c.

◆ dif_pwrmgr_wakeup_request_recording_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_request_recording_get_enabled ( const dif_pwrmgr_t pwrmgr,
dif_toggle_t cur_state 
)

Checks whether wakeup requests are being recorded.

Parameters
pwrmgrA power manager handle.
[out]cur_stateWhether wakeup requests are being recorded.
Returns
The result of the operation.

Definition at line 399 of file dif_pwrmgr.c.

◆ dif_pwrmgr_wakeup_request_recording_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwrmgr_wakeup_request_recording_set_enabled ( const dif_pwrmgr_t pwrmgr,
dif_toggle_t  new_state 
)

Enables or disables recording of wakeup requests.

Power manager automatically starts recording wakeup requests when it begins a valid low power entry. Recording continues until it is explicitly disabled by calling this function.

Parameters
pwrmgrA power manager handle.
new_stateWhether wakeup requests should be recorded.
Returns
The result of the operation.

Definition at line 383 of file dif_pwrmgr.c.