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

Implementing a System Power Management Policy

This chapter contains the following topics:

• Overview
  • Power manager nodes
  • Power manager namespace
  • Power mode management
• Implementing a power manager
• The server library
  • Power manager server
  • Power managed objects
  • Support for product-spcific policies
  • Callbacks
  • State machine datatype and APIs
  • State machine operations
• An example of power manager

Overview

This chapter gives you the resources to implement a system-wide power management policy. As already mentioned in the Power Management Architecture chapter, QNX Neutrino's power manager framework has two important parts: the server and the client. This chapter describes the server for building the power manager, including a rich set of server library routines (or APIs) that help you build the power manager itself.

The server provides the following sets of services for building a product-specific power manager:

• a multi-threaded resource manager that handles client requests
• APIs for manipulating objects that represent power managed devices
• APIs for constructing simple state machines to describe the system power states.

The server library provides a number of APIs broken down into the following functional groups:

• resource manager interface presented to power manager clients
• node configuration and management
• manipulating power modes associated with a node
• manipulating properties associated with a node
• implementing simple state machines.

Please refer to the API Reference chapter for more information.

Power manager nodes

Power manager nodes represent the power managed entities in a system. A node is a (power manager) library specific concept/data structure that contains the following:

• the current power state (maintained using a pm_power_attr_t structure)
• a list of the power modes supported by the entity (an array of pm_power_mode_t values)
• the identity of the driver or other process that is responsible for managing the entity's power mode
• a list of properties associated with the node
• a list of clients that have registered for notification when the state of the node changes.

Not all nodes have a driver process responsible for managing the power mode. These nodes are not power managed.

Nodes are created in a number of ways:

• By the power manager itself. For example, the power manager populates the namespace to contain nodes for all devices in a statically configured system. It then starts device drivers that attach to these pre-configured nodes.
• By device drivers. For example, in a dynamically configured system, device drivers create the power manager nodes when the drivers are started.
• By some external configuration mechanism. For example, enumerators populate the namespace as buses and devices are detected. Because the library implements a standard resource manager interface, the namespace can be built using regular file and directory operations:
  • the mkdir command or mkdir() library call are used to create directory nodes
  • the mkfifo or touch commands or mknod() library call are used to create leaf nodes.

The organization and meaning of the namespace is entirely defined by the product-specific power manager policy. This implies that some sort of cooperation is needed between device drivers and the power manager in order to agree on the naming conventions that allow drivers to determine and attach to the relevant nodes.

Power manager namespace

The power manager implements a hierarchical namespace that represents the power managed entities. The namespace is built using two kinds of nodes:

directory nodes

The nodes represent power managed subsystems that contain a number of peripherals, e.g. buses. In this case, a bus driver is attached to the node to manage the bus power mode. The nodes also provide a naming context for the peripherals.

The directory nodes are also used for configuration or organizational purposes. In this case, there is no power management for the node itself, and it simply provides a naming context for other nodes.

leaf nodes

These nodes represent individual power managed devices. In this case, a driver is attached to the node to manage the device power mode.

The leaf nodes are also used for control purposes without having an associated driver. In this case, power manager properties are associated with the node. Manipulation of these properties by clients can be used to control aspects of the power manager behavior or policy.

Power mode management

The server provides the basic support for triggering and monitoring changes to the power mode on individual nodes.

The product-specific policy can change the power mode of a node. This results in a request being made to the driver responsible for the node's power mode. This request is asynchronous, and the power mode state is updated when the driver completes the request and confirms its new power mode. The library delivers notification of changes to the power mode state to registered clients.

The product-specific policy is informed when the driver changes the power mode. This is in response to a request initiated by the power manager or from the driver itself independent of the power manager policy.

The library implements control of individual node only; it doesn't manage the sequencing of power mode changes for groups of nodes. This is the responsibility of the product-specific policy code. For example, when powering down a subsystem, the policy code is responsible for powering down individual devices within the subsystem before powering down the subsystem itself.

Product-specific policies

The server provides support for product-specific policy implementation in order to control many aspects of the life cycle for a power manager node. This is achieved by a set of policy functions that are invoked when:

• a node is created. This allows the policy to associate a policy-specific data structure with the node. This policy-specific data is supplied when other policy functions are invoked

• a request is made to unlink a node from the namespace. This happens when:
  • the driver for a dynamically created node detaches, in order to allow the power manager node and other resources to be cleaned up
  • an unlink request is made via the resource manager interface, for example via the mkdir or rm commands or rmdir() and unlink library calls.

  This allows the policy to specify whether the node is unlinked, or should remain in the namespace.

• the last reference to an unlinked node is released. This allows the policy to free any policy specific data associated with the node when it is created
• a client attaches or detaches. This allows the policy to keep track of clients if necessary
• a driver registers and initializes the power modes for the node. This allows the policy to determine that the node is now being power managed, and to find out the initial power mode
• a client or the driver requests a power mode change. This allows the policy to determine whether the power mode is allowed within the current system power state
• a driver confirms that a power mode change has been completed. This allows the policy to determine when the asynchronous power mode change has completed, and can be used to control the sequencing of power mode changes for multiple devices based on their power resource dependencies
• a new property is added to a node, or an existing property value is changed. This allows the policy to keep track of policies associated with nodes. It also allows a mechanism for clients to manipulate data that is used to control the policy behavior.

Implementing a power manager

The power manager you implement in accord with a product-specific must:

• specify the policy-specific functions
• initialize and start the server interface
• perform additional policy-specific actions (e.g. populate the namespace, start device drivers, or perform other system services).

Once the server interface is started, the power manager becomes event driven, and the policy receives control via the policy-specific functions. These policy functions use some policy specific data to manage the overall system power mode state.

It is possible to use only default policy functions to provide a very basic power manager. This power manager simply acts as a conduit between device drivers and other clients using power manager interfaces, such that:

• drivers can dynamically create nodes
• all power mode change requests are allowed, and notifications are sent to registered clients as necessary.

This simple policy doesn't handle power dependencies between devices. Control and management of these devices must be performed by client applications using the power manager interface.

To create a functional power manager using the default policy, you may use the following code:

#include <sys/pmm.h>
#include <sys/procmgr.h>

int
main(int argc, char *argv[])
{
   // initialize and start the power manager interface
   if (pmm_init(0) != EOK) {
   exit(1);
   }
   pmm_start(0, 0);

   // become a daemon
   procmgr_daemon(EXIT_SUCCESS, 0);
   pthread_detach(pthread_self());
   pthread_exit(0);
   return 0;
}

The server library

Power manager server

The server library provides the following interfaces to handle power manager clients:

The resource manger interface implements a subset of the standard POSIX iofunc layer calls. It also implements power manager specific operations via the custom message structures described in the client routines in the API Reference chapter:

io_open

Used by pm_attach() and pmd_attach(). In addition, the standard file creation commands and library calls allow external agents to create leaf power manager nodes.

io_mknod

Allows external agents to use standard directory creation commands and library calls to create directory power manager nodes.

io_unlink

Allows external agents to use standard file or directory removal commands and library calls to unlink power manager nodes.

io_msg

Implements the power manager client messages.

io_read

Allows external agents to use standard directory reading commands and library calls to list directory entries for directory nodes.

The iofunc_read_default() function is used for nondirectory nodes.

io_close_ocb

Implements the file close and connection detach handling.

You can manage the namespace using any combination of the following:

• static configuration by the power manager itself
• dynamic configuration in response to driver initialization
• programmatic configuration (for example, by enumerators or other configuration programs)
• shell script configuration (for example, initialization scripts)
• command line configuration (for example, manual administrator actions).

Access control and ownership of power manager nodes follow the standard filesystem semantics:

• nodes are created using the caller's identity and umask value
• ownership is changed using the chown command or library functions
• access modes are changed using the chmod command or library functions.

Power managed objects

Each power managed object is represented by a _pmm_node_t structure. This is an extension of the iofunc_attr_t that adds power manager-specific data, as follows:

• power mode attributes
• client notifications
• properties
• linkage into the power manager namespace.

This structure is opaque to the product-specific policy code, and can be manipulated only via:

• a public API for manipulating nodes
• a number of callback functions that are invoked when operations are performed on nodes.

The public interface for manipulating power manager nodes consists of the following functions:

Support for product-specific policies

In order to receive control during client requests on a particular node, the server library provides hooks for:

• node creation and destruction
• client attachment and detachment
• driver attachment
• power mode requests and mode change completion
• property creation and manipulation.

This support is provided by the following function and structure:

pmm_policy_funcs()

Get a pointer to the policy function table

pmm_policy_funcs_t

Contains a table of policy specific callbacks

Callbacks

Callbacks are available as follows:

State machine datatype and APIs

The following table lists the state machine datatype and APIs:

State machine operations

This section describes how to construct state machines that are used to describe and manage the system's power mode state.

Each power mode state is represented by a pmm_state_t structure that specifies:

• a policy specific identifier for the state
• a function that evaluates whether a new system state should be entered
• a function that performs actions required when leaving this state
• a function that performs actions required when entering this state.

The pmm_state_init() creates a new state machine using an array of pmm_state_t structures that describe the set of allowable states.

This is used to create multiple state machines that operate independently, or interact together to implement nested state machines.

The state machine APIs support the following modes of operation:

• a single-threaded state machine, where a dedicated thread is responsible for performing all state changes. These state changes are triggered by other power manager threads, based on events that change the status of power manager nodes, or other internal events.
• a multi-threaded state machine, where any power manager thread can directly perform a state change when necessary.

Single-threaded state machines

The basic steps involved are:

1. Define the system states and data associated with the state machine:

   pmm_state_t my_states[NSTATES] = {
      :
   };
   struct my_data *my_data;

2. Initialize the state machine:

   hdl = pmm_state_init(NSTATES, my_states, my_data, MY_INITIAL_STATE);

3. Execute the state machine:

   if (pmm_state_machine(hdl) != EOK) {
      error handling...
   }

   Because this call never returns, it must be the last initialization action that this thread performs.

Once the state machine thread is running, other threads can trigger state changes by calling pmm_state_trigger(hdl). This will cause the state machine thread to re-evaluate the current state and perform a state transition to a new state, if necessary.

Multi-threaded state machines

The basic steps involved are:

1. Define the system states and data associated with the state machine:

   pmm_state_t my_states[NSTATES] = {
      :
   };
   struct my_data *my_data;

2. Initialize the state machine:

   hdl = pmm_state_init(NSTATES, my_states, my_data, MY_INITIAL_STATE);

Once the state machine is initialized, any thread in the power manager can re-evaluate and change the system state as follows:

pmm_state_check(hdl, &cur_state, &new_state);
if (new_state != cur_state)
   pmm_state_change(hdl, new_state);

Alternatively, a thread may unconditionally change the state using (?)

The implementation ensures mutual exclusion between these two functions so that:

• state transitions in pmm_state_change() are serialized
• pmm_state_check() waits until a state transition completes before re-evaluating the state.

Nested state machines

You can build nested state machines where sub-state machines can affect state transitions on higher-level state machines:

• via pmm_state_trigger() if the higher-level state machine is single-threaded
• a combination of pmm_state_check() and pmm_state_change() if the higher-level state machine is multi-threaded.

For example, the power manager could implement separate state machines for each subsystem that implements a set of services, and the state of these individual subsystems can be used to control the system's power mode state.

An example of power manager