adafruit-mirror/zephyr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 9

doc: pm: Add information about device and system constraint

Browse source 
Add information about device power management and system power
management constarints.

Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
This commit is contained in:
Flavio Ceolin 2024-05-30 10:28:06 -07:00 committed by Anas Nashif
parent 73b755d817
commit 9ba65abcb3
2 changed files with 92 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
doc/services/pm/device.rst
View file

@ -307,6 +307,96 @@ the system will not do power management on it. After the device is no
longer doing an operation and can be suspended, it should call
:c:func:`pm_device_busy_clear`.
.. _pm-device-constraint:
Device Power Management X System Power Management
*************************************************
When managing power in embedded systems, it's crucial to understand
the interplay between device power state and the overall system power
state. Some devices may have dependencies on the system power
state. For example, certain low-power states of the SoC might not
supply power to peripheral devices, leading to problems if the device
is in the middle of an operation. Proper coordination is essential to
maintain system stability and data integrity.
To avoid this sort of problem, devices must :ref:`get and release lock <pm-policy-power-states>`
power states that cause power loss during an operation.
Zephyr provides a mechanism for devices to declare which power states cause power
loss and an API that automatically get and put lock on them. This feature is
enabled setting :kconfig:option:`CONFIG_PM_POLICY_DEVICE_CONSTRAINTS` to ``y``.
Once this feature is enabled, devices must declare in devicetree which
states cause power loss. In the following example, device ``test_dev``
says that power states ``state1`` and ``state2`` cause power loss.
.. code-block:: devicetree
power-states {
state0: state0 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-idle";
min-residency-us = <10000>;
exit-latency-us = <100>;
};
state1: state1 {
compatible = "zephyr,power-state";
power-state-name = "standby";
min-residency-us = <20000>;
exit-latency-us = <200>;
};
state2: state2 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-ram";
min-residency-us = <50000>;
exit-latency-us = <500>;
};
state3: state3 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-ram";
status = "disabled";
};
};
test_dev: test_dev {
compatible = "test-device-pm";
status = "okay";
zephyr,disabling-power-states = <&state1 &state2>;
};
After that devices can lock these state calling
:c:func:`pm_policy_device_power_lock_get` and release with
:c:func:`pm_policy_device_power_lock_put`. For example:
.. code-block:: C
static void timer_expire_cb(struct k_timer *timer)
{
struct test_driver_data *data = k_timer_user_data_get(timer);
data->ongoing = false;
k_timer_stop(timer);
pm_policy_device_power_lock_put(data->self);
}
void test_driver_async_operation(const struct device *dev)
{
struct test_driver_data *data = dev->data;
data->ongoing = true;
pm_policy_device_power_lock_get(dev);
/** Lets set a timer big enough to ensure that any deep
* sleep state would be suitable but constraints will
* make only state0 (suspend-to-idle) will be used.
*/
k_timer_start(&data->timer, K_MSEC(500), K_NO_WAIT);
}
Wakeup capability
*****************

2
doc/services/pm/system.rst
View file

@ -122,6 +122,8 @@ remaining time until the next scheduled timeout.
An example of an application that defines its own policy can be found in
:zephyr_file:`tests/subsys/pm/power_mgmt/`.
.. _pm-policy-power-states:
Policy and Power States
------------------------