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

pmd_attr_setpower()

Specify driver's setpower() function

Synopsis:

#include <sys/pm.h>

void pmd_attr_setpower(pmd_attr_t *pmd, 
                       pmd_setpower_t func, 
                       void *data);

Arguments:

pmd: Pointer to the pmd_attr_t structure to be initialized.
func: Pointer to the driver specific function to set the device power mode.
data: Pointer to driver specific data passed to func.

Description:

The pmd_attr_setpower() initializes the pmd_attr_t's setpower and data fields to the specified driver specific values.

The func() is the driver specific function to set the device power mode:

int (*func)(pmd_attr_t *pmd, unsigned flags);

Where:

pmd->cur_attr points to the pmd_mode_attr_t for the current device mode.

pmd->new_attr points to the pmd_mode_attr_t for the mode to be set.

pmd->new_flags contains the mode flags that apply to the new power mode.

This function is responsible for performing all necessary actions to set the new mode:

if the device is being powered down, it may have to flush driver buffers to the device before powering it down. The PM_MODE_URGENT flag set in pmd->new_flags indicates the driver should discard these buffers so that the power down occurs immediately.
If this draining operation will complete some time later, the function should return at this point with EINPROGRESS to indicate that the mode change has been started, but will complete later. The driver is responsible for calling pmd->setpower() itself when this occurs to complete processing of the power mode change.
if PM_MODE_HWVOL is set in pmd->new_flags, the driver may need to save information required to reinitialize the device hardware registers.
if PM_MODE_NORAM is set in pmd->new_flags, the driver may need to save information in its persistent storage object so that driver and device state can be restored when the driver is restarted after a system wakeup.
once buffers have flushed and any necessary state has been saved, the hardware can be set to the appropriate power level.
once the power level has been changed, pmd_confirm() should be used to inform the Power Manager that the mode change has completed.
if the mode has changed from a non-active to a PM_MODE_ACTIVE mode, the driver must perform whatever driver specific actions are required to unblock or restart requests that were blocked because they could not proceed in the previous power mode.

pmd->setpower() is called by the following library helper functions:

by pmd_handler() to set the power mode requested by the power manager
by pmd_power() to set the power mode requested by an iopower_setmode() call to the driver.

These functions call setpower() with the pmd exclusive lock held to serialize power mode changes. If the driver needs to call pmd->setpower() itself, for example, when a draining operation completes, it should acquire this lock using pmd_lock_exclusive() first.

Examples:

For more information, see the device driver chapter.

Classification:

Neutrino

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