Process Performance State Manager (PPSM)

This note includes:

Overview

Process Performance State Manager (PPSM) is a static library that implements the Enhanced Intel SpeedStep Technology (EIST), and System State S3 (Suspend to RAM) and S5 (Suspend to Disk) power management support.

PPSM supports the following power management modes:

By default, the system remains in the C0 state at the maximum clock rate. Whenever the CPU idle thread is running, the C1 state is entered.

You can:

For more information about the Enhanced Intel SpeedStep Technology, see http://www.intel.com/support/processors/sb/CS-028855.htm.

PPSM functions

The PPSM library (libppsm.a) includes the following:

You normally call these functions in the following order:

  1. Call ppsm_init() to initialize and allocate resources used by the PPSM library, and create CPU load-accounting threads for each CPU.
  2. Call any other APIs as required.
  3. Call ppsm_fini() to stop the CPU accounting threads and release resources used by the PPSM library.

ppsm_init()

void * ppsm_init( int verbose,
                  int prio,
                  int interval,
                  int scale_factor,
                  int lower,
                  int upper,
                  int policy);

This function creates the device structure and starts the CPU load-accounting threads for each CPU. The arguments are:

verbose
The level of verbosity to use when logging information.
prio
The priority you want to set for the CPU accounting thread (default: 51).
interval
The interval (in ms) at which to check the CPU load and put the CPU into the desired state according to current CPU load.
scale_factor
When the system is busy (target state or current state at highest performance state), the polling time = interval × scale_factor.
lower
The lower threshold (as a percentage of CPU loading from 0 to 100).
upper
The upper threshold (as a percentage of CPU loading from 0 to 100).
policy
The default initial policy; the following policies are supported:

The ppsm_init() function returns a handle that you need to pass to the other PPSM functions, or NULL if the initialization failed (see the system log for details).

ppsm_fini()

void ppsm_fini( void *handle);

This function stops the CPU accounting threads and releases the resources used by the PPSM library. The only argument is the handle returned by ppsm_init().

ppsm_sys_mode()

int ppsm_sys_mode( void *handle,
                   int mode );

This function sets the system-wide sleep mode. The arguments are:

handle
The handle returned by ppsm_init().
mode
The system mode (PPSM_SYSTEM_MODE_S3 or PPSM_SYSTEM_MODE_S5) that you want to set.

The ppsm_sys_mode() function returns -1 if an error occurred; if the function succeeds, it doesn't return.

ppsm_set_polling_interval()

int ppsm_set_polling_interval( void *handle,
                               int interval,
                               int scale_factor );

This function sets the polling interval and the scaling factor. The arguments are:

handle
The handle returned by ppsm_init().
interval
The interval (in ms) at which to check the CPU load and put the CPU into the desired state according to the current CPU load.
scale_factor
When the system is busy (when the target state or the current state is at the highest performance state), the polling time = interval × scale_factor.

The ppsm_set_polling_interval() function returns -1 on error (e.g. interval is less than 1).

ppsm_set_threshold()

int ppsm_set_threshold( void *handle,
                        int lower,
                        int upper );

This function sets the upper and lower threshold values for CPU loading. The arguments are:

handle
The handle returned by ppsm_init().
lower
The lower threshold (as a percentage of CPU loading from 0 to 100).
upper
The upper threshold (as a percentage of CPU loading from 0 to 100).

The ppsm_set_threshold() function returns -1 on error (e.g. lower is less than 0, or lower is greater than upper).

ppsm_get_cpuload()

int ppsm_get_cpuload( void *handle,
                      int cpu );

This function gets the current CPU load. The arguments are:

handle
The handle returned by ppsm_init().
cpu
The index of the CPU, in the range from 0 to the number of processors − 1.

This function returns the per cent load for the specified CPU, or -1 if an error occurred (e.g. the CPU index is out of range).

ppsm_get_cpufreq()

int ppsm_get_cpufreq( void *handle,
                      int cpu );

This function gets the current CPU frequency. The arguments are:

handle
The handle returned by ppsm_init().
cpu
The index of the CPU, in the range from 0 to the number of processors − 1.

The ppsm_get_cpufreq() function returns the current CPU frequency, in MHz, or -1 if an error occurred (e.g. the CPU index is out of range).

ppsm_speedstep_enable()

int ppsm_speedstep_enable( void *handle);

This function enables the SpeedStep functionality, which is disabled by default after you call ppsm_init(). This automatically sets the policy to PPSM_POLICY_ADAPTIVE. The only argument is the handle returned by ppsm_init().

The ppsm_speedstep_enable() function returns -1 on error.

ppsm_speedstep_disable()

int ppsm_speedstep_disable( void *handle);

This function disables the SpeedStep functionality (by default after you call ppsm_init(), the SpeedStep is disabled). This automatically sets the policy to PPSM_POLICY_NONE. The only argument is the handle returned by ppsm_init().

The ppsm_speedstep_disable() function returns -1 on error.

ppsm_set_policy()

int ppsm_set_policy( void *handle,
                     int policy );

This function sets the power-management policy (by default after you call ppsm_init(), it's PPSM_POLICY_NONE). The arguments are:

handle
The handle returned by ppsm_init().
policy
The policy you want to set; one of:

The ppsm_set_policy() function returns -1 on error.

ppsm_set_notify_handler()

int ppsm_set_notify_handler( void *handle,
                             FnNotifyCbck cbx,
                             void *clientinfo );

This function registers a notification handler that you want to be called whenever there's a state change. The arguments are:

handle
The handle returned by ppsm_init().
cbx
A pointer to the notification handler (see below).
clientinfo
A pointer to arbitrary data that you want to pass to the handler.

The ppsm_set_notify_handler() function returns -1 on error.

The prototype of the handler is as follows:

void my_handler ( void *handle,
                             int cpuid,
                             void *clientinfo );

Whenever the performance state changes, the library calls this function, passing the following:

handle
The handle returned by ppsm_init().
cpu
The ID of the CPU whose state has changed.
clientinfo
A pointer to the client data that you specified when you registered the handler.

The handler doesn't return anything.