Power Manager#

sl_power_state_t#

sl_power_state_t

Enumeration for the power states.

sl_clock_scaling_t#

sl_clock_scaling_t

Enumeration for clock scaling parameters.

sl_si91x_power_manager_on_isr_exit_t#

sl_si91x_power_manager_on_isr_exit_t

On ISR Exit Hook answer.

sl_power_manager_ps_transition_event_t#

typedef uint32_t sl_power_manager_ps_transition_event_t

Mask of all the event(s) to listen to.

sl_power_manager_ps_transition_on_event_t#

typedef void(* sl_power_manager_ps_transition_on_event_t) (sl_power_state_t from, sl_power_state_t to) )(sl_power_state_t from, sl_power_state_t to)

Typedef for the user-supplied callback function which is called when a power state transition occurs.

This typedef defines a callback function that is called when a power state transition occurs.

sl_si91x_power_manager_init#

sl_status_t sl_si91x_power_manager_init (void )

To initialize the Power Manager service.

Configures the PS4 state with a 100 MHz system clock.

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_ALREADY_INITIALIZED - Power Manager is already initialized.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_core_entercritical#

__STATIC_INLINE void sl_si91x_power_manager_core_entercritical (void )

To disable the interrupts.

Disables all interrupts by setting PRIMASK. Fault exception handlers will still be enabled.

sl_si91x_power_manager_core_exitcritical#

__STATIC_INLINE void sl_si91x_power_manager_core_exitcritical (void )

To enable the interrupts.

Enables interrupts by clearing PRIMASK.

sl_si91x_power_manager_add_ps_requirement#

__STATIC_INLINE sl_status_t sl_si91x_power_manager_add_ps_requirement (sl_power_state_t state)

To add a requirement on power states.

The default state for the Power Manager is PS4. If any requirements are added, the Power Manager switches to the state if it is a valid transition. Before transitioning from one state to another, make sure to remove requirements of previous states if any were added. If an invalid state requirement is added, it returns SL_STATUS_INVALID_PARAMETER. If the Power Manager service is not initialized, it returns SL_STATUS_NOT_INITIALIZED. To initialize, call sl_si91x_power_manager_init. To get the requirements on all power states, call sl_si91x_power_manager_get_requirement_table. To know the current power state, use sl_si91x_power_manager_get_current_state.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_remove_ps_requirement#

__STATIC_INLINE sl_status_t sl_si91x_power_manager_remove_ps_requirement (sl_power_state_t state)

To remove requirement on power states.

Default state for Power Manager is PS4. Removing requirement will not impact on power state transitions. If the current state is PS4 and no other requirements are added, and PS4 requirement is removed then it returns SL_STATUS_INVALID_PARAMETER. If the Power Manager service is not initialized then it returns SL_STATUS_NOT_INITIALIZED, to initialize call sl_si91x_power_manager_init. To get the requirements on all power states, call sl_si91x_power_manager_get_requirement_table. To know the current power state, use sl_si91x_power_manager_get_current_state.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• sl_status_t Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - The Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_set_clock_scaling#

sl_status_t sl_si91x_power_manager_set_clock_scaling (sl_clock_scaling_t mode)

To configure the clock scaling.

PS4 and PS3 states are supported only. Possible values for clock scaling are:

• POWERSAVE and PERFORMANCE

• PS4 Performance: 180 MHz clock

• PS4 Power-save: 100 MHz clock

• PS3 Performance: 80 MHz clock

• PS3 Power-save: 40 MHz clock

• For PS2 state, 20 MHz clock is default.

If the Power Manager service is not initialized, it returns SL_STATUS_NOT_INITIALIZED. To initialize, call sl_si91x_power_manager_init.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

  • SL_STATUS_INVALID_CONFIGURATION - Invalid configuration of mode.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_get_clock_scaling#

sl_clock_scaling_t sl_si91x_power_manager_get_clock_scaling (void )

the clock scaling mode in PS4 and PS3 power state.

Possible return values: * SL_SI91X_POWER_MANAGER_POWERSAVE (Minimum supported frequency in a power state) SL_SI91X_POWER_MANAGER_PERFORMANCE (Maximum supported frequency in a power state)

Returns

• The following values are returned:

  • sl_clock_scaling_t enum value indicating current clock scaling mode

sl_si91x_power_manager_add_peripheral_requirement#

sl_status_t sl_si91x_power_manager_add_peripheral_requirement (sl_power_peripheral_t * peripheral)

Adds the peripheral requirement.

Power on the peripherals the valid peripherals passed in the structure. Structure member possible values: sl_power_peripheral_t

• m4ss_peripheral -> Accepts masked value of m4ss peripherals.

• ulpss_peripheral -> Accepts masked value of ulpss peripherals.

• npss_peripheral -> Accepts masked value of npss peripherals. The values of enums can be combined by using 'OR' operator and then passed to the variable.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_INVALID_STATE (0x0002) - Not a valid transition.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_remove_peripheral_requirement#

sl_status_t sl_si91x_power_manager_remove_peripheral_requirement (sl_power_peripheral_t * peripheral)

To remove the peripheral requirement.

Powers off the peripherals specified in the structure. Valid peripherals are passed in the structure sl_power_peripheral_t. The structure members can have the following values:

• m4ss_peripheral -> Accepts masked value of M4SS peripherals.

• ulpss_peripheral -> Accepts masked value of ULPSS peripherals.

• npss_peripheral -> Accepts masked value of NPSS peripherals.

The values of enums can be combined using the 'OR' operator and then passed to the variable.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_subscribe_ps_transition_event#

sl_status_t sl_si91x_power_manager_subscribe_ps_transition_event (sl_power_manager_ps_transition_event_handle_t * event_handle, const sl_power_manager_ps_transition_event_info_t * event_info)

To register a callback to be called on given power state transition(s).

If the Power Manager service is not initialized, it returns SL_STATUS_NOT_INITIALIZED. To initialize, call sl_si91x_power_manager_init.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_NULL_POINTER - Null pointer is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

Note

• Adding and removing power state transition requirement(s) from a callback on a transition event is not supported.

• The parameters passed must be persistent, meaning that they need to survive until the callback fires.

• An ASSERT is thrown if the handle is not found.

Usage example:

#define PS_EVENT_MASK          (  SL_POWER_MANAGER_EVENT_TRANSITION_ENTERING_PS4 \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_LEAVING_PS4  \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_ENTERING_PS3 \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_LEAVING_PS3  \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_ENTERING_PS2 \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_LEAVING_PS2  \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_ENTERING_PS0 \
                                | SL_POWER_MANAGER_EVENT_TRANSITION_LEAVING_SLEEP)

sl_power_manager_ps_transition_event_handle_t handle;
sl_power_manager_ps_transition_event_info_t info = { .event_mask = PS_EVENT_MASK,
                                                     .on_event   = transition_callback };

void transition_callback(sl_power_state_t from, sl_power_state_t to)
{
  [...]
}

void main(void)
{
  sl_status_t status;

  status = sl_si91x_power_manager_init();
  // Validate the status

  status = sl_si91x_power_manager_subscribe_ps_transition_event(&handle, &info);
  // Validate the status
}

sl_si91x_power_manager_unsubscribe_ps_transition_event#

sl_status_t sl_si91x_power_manager_unsubscribe_ps_transition_event (sl_power_manager_ps_transition_event_handle_t * event_handle, const sl_power_manager_ps_transition_event_info_t * event_info)

To unregister an event callback handle on power state transition.

If the Power Manager service is not initialized, it returns SL_STATUS_NOT_INITIALIZED. To initialize, call sl_si91x_power_manager_init.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_NULL_POINTER - Null pointer is passed. For more information on status codes, see SL STATUS DOCUMENTATION.

For more information on status codes, refer to SL STATUS DOCUMENTATION. Note

• An ASSERT is thrown if the handle is not found.

sl_si91x_power_manager_sleep#

sl_status_t sl_si91x_power_manager_sleep (void )

To move into sleep mode and wait for the peripheral to be set as a wakeup source to trigger and wake up the M4 SoC.

It supports PS4, PS3, and PS2 only; it cannot enter sleep mode from any other active states. If any error occurs, it returns the error code and does not transition to sleep mode.

Note

• This function expects and calls a callback with the following signature: boolean_t sl_si91x_power_manager_is_ok_to_sleep(void). This function can be used to cancel a sleep action and handle the possible race condition where an ISR that would cause a wakeup is triggered right after the decision to call sl_si91x_power_manager_sleep() has been made.

This function also expects and calls a callback with the following signature: boolean_t sl_si91x_power_manager_isr_wakeup(void) after wakeup from sleep. The possible return values are:

• SL_SI91X_POWER_MANAGER_ISR_IGNORE

• SL_SI91X_POWER_MANAGER_ISR_SLEEP

• SL_SI91X_POWER_MANAGER_ISR_WAKEUP

Note

• It can end up in an infinite sleep-wakeup loop if continuously SL_SI91X_POWER_MANAGER_ISR_SLEEP return value is passed.

• Pre-conditions:

  • sl_si91x_power_manager_init

  • sl_si91x_power_manager_configure_ram_retention

  • sl_si91x_power_manager_set_wakeup_sources

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

  • SL_STATUS_INVALID_STATE (0x0002) - Not a valid transition.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_standby#

void sl_si91x_power_manager_standby (void )

To move into standby state and wait for the interrupt.

Standby transition is possible from PS4, PS3, and PS2 states only. Transition from sleep, PS1, or PS0 is not supported.

• Pre-conditions:

  • sl_si91x_power_manager_init

sl_si91x_power_manager_set_wakeup_sources#

sl_status_t sl_si91x_power_manager_set_wakeup_sources (uint32_t source, boolean_t add)

To configure the wakeup sources.

One or many wakeup sources can be configured using a logical 'OR' operation. The initialization of the peripheral configured as a wakeup source needs to be performed by the user. The Power Manager only sets it as a wakeup source.

• Pre-conditions:

  • sl_si91x_power_manager_init

  • sl_si91x_power_manager_configure_ram_retention

• • sl_si91x_power_manager_sleep

  • sl_si91x_power_manager_standby

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_INVALID_PARAMETER - Invalid parameter is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_configure_ram_retention#

sl_status_t sl_si91x_power_manager_configure_ram_retention (sl_power_ram_retention_config_t * config)

To retain the RAM in low power state either by using size or RAM bank as input parameters.

Structure member possible values: sl_power_ram_retention_config_t

• configure_ram_banks -> Boolean to switch between RAM Bank retentions. Either by size or by RAM bank number.

  • Enable -> Use RAM Bank Number.

  • Disable -> Use Size.

• m4ss_ram_size_kb -> Retains M4SS RAM banks according to the size.

  • Less than 320 KB (Enter 100 for 100 KB).

• ulpss_ram_size_kb -> Retains ULPSS RAM banks according to the size.

  • Less than 8 KB (Enter 5 for 5 KB).

• ram_bank_number -> Retains the M4SS and ULPSS RAM Bank using bank number.

• Pre-conditions:

  • sl_si91x_power_manager_init

• sl_si91x_power_manager_sleep

Returns

• Status code indicating the result:

  • SL_STATUS_OK - Success.

  • SL_STATUS_NOT_INITIALIZED - Power Manager is not initialized.

  • SL_STATUS_NULL_POINTER - Null pointer is passed.

For more information on status codes, see [SL STATUS DOCUMENTATION](

sl_si91x_power_manager_get_current_state#

sl_power_state_t sl_si91x_power_manager_get_current_state (void )

To return the current power state.

Possible return values:

• 2: SL_POWER_MANAGER_PS2, ///< PS2 Power State

• 3: SL_POWER_MANAGER_PS3, ///< PS3 Power State

• 4: SL_POWER_MANAGER_PS4, ///< PS4 Power State

Returns

• sl_power_state_t enum value indicating the current power state.

sl_si91x_power_manager_get_requirement_table#

uint8_t * sl_si91x_power_manager_get_requirement_table (void )

To get the current requirements on all the power states.

It returns 5 values starting from PS0 to PS4.

• Pre-conditions:

  • sl_si91x_power_manager_init

Returns

• Pointer to a uint8_t type array which contains 5 elements.

Usage example:

void main()
{
  uint8_t *requirement_table;
  sl_si91x_power_manager_init();
  requirement_table = sl_si91x_power_manager_get_requirement_table();
  DEBUGOUT("PS4: %d, PS3: %d, PS2: %d, PS1: %d, PS0: %d", 
           requirement_table[4], 
           requirement_table[3], 
           requirement_table[2], 
           requirement_table[1], 
           requirement_table[0]); 
}

sl_si91x_power_manager_deinit#

void sl_si91x_power_manager_deinit (void )

To de-initialize the Power Manager service.

It clears all the power requirements and callback event subscriptions. If the Power Manager service is not initialized, it returns SL_STATUS_NOT_INITIALIZED. To initialize, call sl_si91x_power_manager_init.

• Pre-conditions:

  • sl_si91x_power_manager_init

sl_si91x_power_manager_debug_print_ps_requirements#

void sl_si91x_power_manager_debug_print_ps_requirements (void )

To print a table that describes the current requirements on each power state and their owner.