.. todo:: This needs to be updated to account for the different governors besides the activity-based one.
NuttX supports a simple power management (PM) sub-system which:
- Monitors activity from drivers (and from other parts of the system), and
- Provides hooks to place drivers (and the whole system) into reduce power modes of operation.
The PM sub-system integrates the MCU idle loop with a collection of device drivers to support:
- Reports of relevant driver or other system activity.
- Registration and callback mechanism to interface with individual device drivers.
- IDLE time polling of overall driver activity.
- Coordinated, global, system-wide transitions to lower power usage states.
Low Power Consumption States. Various "sleep" and low power consumption states have various names and are sometimes used in conflicting ways. In the NuttX PM logic, we will use the following terminology:
NORMAL- The normal, full power operating mode.
IDLE- This is still basically normal operational mode, the system is, however,
IDLEand some simple simple steps to reduce power consumption provided that they do not interfere with normal Operation. Simply dimming the a backlight might be an example some that that would be done when the system is idle.STANDBY- Standby is a lower power consumption mode that may involve more extensive power management steps such has disabling clocking or setting the processor into reduced power consumption modes. In this state, the system should still be able to resume normal activity almost immediately.
SLEEP- The lowest power consumption mode. The most drastic power reduction measures possible should be taken in this state. It may require some time to get back to normal operation from
SLEEP(some MCUs may even require going through reset).
.. c:enum:: pm_state_e These various states are represented with type :c:enum:`pm_state_e` in ``include/nuttx/power/pm.h``.
Power Management Domains. Each PM interfaces includes a
integer domain number. By default, only a single power domain is
supported (CONFIG_PM_NDOMAINS=1). But that is configurable;
any number of PM domains can be supported. Multiple PM domains
might be useful, for example, if you would want to control power
states associated with a network separately from power states
associated with a user interface.
All PM interfaces are declared in the file include/nuttx/power/pm.h.
.. c:function:: void pm_initialize(void) Called by MCU-specific one-time logic at power-on-reset in order to initialize the power management capabilities. This function must be called *very* early in the initialization sequence *before* any other device drivers are initialized (since they may attempt to register with the power management subsystem).
.. c:function:: int pm_register(FAR struct pm_callback_s *callbacks)
Called by a device driver in
order to register to receive power management event callbacks.
Refer to the :ref:`components/power:Callbacks` section for more
details.
:param callbacks:
An instance of :c:struct:`pm_callback_s`
providing the driver callback functions.
:return:
Zero (``OK``) on success; otherwise a negated
``errno`` value is returned.
.. c:function:: int pm_unregister(FAR struct pm_callback_s *callbacks)
Called by a device driver in
order to unregister previously registered power management event
callbacks. Refer to the :ref:`components/power:Callbacks` section for
more details.
**Input Parameters:**
:param callbacks:
An instance of :c:struct:`pm_callback_s`
providing the driver callback functions.
:return:
Zero (``OK``) on success; otherwise a negated
``errno`` value is returned.
.. c:function:: void pm_activity(int domain, int priority)
Called by a device driver to
indicate that it is performing meaningful activities (non-idle).
This increment an activity count and/or will restart a idle timer
and prevent entering reduced power states.
:param domain: Identifies the domain of the new PM activity
:param priority:
Activity priority, range 0-9. Larger values correspond to
higher priorities. Higher priority activity can prevent the
system from entering reduced power states for a longer period
of time. As an example, a button press might be higher priority
activity because it means that the user is actively interacting
with the device.
**Assumptions:** This function may be called from an interrupt
handler (this is the ONLY PM function that may be called from an
interrupt handler!).
.. c:function:: enum pm_state_e pm_checkstate(int domain)
Called from the MCU-specific
IDLE loop to monitor the power management conditions. This
function returns the "recommended" power management state based on
the PM configuration and activity reported in the last sampling
periods. The power management state is not automatically changed,
however. The IDLE loop must call :c:func:`pm_changestate` in order to
make the state change.
These two steps are separated because the platform-specific IDLE
loop may have additional situational information that is not
available to the PM sub-system. For example, the IDLE loop may
know that the battery charge level is very low and may force lower
power states even if there is activity.
NOTE: That these two steps are separated in time and, hence, the
IDLE loop could be suspended for a long period of time between
calling :c:func:`pm_checkstate` and :c:func:`pm_changestate`. The IDLE
loop may need to make these calls atomic by either disabling
interrupts until the state change is completed.
:param domain: Identifies the PM domain to check
:return: The recommended power management state.
.. c:function:: int pm_changestate(int domain, enum pm_state_e newstate)
This function is used by platform-specific power
management logic. It will announce the power management power
management state change to all drivers that have registered for
power management event callbacks.
:param domain: Identifies the domain of the new PM state
:param newstate: Identifies the new PM state
:return:
0 (``OK``) means that the callback function
for all registered drivers returned ``OK`` (meaning that they
accept the state change). Non-zero means that one of the drivers
refused the state change. In this case, the system will revert to
the preceding state.
**Assumptions:** It is assumed that interrupts are disabled when
this function is called. This function is probably called from the
IDLE loop... the lowest priority task in the system. Changing
driver power management states may result in renewed system
activity and, as a result, can suspend the IDLE thread before it
completes the entire state change unless interrupts are disabled
throughout the state change.
.. c:struct:: pm_callback_s This struct includes the pointers to the driver callback functions. This structure is defined ``include/nuttx/power/pm.h``. These callback functions can be used to provide power management information to the driver.
.. c:var:: int (*prepare)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate)
Request the driver to prepare for a new power
state. This is a warning that the system is about to enter into a
new power state. The driver should begin whatever operations that
may be required to enter power state. The driver may abort the
state change mode by returning a non-zero value from the callback
function.
:param cb:
Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at
the end of the structure.
:param domain:
Identifies the activity domain of the state change
:param pmstate:
Identifies the new PM state
:return:
Zero (``OK``) means the event was successfully
processed and that the driver is prepared for the PM state change.
Non-zero means that the driver is not prepared to perform the
tasks needed achieve this power setting and will cause the state
change to be aborted. NOTE: The ``prepare()`` method will also be
called when reverting from lower back to higher power consumption
modes (say because another driver refused a lower power state
change). Drivers are not permitted to return non-zero values when
reverting back to higher power consumption modes!
.. c:var:: void (*notify)(FAR struct pm_callback_s *cb, int domain, enum pm_state_e pmstate)
Notify the driver of new power state. This
callback is called after all drivers have had the opportunity to
prepare for the new power state.
:param cb:
Returned to the driver. The driver version of the callback
structure may include additional, driver-specific state data at
the end of the structure.
:param domain:
Identifies the activity domain of the state change
:param pmstate:
Identifies the new PM state
The driver already agreed to transition
to the low power consumption state when when it returned ``OK`` to
the :c:var:`prepare` call.