man Pages(7):Device and Network Interfaces

pm(7D)

NAME

pm- power management driver

SYNOPSIS

/dev/pm

DESCRIPTION

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

Power Management Framework

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 definition of power manageable components of a device is under the control of the device driver. 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).

Normally, the pm driver manages the component transition from idle to power managed. 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 dependency requirements. A dependency occurs when a device requires another device to be power managed before it can be power managed. Dependencies occur on a per device basis: when a dependency exists, no components of a device may be managed unless all the devices it depends upon are first power managed. See power.conf( 4), power(9E), pm_create_components(9F), pm_idle_component(9F), pm_busy_component(9F), pm_destroy_components(9F), and Writing Device Drivers for additional information.

Using the commands below, an application may take control of the power management of a device from the pm driver and manage the transition of device power levels directly. Xsun(1) does this to power manage the display.

IOCTLS

For all ioctl commands, arg (see ioctl(2)) 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 level or threshold value */
	char	*dependent;	/* hold name of dependent */
	int	size;		/* size of dependent buffer */
} pm_request;

The fields should contain the following data:

who: Pointer to the name of the device to be configured. The name must be in the format described in power.conf(4).
select: Non-negative integer specifying the component or dependent being configured. The numbering starts at zero.
level: Non-negative integer specifying the threshold value in seconds or the desired power level.
dependent: 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 who field.
size: Size of the dependent buffer.

Not all fields are used in each command.

PM_DISABLE_AUTOPM

The device named by who is disabled from being automatically power managed. The caller will power manage the device directly using the commands below. If this command is not successfully executed, subsequent PM_SET_CUR_PWR calls will fail. Error codes:

EBUSY: Device already disabled for auto power management.
EPERM: Caller is neither superuser nor owner of the device.

PM_GET_NORM_PWR

The normal power level of the component select of the device named by who is returned. The normal power level of the component is the power level to which the component will be set when it becomes busy again. Error codes:

EINVAL: Device component out of range.
EIO: Device has no power-manageable components.

PM_GET_CUR_PWR

The current power level of component select of the device named by who is returned. Error codes:

EINVAL: Device component out of range.

PM_SET_CUR_PWR

Component select of the device named by who is brought to power level level. If select is not 0 and component 0 of the device is at power level 0, component 0 is brought to its normal power level. Each component of each device which depends on this device is brought to its normal power level. Each component of each ancestor of each device affected is brought to its normal power level. Error codes:

EINVAL: Device component out of range, or power level < 0.
EIO: Failed to power device or its ancestors or its dependees or their ancestors.
EPERM: Caller is neither superuser nor owner of the device.

PM_REENABLE_AUTOPM

The device named by who is re-enabled for automatic power management. By default, all configured devices are automatically power managed by the pm device. Error codes:

EINVAL: Device already being power managed automatically.
EPERM: Caller is neither superuser nor owner of the device.

ERRORS

Upon error, the commands will return -1, and set errno. In addition to the error codes listed above by command, 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.
ENXIO: Too many opens attempted.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Unstable

NOTES

To unload a power managed driver, the driver must first be unmanaged (see pmconfig(1M)).

pm(7D) is not a stable API. The commands documented within this reference manual page may not exist or may have a different interpretation in a future release. That other reference manual pages lack this notice does not imply that they document a stable API.

SunOS 5.7 Last Revised 10 Jun 1997