This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

iopower_setmode()

Set the power mode of a power managed device

Synopsis:

#include <sys/pm.h>

int iopower_setmode(int filedes, 
                    pm_power_mode_t mode, 
                    unsigned flags);

Arguments:

filedes

A file descriptor to the device special file.

mode

The power mode to set.

flags

Flags controlling the power mode change.

Library:

libpm

Description:

The iopower_setmode() function replaces pm_set_power() that has been deprecated.

The iopower_setmode() is used to change the power mode of a power managed device.

The mode can be either a generic power mode or a device specific power mode. See pm_power_mode_t for details.

If the power manager is running, it determines whether the requested power mode change is allowed, subject to the current system power management policy.

If there's no power manager running, the driver may reject the mode change based on some internal policy. For example, it may refuse to power down a device if the device is in use.

The flags argument controls the behavior of the power mode change:

PM_MODE_FORCE

The power mode change is not refused by the power manager or device power management policy.

PM_MODE_URGENT

Used with PM_MODE_STANDBY or PM_MODE_OFF modes to indicate that driver should perform the change as quickly as possible. For example, if the driver maintains buffered data for the device, this flag will discard those buffers instead of waiting for the buffers to drain before performing the power mode change.

PM_MODE_NORAM

Used with PM_MODE_STANDBY modes to indicate that the driver may need to save any device or driver state in persistent storage. For example, if the device is being powered down in preparation for entering a system power state where system RAM is disabled.

PM_MODE_HWVOL

Used with PM_MODE_STANDBY modes to indicate that the driver may need to save any hardware state that would be lost when the system power state shuts down the CPU. For example, powering down system-on-chip processors may cause on-chip peripheral registers to lose their contents.

PM_MODE_WAKEUP

Used with PM_MODE_STANDBY modes to indicate that the driver should enable any system wakeup functionality implemented by the device. This is used for devices that can act as wake up sources when the system is placed in a low power standby mode.

If the mode change can't be performed immediately, this call returns -1 with errno set to EINPROGRESS. This can happen for example if powering down the device requires the driver to wait for buffered data to drain.

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EBADF

filedes is not a valid file descriptor.

EFAULT

A fault occurred accessing modes.

ENOSYS

The device is in the middle of an already initiated power mode change

EINPROGRESS

the mode change has been started, but will complete later

Examples:

#include <sys/pm.h>
#include <fcntl.h>
#include <stdlib.h>

int
main(void)
{
  int  fd;

   fd = open("/dev/device", O_RDWR);
   if (fd == -1) {
      perror("open");
      return EXIT_FAILURE;
   }

   // try to set device to active
   if (iopower_setmode(fd, PM_MODE_ACTIVE, 0) == -1 && errno != EINPROGRESS) {
                perror("iopower_setmode");

   // try to force device to active
   if (iopower_setmode(fd, PM_MODE_ACTIVE, PM_MODE_FORCE) == -1) {
      perror("iopower_setmode");
      }
   }
   return EXIT_SUCCESS;
}

Classification:

Neutrino

See also:

pm_power_mode_t, iopower_getattr(), iopower_modeattr(), iopower_getmodes()