DPM Device Constraints

Device Constraints

Device constraints allow drivers to control entry to DPM operating points. Constraints are usually employed to restrict entry to operating points that are incompatible with correct operation of devices. For example, proper functioning of a device may require that the system PLL be running; if the PLL is inactive then the device must have first been powered off (or placed into a device suspend state compatible with the state of the PLL). The appropriate device constraints to use, and the consequences of violating these constraints, may be determined by the characteristics of the hardware platform. Constraints may also be chosen to restrict DPM operation in ways deemed useful by the system designer, such as to allow DPM to transition to a low-power idle mode only if a set of devices are not in use (regardless of whether the underlying hardware is capable of operating the devices in that mode).

The manner in which DPM interprets constraints depends on the way the current DPM policy is defined. DPM policies can map a system operating state to a specific DPM operating point or to a DPM class of operating points. The two cases are described in the sections that follow.

Case 1: Policy Specifies an Operating Point

If the active policy specifies a single operating point for the current operating state and the operating point violates a device constraint then one of two actions may be taken, depending on the setting of the "force" attribute of the requested operating point:

If the operating point "force" attribute is not enabled then DPM will not activate the operating point; the system will remain running at the previous operating point. In this fashion, drivers may override an attempt by an application to place the system into an incompatible power state. This is the default behavior.

The following behavior has been disabled pending rework: If the "force" attribute is enabled then the device that registered the constraint will be powered off (via the driver LDM suspend callback) before the new operating point is activated. The "force" attribute is enabled using the instructions that appear in a following section. Using this attribute, a power manager application can shut down devices and enter a low-power state when critical to do so, such as in low-battery conditions.

Case 2: Policy Specifies a Class

If the active policy specifies a class of operating points for the current operating state then DPM chooses one of the operating points in the class that do not violate device constraints. See the section on DPM Classes for more information on how the selection occurs.

Constraints Interfaces

Device constraints may be specified and managed by driver code in the kernel, or from userspace via sysfs (perhaps under control of a power policy management application). The ability to "force" constrained operating points is also managed by kernel platform code or from userspace via sysfs.

Constraints sysfs Interface

Constraints may be read and written using the sysfs constraints power attribute of the device, /sys/devices/bus/device-id/power/constraints. The format of strings written to this attribute is:

power_param min_value max_value

where:

power_param

is the name of a power parameter for the platform.

min_value

is the minimum value of that power parameter, or -1 for no minimum.

max_value

is the maximum value of that power parameter, or -1 for no maximum.

For example:

echo "pll 66 266" > /sys/devices/my-bus/my-device/power/constraints

The above example causes device my-device to constrain the power parameter named "pll" to values between 66 and 266.

Writing new values for a different power parameter to the constraints attribute adds new constraints for that device. Writing new values for a power parameter that already appears overwrites the old values. If the new maximum or minimum value is -1, the existing maximum or minimum constraint is removed.

A contrived sysfs usage on TI OMAP that blocks entry to sleep states while the LCD device is powered on (CPU divisor value zero indicates sleep):

# LCD device constraints CPU divider non-zero
echo "arm-div 1 2" > /sys/devices/platform/omapfb0/power/constraints
# Attempt to enter sleep operating state
echo "sleep" > /sys/dpm/state/active
# Check LCD constraints attribute
cat /sys/devices/platform/omapfb0/power/constraints
arm-div: min=1 max=2
asserted=yes violations=2
# Remove LCD constraints
echo "arm-div -1 -1" > /sys/devices/platform/omapfb0/power/constraints
# Re-attempt to enter sleep operating state
echo "sleep" > /sys/dpm/state/active

Constraints Driver Interface

Alternatively, constraints may be specified using the constraints field of the struct device, which is a pointer to a struct constraints. An example for a platform that interprets identifier DPM_MD_PLL as the index of a power parameter that indicates whether the PLL is on or off:

static struct constraints my_constraints = {
        count: 1,
        param: {{DPM_MD_PLL, 1, 1},}, /* require the PLL be on */

};

static struct device my_device = {
...
        constraints:    &my_constraints,
}

The values of the param field correspond to the power_param_id, max_value, and min_value parameters of the sysfs attribute described above.

Asserting and Deasserting Constraints

Device constraints are normally "asserted" (or activated) whenever the device is powered on, and are "deasserted (or deactivated) whenever the device is powered off. DPM deasserts and reasserts device constraints when a device is suspended and resumed.

Constraints can also be managed by the driver by calling:

assert_constraints(dev->constraints)
deassert_constraints(dev->constraints)

Forced Constraint Overrides

Note: This behavior is disabled pending rework.

In some situations it may be desired to override device constraints and force the requested operating point to take effect. For example, in a low-battery situation an emergency transfer to a low-power state may be required. DPM forces the operating point when the force attribute of the operating point is set to one (and when the active policy specifies a single operating point, not a class, for the associated operating state).

The force attribute is exported via sysfs. For example:

echo 1 > /sys/dpm/op/low-power-opt/force

If DPM attempts to transition to operating point low-power-opt and a device's constraints are violated by the power parameters associated with that operating point then the device is first powered down prior to transitioning to the incompatible operating point. DPM calls the driver's suspend callback for the device, requesting power state 3.

If DPM later moves to an operating point that meets the device constraints then the device is powered back on via the driver resume callback.

The force attribute may also be modified in DPM platform code by setting the force field of the struct opt non-zero.

Since powering on and off devices typically takes a noticable amount of time, it is recommended that forced operating points be used only in situations where high latency of operating point changes is tolerable. For example, it may be appropriate to force an operating point that places the system into a low-power sleep or standby state that is expected to remain the active operating point for a "long" period of time. It may be less appropriate to force an operating point that may be entered or exited very rapidly, such as one used during brief idle periods during normal system operation.

In some situations, a power manager application or kernel driver can obtain approximately the same effect by first suspending any constraining devices and then requesting the desired operating state or activating the desired policy.

Kernel Configuration

Device constraints require CONFIG_PM=y, since Linux Driver Model power management functions and data structures that are only present when CONFIG_PM=y are used and extended by DPM device constraints.