NAME

pm - Power Management Driver

SYNOPSIS

#include <sys/pm.h>

int ioctl(int fildes, int command, int arg);

AVAILABILITY

SUNWpmu

DESCRIPTION

The Power Management driver provides an interface for applications to configure the devices within the system for power management. The interface is provided through ioctl(2) commands. The pm driver may be accessed using /dev/pm.

fildes is an open file descriptor that refers to the pm driver. command determines the control function to be performed as described below. arg represents additional information that is needed by this command. The type of arg depends upon the command, but it is generally an integer or a pointer to a command-specific data structure.

COMMAND FUNCTIONS

Unless configured by using the commands below, pm does not power manage devices by default. Note, however, that the pmconfig(1M) program is typically run at boot time, and by reading the power.conf(4) file will use the commands below to configure pm. Any devices configured for power management by pm will have their drivers loaded (if not already) and locked into memory until that device is unmanaged. Some devices may be able to fully operate at non-full power levels. Using the command PM_SET_POWER on such a device allows this low power mode to become the normal (on) power level for that device. This mode of operation is distinct from the power managed mode of operation.

pm periodically searches the system for devices which it can power manage. A device will only be power managed when it is not in use (explained further below). When a power managed device is subsequently used, it will be automatically returned to normal power.

The pm model of power management is to view the system as a collection of devices. Each device is a collection of components, a component is the smallest power manageable unit. The devices, and the components within those devices, which are power manageable are dependent upon the implementation of their respective device drivers. A power manageable component has three states. It may be busy (in use), it may be idle (not in use but using normal power), or it may be power managed (not in use and not using normal power). The pm driver manages the component transition from the second to the third state. pm uses two factors to determine this transition: the component must have been idle for at least the threshold time; and the device to which the component belongs must satisfy any dependencies requirements. A dependency is when a device requires another device to be power managed before it can be power managed. A device is considered to be power managed when all of its components are power managed. Note that dependencies occur on a per device basis: when a dependency exists, no components of a device may be managed unless all the components it depends upon are first managed. For more information, see the Guide to Writing Device Drivers manual, attach(9E), detach(9E), power(9E).

Thus the configuration of a device for power management is the setting of the threshold for any component that is to be managed and defining any dependencies for that device.

For all commands excluding PM_SCHEDULE, arg points to a structure of type pm_request defined in sys/pm.h:

typedef struct {
        char    * who;          /* device to configure * /
        int     select;         /* selects the component or
                                dependent of the device * /
        int     level;          /* power or threshold level * /
        char    * dependent;    /* hold name of dependent * /
        int     size;           /* size of dependent buffer * /
} pm_request;

The fields should contain the following data. who is a pointer to the name of the device to be configured. The name must be in the format described in power.conf(4). select is a non-negative integer specifying the component or dependent being configured. The numbering starts at zero. level is non-negative integer giving the threshold level in seconds or the desired power level. dependent is a pointer to a buffer which contains or receives the name of a device on which this device has a dependency. It uses the same format as the first field. size is the size of the dependent buffer.

Not all fields are used in each command. Upon error the commands will return -1, and set errno to the error condition specified below. The following error codes are common to all commands.

EFAULT: Bad address passed in as argument.

ENODEV:

Device is not power manageable, or device is not configured (Use PM_SET_THRESHOLD command first).

ENXIO:

Invalid instance number (device not attached).

EPERM:

Permission denied. You must be root or console owner.

PM_SCHEDULE:

arg sets the period in seconds of pm device scans. A value of zero inhibits scans which stops any further components from being managed. A negative value is ignored. The ioctl returns the new (or current) period.

PM_GET_IDLE_TIME:

Using the fields who and select, this command returns the time in seconds since the component was last busy. Error codes:

EINVAL: Device component out of range.

PM_GET_NUM_CMPTS:

Using the field who, this command returns the number of components defined for this device.

PM_GET_THRESHOLD:

Using the fields who and select, this command returns the threshold level of the component. Error codes:

EINVAL: Device component out of range.

PM_SET_THRESHOLD:

Using the fields who, select and level, this command sets the threshold level of the component. It returns zero on success. Error codes:

EINVAL: Device component out of range, or threshold value < 0.

PM_GET_POWER:

Using the fields who and select, this command returns the current normal power level of the component.

EINVAL: Device component out of range.

EIO: Non-power manageable device (or properties are removed).

PM_SET_POWER:

Using the fields who, select and level, this command sets the current normal power level of the component to the given power level.

EINVAL: Device component out of range, or power level <= 0.

EIO: Failed to power device or its parent or its dependents.

PM_GET_CUR_PWR:

Using the fields who and select, this command returns the current power level of the component.

EINVAL: Device component out of range.

PM_GET_NUM_DEPS:

Using the field who, this command returns the number of dependents configured for this device.

PM_GET_DEP:

Using the fields who, select, level and dependent, this command writes the name of dependent into the buffer supplied by the dependent field.

EINVAL: Dependent component out of range, or user buffer is too small for

dependent name

EFAULT: Bad buffer address was given.

PM_ADD_DEP:

Using the fields who and dependent, this command adds the dependent to the device.

ENODEV: Dependent is non-power manageable or is not configured.

PM_REM_DEP:

Using the fields who and dependent, this command removes the dependent from the device.

ENODEV: Dependent is non-power manageable or is not configured, or the

device has no dependents

PM_REM_DEVICE:

Using the field who, this command unmanages the device and returns the device to normal power, if it is not already.

PM_REM_DEVICES:

This command unmanages all devices and returns them to normal power.

NOTES

To unload a power managed driver, the driver must first be unmanaged using PM_REM_DEVICE(S).

Currently it is NOT an error to remove a nonexistent dependent or add a repeated dependent. The pseudo driver will silently ignore the redundant command.

SEE ALSO

intro(2), ioctl(2), pmconfig(1M), power.conf(4), attach(9E), detach(9E), power(9E)