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

pm_setmode()

Set the power mode a power managed object

Synopsis:

#include <sys/pm.h>

int pm_setmode(pm_hdl_t hdl, 
               pm_power_mode_t mode, 
               unsigned flags);

Description:

The pm_setmode() is used to change the power mode of a power managed object.

The power manager determines whether the requested power mode change is allowed, subject to the current system power management policy. Even if the change is allowed by the power manager, the driver for the object may impose its own power management policy that refuses the request. For example, it may refuse to power down a device that is in use. mode can be either a generic power mode or a object specific power mode. See pm_power_mode_t. The flags variable controls the behavior of the power mode change:

PM_MODE_FORCE: The power mode change will not be refused by the Power Manager, or any driver specific power management policy.
PM_MODE_URGENT: can be used with PM_MODE_STANDBY or PM_MODE_OFF modes to indicate that the 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 drivermay 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.

Returns:

0: Success.
-1: An error occurred (errno is set).

Errors:

EBADF: hdl is not a valid handle.
EAGAIN: The specified mode is not allowed by the power manager policy.
EINVAL: Mode is not supported by the device or flags contains invalid values.
EACCES: Caller is not allowed to add properties to the object (for example, hdl was not opened with O_RDWR access)

Examples:

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

int
main(void)
{
   pm_hdl_t        hdl;

   hdl = pm_attach("object", O_RDWR);
   if (!pm_valid_hdl(hdl)) {
      perror("pm_attach");
      return EXIT_FAILURE;
   }

   // try to set device to active
   if (pm_setmode(fd, PM_MODE_ACTIVE, 0) == -1) {
       perror("pm_setmode");

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

Classification:

Neutrino

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes