v2.0.0
Enumerations | Functions
hardware_powman
Hardware APIs

Power Management API. More...

## Enumerations
enum | powman_power_domains { POWMAN_POWER_DOMAIN_SRAM_BANK1 = 0 , POWMAN_POWER_DOMAIN_SRAM_BANK0 = 1 , POWMAN_POWER_DOMAIN_XIP_CACHE = 2 , POWMAN_POWER_DOMAIN_SWITCHED_CORE = 3 , POWMAN_POWER_DOMAIN_COUNT = 4 }
| Power domains of powman. More...

## Functions
void | powman_timer_set_1khz_tick_source_lposc (void)
| Use the ~32KHz low power oscillator as the powman timer source.
void | powman_timer_set_1khz_tick_source_lposc_with_hz (uint32_t lposc_freq_hz)
| Use the low power oscillator (specifying frequency) as the powman timer source. More...
void | powman_timer_set_1khz_tick_source_xosc (void)
| Use the crystal oscillator as the powman timer source.
void | powman_timer_set_1khz_tick_source_xosc_with_hz (uint32_t xosc_freq_hz)
| Use the crystal oscillator as the powman timer source. More...
void | powman_timer_set_1khz_tick_source_gpio (uint32_t gpio)
| Use a 1KHz external tick as the powman timer source. More...
void | powman_timer_enable_gpio_1hz_sync (uint32_t gpio)
| Use a 1Hz external signal as the powman timer source for seconds only. More...
void | powman_timer_disable_gpio_1hz_sync (void)
| Stop using 1Hz external signal as the powman timer source for seconds.
uint64_t | powman_timer_get_ms (void)
| Returns current time in ms.
void | powman_timer_set_ms (uint64_t time_ms)
| Set current time in ms. More...
void | powman_timer_enable_alarm_at_ms (uint64_t alarm_time_ms)
| Set an alarm at an absolute time in ms. More...
void | powman_timer_disable_alarm (void)
| Disable the alarm. More...
static void | powman_set_bits (volatile uint32_t *reg, uint32_t bits)
| hw_set_bits helper function More...
static void | powman_clear_bits (volatile uint32_t *reg, uint32_t bits)
| hw_clear_bits helper function More...
static bool | powman_timer_is_running (void)
| Determine if the powman timer is running.
static void | powman_timer_stop (void)
| Stop the powman timer.
static void | powman_timer_start (void)
| Start the powman timer.
static void | powman_clear_alarm (void)
| Clears the powman alarm. More...
powman_power_state | powman_get_power_state (void)
| Get the current power state.
int | powman_set_power_state (powman_power_state state)
| Set the power state. More...
static powman_power_state | powman_power_state_with_domain_on (powman_power_state orig, enum powman_power_domains domain)
| Helper function modify a powman_power_state to turn a domain on. More...
static powman_power_state | powman_power_state_with_domain_off (powman_power_state orig, enum powman_power_domains domain)
| Helper function modify a powman_power_state to turn a domain off. More...
static bool | powman_power_state_is_domain_on (powman_power_state state, enum powman_power_domains domain)
| Helper function to check if a domain is on in a given powman_power_state. More...
void | powman_enable_alarm_wakeup_at_ms (uint64_t alarm_time_ms)
| Wake up from an alarm at a given time. More...
void | powman_enable_gpio_wakeup (uint gpio_wakeup_num, uint32_t gpio, bool edge, bool high)
| Wake up from a gpio. More...
void | powman_disable_alarm_wakeup (void)
| Disable waking up from alarm.
void | powman_disable_gpio_wakeup (uint gpio_wakeup_num)
| Disable wake up from a gpio. More...
void | powman_disable_all_wakeups (void)
| Disable all wakeup sources.
bool | powman_configure_wakeup_state (powman_power_state sleep_state, powman_power_state wakeup_state)
| Configure sleep state and wakeup state. More...
static void | powman_set_debug_power_request_ignored (bool ignored)
| Ignore wake up when the debugger is attached. More...

## Detailed Description

Power Management API.

## Enumeration Type Documentation

## ◆ powman_power_domains

enum powman_power_domains

Power domains of powman.

Enumerator
POWMAN_POWER_DOMAIN_SRAM_BANK1 | bank1 includes the top 256K of sram plus sram 8 and 9 (scratch x and scratch y)
POWMAN_POWER_DOMAIN_SRAM_BANK0 | bank0 is bottom 256K of sSRAM
POWMAN_POWER_DOMAIN_XIP_CACHE | XIP cache is 2x8K instances.
POWMAN_POWER_DOMAIN_SWITCHED_CORE | Switched core logic (processors, busfabric, peris etc)

## Function Documentation

## ◆ powman_clear_alarm()

static void powman_clear_alarm | ( | void |  | ) |
| inlinestatic

Clears the powman alarm.

Note, the alarm must be disabled (see powman_timer_disable_alarm) before clearing the alarm, as the alarm fires if the time is greater than equal to the target, so once the time has passed the alarm will always fire while enabled.

## ◆ powman_clear_bits()

static void powman_clear_bits | ( | volatile uint32_t * | reg,
|  | uint32_t | bits
| ) |  |
| inlinestatic

hw_clear_bits helper function

Powman needs a password for writes, to prevent accidentally writing to it. This function implements hw_clear_bits with an appropriate password.

Parameters

  reg | register to clear
  bits | bits of register to clear

## ◆ powman_configure_wakeup_state()

bool powman_configure_wakeup_state | ( | powman_power_state | sleep_state,
|  | powman_power_state | wakeup_state
| ) |  |

Configure sleep state and wakeup state.

Parameters

  sleep_state | power state powman will go to when sleeping, used to validate the wakeup state
  wakeup_state | power state powman will go to when waking up. Note switched core and xip always power up. SRAM bank0 and bank1 can be left powered off

Returns
  true if the state is valid, false if not

## ◆ powman_disable_gpio_wakeup()

void powman_disable_gpio_wakeup | ( | uint | gpio_wakeup_num | ) |

Disable wake up from a gpio.

Parameters

  gpio_wakeup_num | hardware wakeup instance to use (0-3)

## ◆ powman_enable_alarm_wakeup_at_ms()

void powman_enable_alarm_wakeup_at_ms | ( | uint64_t | alarm_time_ms | ) |

Wake up from an alarm at a given time.

Parameters

  alarm_time_ms | time to wake up in ms

## ◆ powman_enable_gpio_wakeup()

void powman_enable_gpio_wakeup | ( | uint | gpio_wakeup_num,
|  | uint32_t | gpio,
|  | bool | edge,
|  | bool | high
| ) |  |

Wake up from a gpio.

Parameters

  gpio_wakeup_num | hardware wakeup instance to use (0-3)
  gpio | gpio to wake up from (0-47)
  edge | true for edge sensitive, false for level sensitive
  high | true for active high, false active low

## ◆ powman_power_state_is_domain_on()

static bool powman_power_state_is_domain_on | ( | powman_power_state | state,
|  | enum powman_power_domains | domain
| ) |  |
| inlinestatic

Helper function to check if a domain is on in a given powman_power_state.

Parameters

  state | powman_power_state
  domain | domain to check is on

## ◆ powman_power_state_with_domain_off()

static powman_power_state powman_power_state_with_domain_off | ( | powman_power_state | orig,
|  | enum powman_power_domains | domain
| ) |  |
| inlinestatic

Helper function modify a powman_power_state to turn a domain off.

Parameters

  orig | original state
  domain | domain to turn off

## ◆ powman_power_state_with_domain_on()

static powman_power_state powman_power_state_with_domain_on | ( | powman_power_state | orig,
|  | enum powman_power_domains | domain
| ) |  |
| inlinestatic

Helper function modify a powman_power_state to turn a domain on.

Parameters

  orig | original state
  domain | domain to turn on

## ◆ powman_set_bits()

static void powman_set_bits | ( | volatile uint32_t * | reg,
|  | uint32_t | bits
| ) |  |
| inlinestatic

hw_set_bits helper function

Parameters

  reg | register to set
  bits | bits of register to set Powman needs a password for writes, to prevent accidentally writing to it. This function implements hw_set_bits with an appropriate password.

## ◆ powman_set_debug_power_request_ignored()

static void powman_set_debug_power_request_ignored | ( | bool | ignored | ) |
| inlinestatic

Ignore wake up when the debugger is attached.

Typically, when a debugger is attached it will assert the pwrupreq signal. OpenOCD does not clear this signal, even when you quit. This means once you have attached a debugger powman will never go to sleep. This function lets you ignore the debugger pwrupreq which means you can go to sleep with a debugger attached. The debugger will error out if you go to turn off the switch core with it attached, as the processors have been powered off.

Parameters

  ignored | should the debugger power up request be ignored

## ◆ powman_set_power_state()

int powman_set_power_state | ( | powman_power_state | state | ) |

Set the power state.

Check the desired state is valid. Powman will go to the state if it is valid and there are no pending power up requests.

Note that if you are turning off the switched core then this function will never return as the processor will have been turned off at the end.

Parameters

  state | the power state to go to

Returns
  PICO_OK if the state is valid. Misc PICO_ERRORs are returned if not

## ◆ powman_timer_disable_alarm()

void powman_timer_disable_alarm | ( | void |  | ) |

Disable the alarm.

Once an alarm has fired it must be disabled to stop firing as the alarm comparison is alarm = alarm_time >= current_time

## ◆ powman_timer_enable_alarm_at_ms()

void powman_timer_enable_alarm_at_ms | ( | uint64_t | alarm_time_ms | ) |

Set an alarm at an absolute time in ms.

Note, the timer is stopped and then restarted as part of this function. This only controls the alarm if you want to use the alarm to wake up powman then you should use powman_enable_alarm_wakeup_at_ms

Parameters

  alarm_time_ms | time at which the alarm will fire

## ◆ powman_timer_enable_gpio_1hz_sync()

void powman_timer_enable_gpio_1hz_sync | ( | uint32_t | gpio | ) |

Use a 1Hz external signal as the powman timer source for seconds only.

Use a 1hz sync signal, such as from a gps for the seconds component of the timer. The milliseconds will still come from another configured source such as xosc or lposc

Parameters

  gpio | the gpio to use. must be 12, 14, 20, 22

## ◆ powman_timer_set_1khz_tick_source_gpio()

void powman_timer_set_1khz_tick_source_gpio | ( | uint32_t | gpio | ) |

Use a 1KHz external tick as the powman timer source.

Parameters

  gpio | the gpio to use. must be 12, 14, 20, 22

## ◆ powman_timer_set_1khz_tick_source_lposc_with_hz()

void powman_timer_set_1khz_tick_source_lposc_with_hz | ( | uint32_t | lposc_freq_hz | ) |

Use the low power oscillator (specifying frequency) as the powman timer source.

Parameters

  lposc_freq_hz | specify an exact lposc freq to trim it

## ◆ powman_timer_set_1khz_tick_source_xosc_with_hz()

void powman_timer_set_1khz_tick_source_xosc_with_hz | ( | uint32_t | xosc_freq_hz | ) |

Use the crystal oscillator as the powman timer source.

Parameters

  xosc_freq_hz | specify a crystal frequency

## ◆ powman_timer_set_ms()

void powman_timer_set_ms | ( | uint64_t | time_ms | ) |

Set current time in ms.

Parameters

  time_ms | Current time in ms