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

mode_request() callback

Called to request power mode change for a node

Synopsis:

#include <sys/pmm.h>

int mode_request(void *data, pm_power_mode_t mode, 
     unsigned flags, const pm_power_attr_t *attr);

libc

This function is called when a request is made to change the power mode for a node:

data

Policy specific data returned by the create() function when the node is created.

mode

New mode that is being requested.

flags

Contain the following:

PM_MODE_FORCE: Force the object to change to mode.
If this is set, the policy should allow the change.
PM_MODE_REQUEST: Use this flag to request permission from the power manager to implement a power mode change.
This is typically be used by a driver to indicate to the power manager that mode is a more appropriate mode for the driver in its current state of operation.

attr

Contains the current power mode attributes of the node:

attr->cur_mode is the current mode of the device
if attr->new_mode is different from cur_mode, it indicates that the driver is in the process of changing to new_mode, but it hasn't confirmed that that mode change is complete
if attr->nxt_mode is different from new_mode, it indicates that a mode change request was received before the driver has changed to new_mode.

The return value from this function determines whether the mode change is allowed by the policy:

if the policy agrees, it should return EOK
The policy must allow the change if PM_MODE_FORCE is set.
if PM_MODE_REQUEST is set, the driver changes the mode on return from the power manager request. Otherwise, the library will deliver an event to the driver. This is in order to request a mode change.
if the policy does not agree and PM_MODE_REQUEST is set, this function should return EAGAIN to inform the driver that it can not change modes.
If PM_MODE_REQUEST is not set, and the policy does not agree to the mode change, it should return an appropriate error code.

The default action (if the policy does not override this function) is to allow all requests.