com.digi.android.system.cpu

Class CPUManager

java.lang.Object

com.digi.android.system.cpu.CPUManager

public class CPUManager
extends java.lang.Object

This class provides access to the CPU management.

This manager allows applications to enable/disable the CPU cores, configure the different frequency values and set the CPU governor.

Unless noted, all CPU API methods require the com.digi.android.permission.CPU permission. If your application does not have this permission it will not have access to any CPU service feature.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_USAGE_ELAPSE Default timeout get usage calls block: 300 milliseconds.
static int	MINIMUM_TEMP_INTERVAL Minimum interval between temperature reads: 1000 milliseconds.

Constructor Summary

Constructors

Constructor and Description
CPUManager(android.content.Context context) Class constructor.

Method Summary

Modifier and Type	Method and Description
void	boostPulse() Immediately boosts the speed of all CPUs to high speed frequency for the period of time specified by the 'Boost pulse duration' property of the 'interactive' governor.
void	disableCore(int coreIndex) Disables the provided core.
void	enableCore(int coreIndex) Enables the provided core.
java.util.ArrayList<java.lang.Integer>	getAvailableFrequencies() Returns a list with the available frequencies in KHz.
java.util.ArrayList<GovernorType>	getAvailableGovernorTypes() Returns a list with the available governor types supported by the CPU.
float	getCoreUsage(int coreIndex) Returns the usage of the provided core, in percent.
float	getCoreUsage(int coreIndex, long elapse) Returns the usage of the provided core, in percent.
float	getCPUUsage() Returns the total CPU usage, in percent.
float	getCPUUsage(long elapse) Returns the total CPU usage, in percent.
float	getCriticalTemperature() Retrieves the critical CPU temperature value.
float	getCurrentTemperature() Retrieves the current CPU temperature.
int	getFrequency() Returns the current frequency (in kHz) of the CPU.
Governor	getGovernor() Returns the governor that the CPU is configured with.
GovernorType	getGovernorType() Returns the governor type the CPU is configured with.
float	getHotTemperature() Retrieves the hot CPU temperature value.
int	getMaxFrequency() Returns the maximum frequency (in kHz) that the CPU supports.
int	getMaxScalingFrequency() Returns the maximum frequency (in kHz) the device may scale the CPU to.
int	getMinFrequency() Returns the minimum frequency (in kHz) that the CPU supports.
int	getMinScalingFrequency() Returns the minimum frequency (in kHz) the device may scale the CPU to.
int	getNumberOfCores() Returns the number of cores available in the device.
int	getTransitionLatency() Returns the transition latency of the CPU in nano seconds (10^⁻9).
java.util.ArrayList<java.lang.Float>	getUsage() Returns a list with all the CPU usage percentages (from CPU and cores).
java.util.ArrayList<java.lang.Float>	getUsage(long elapse) Returns a list with all the CPU usage percentages (from CPU and cores).
boolean	isCoreEnabled(int coreIndex) Returns whether the provided core is enabled or disabled.
void	registerListener(ICPUTemperatureListener listener, long interval) Registers for temperature updates using the given time interval.
float	setCriticalTemperature(float temp) Sets the critical CPU temperature value.
void	setFrequency(int frequency) Configures the CPU with a custom frequency (in kHz).
Governor	setGovernorType(GovernorType governorType) Configures the CPU with the provided governor type.
float	setHotTemperature(float temp) Sets the hot CPU temperature value.
void	setMaxScalingFrequency(int frequency) Sets the maximum frequency (in kHz) the device may scale the CPU to.
void	setMinScalingFrequency(int frequency) Sets the minimum frequency (in kHz) the device may scale the CPU to.
void	unregisterListener(ICPUTemperatureListener listener) Removes all temperature updates for the specified listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MINIMUM_TEMP_INTERVAL

public static final int MINIMUM_TEMP_INTERVAL

Minimum interval between temperature reads: 1000 milliseconds.

See Also:

Constant Field Values

DEFAULT_USAGE_ELAPSE

public static final int DEFAULT_USAGE_ELAPSE

Default timeout get usage calls block: 300 milliseconds.

See Also:

Constant Field Values

Constructor Detail

CPUManager

public CPUManager(android.content.Context context)

Class constructor.

Instantiates a new CPUManager for the given application.

Parameters:

context - Context of the application.

Method Detail

getNumberOfCores

public int getNumberOfCores()

Returns the number of cores available in the device.

Returns:

The number of cores available in the device.

See Also:

enableCore(int), disableCore(int), isCoreEnabled(int)

enableCore

public void enableCore(int coreIndex)
                throws NoSuchCoreException,
                       CPUException

Enables the provided core.

Parameters:

coreIndex - The index of the core to enable.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If coreIndex < 1.

NoSuchCoreException - If the core does not exist.

See Also:

disableCore(int), getNumberOfCores(), isCoreEnabled(int)

disableCore

public void disableCore(int coreIndex)
                 throws NoSuchCoreException,
                        CPUException

Disables the provided core.

Parameters:

coreIndex - The index of the core to disable.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If coreIndex < 1.

NoSuchCoreException - If the core does not exist.

See Also:

enableCore(int), getNumberOfCores(), isCoreEnabled(int)

isCoreEnabled

public boolean isCoreEnabled(int coreIndex)
                      throws NoSuchCoreException,
                             CPUException

Returns whether the provided core is enabled or disabled.

Parameters:

coreIndex - The index of the core to check if it is enabled.

Returns:

true if the core is enabled, false otherwise.

Throws:

CPUException - If there is an error checking for the core status.

NoSuchCoreException - If the core does not exist.

See Also:

enableCore(int), disableCore(int), getNumberOfCores()

getCPUUsage

public float getCPUUsage()
                  throws CPUException

Returns the total CPU usage, in percent. The call is blocking for DEFAULT_USAGE_ELAPSE milliseconds.

Returns:

The total CPU usage percentage or -1 if the value is not available.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int), getCoreUsage(int, long), getCPUUsage(long), getUsage(), getUsage(long)

getCPUUsage

public float getCPUUsage(long elapse)
                  throws CPUException

Returns the total CPU usage, in percent. The call is blocking for the time specified by elapse.

Parameters:

elapse - The time in milliseconds between reads.

Returns:

The total CPU usage percentage or -1 if the value is not available.

Throws:

CPUException - If there is an error getting the usage.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int), getCoreUsage(int, long), getCPUUsage(), getUsage(), getUsage(long)

getCoreUsage

public float getCoreUsage(int coreIndex)
                   throws NoSuchCoreException,
                          CPUException

Returns the usage of the provided core, in percent. The call is blocking for DEFAULT_USAGE_ELAPSE milliseconds.

Parameters:

coreIndex - The index of the core to read its usage.

Returns:

The usage of the provided core or -1 if the value is not available.

Throws:

CPUException - If there is an error getting the usage.

NoSuchCoreException - If the core does not exist.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int, long), getCPUUsage(), getCPUUsage(long), getUsage(), getUsage(long)

getCoreUsage

public float getCoreUsage(int coreIndex,
                          long elapse)
                   throws NoSuchCoreException,
                          CPUException

Returns the usage of the provided core, in percent. The call is blocking for the time specified by elapse.

Parameters:

coreIndex - The index of the core to read its usage.

elapse - The time in milliseconds between reads.

Returns:

The usage of the provided core or -1 if the value is not available.

Throws:

CPUException - If there is an error getting the usage.

NoSuchCoreException - If the core does not exist.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int), getCPUUsage(), getCPUUsage(long), getUsage(), getUsage(long)

getUsage

public java.util.ArrayList<java.lang.Float> getUsage()
                                              throws CPUException

Returns a list with all the CPU usage percentages (from CPU and cores). The CPU usage is located at index 0 of the list, followed by the core usages for the available number of cores of the device. The call is blocking for DEFAULT_USAGE_ELAPSE milliseconds.

• Index 0: CPU usage
• Index 1: Core 0 usage
• Index 2: Core 1 usage
• Index 3: Core 2 usage
• Index 4: Core 3 usage
• ...

Returns:

The list with all the CPU usage percentages (from CPU and cores) or null if the he values are not available.

Throws:

CPUException - If there is an error getting the usage.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int), getCoreUsage(int, long), getCPUUsage(), getCPUUsage(long), getUsage(long)

getUsage

public java.util.ArrayList<java.lang.Float> getUsage(long elapse)
                                              throws CPUException

Returns a list with all the CPU usage percentages (from CPU and cores). The CPU usage is located at index 0 of the list, followed by the core usages for the available number of cores of the device. The call is blocking for the time specified by elapse.

• Index 0: CPU usage
• Index 1: Core 0 usage
• Index 2: Core 1 usage
• Index 3: Core 2 usage
• Index 4: Core 3 usage
• ...

Parameters:

elapse - The time in milliseconds between reads.

Returns:

The list with all the CPU usage percentages (from CPU and cores) or null if the he values are not available.

Throws:

CPUException - If there is an error getting the usage.

See Also:

DEFAULT_USAGE_ELAPSE, getCoreUsage(int), getCoreUsage(int, long), getCPUUsage(), getCPUUsage(long), getUsage()

getAvailableFrequencies

public java.util.ArrayList<java.lang.Integer> getAvailableFrequencies()
                                                               throws CPUException

Returns a list with the available frequencies in KHz.

Returns:

A list with the available frequencies in KHz.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

setFrequency

public void setFrequency(int frequency)
                  throws UnsupportedCommandException,
                         CPUException

Configures the CPU with a custom frequency (in kHz).

This operation can be performed only if the CPU is configured with a 'userspace' governor.

Parameters:

frequency - The frequency that the CPU is configured with in kHz.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If frequency > getMaxFrequency() or frequency < getMinFrequency() or the frequency is not contained in the list of available frequencies.

UnsupportedCommandException - If the GovernorType configured in the CPU is different from GovernorType.USERSPACE.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setMaxScalingFrequency(int), setMinScalingFrequency(int)

getFrequency

public int getFrequency()
                 throws CPUException

Returns the current frequency (in kHz) of the CPU.

Returns:

The current frequency of the CPU in kHz. -1 if the frequency could not be read correctly.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableFrequencies(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

getMaxFrequency

public int getMaxFrequency()
                    throws CPUException

Returns the maximum frequency (in kHz) that the CPU supports.

Returns:

The maximum supported frequency of the CPU in kHz. -1 if the frequency could not be read correctly.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

getMinFrequency

public int getMinFrequency()
                    throws CPUException

Returns the minimum frequency (in kHz) that the CPU supports.

Returns:

The minimum supported frequency of the CPU in kHz. -1 if the frequency could not be read correctly.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

getMinScalingFrequency

public int getMinScalingFrequency()
                           throws CPUException

Returns the minimum frequency (in kHz) the device may scale the CPU to.

Returns:

The minimum scaling frequency of the CPU in kHz. -1 if the frequency could not be read correctly.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

setMinScalingFrequency

public void setMinScalingFrequency(int frequency)
                            throws CPUException

Sets the minimum frequency (in kHz) the device may scale the CPU to.

Parameters:

frequency - The minimum scaling frequency in kHz.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If frequency > getMaxFrequency() or frequency < getMinFrequency() or frequency > getMaxScalingFrequency() or the frequency is not contained in the list of available frequencies.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int)

getMaxScalingFrequency

public int getMaxScalingFrequency()
                           throws CPUException

Returns the maximum frequency (in kHz) the device may scale the CPU to.

Returns:

The maximum scaling frequency of the CPU in kHz. -1 if the frequency could not be read correctly.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMaxScalingFrequency(int), setMinScalingFrequency(int)

setMaxScalingFrequency

public void setMaxScalingFrequency(int frequency)
                            throws CPUException

Sets the maximum frequency (in kHz) the device may scale the CPU to.

Parameters:

frequency - The maximum scaling frequency in kHz.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If frequency > getMaxFrequency() or frequency < getMinFrequency() or frequency < getMinScalingFrequency() or the frequency is not contained in the list of available frequencies.

See Also:

getAvailableFrequencies(), getFrequency(), getMaxFrequency(), getMaxScalingFrequency(), getMinFrequency(), getMinScalingFrequency(), setFrequency(int), setMinScalingFrequency(int)

getAvailableGovernorTypes

public java.util.ArrayList<GovernorType> getAvailableGovernorTypes()
                                                            throws CPUException

Returns a list with the available governor types supported by the CPU.

Returns:

A list with the supported governor types

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getGovernor(), getGovernorType(), setGovernorType(GovernorType), GovernorType

setGovernorType

public Governor setGovernorType(GovernorType governorType)
                         throws CPUException

Configures the CPU with the provided governor type.

Parameters:

governorType - The GovernorType to configure in the CPU.

Returns:

The Governor corresponding to the provided GovernorType and that has been set in the manager.

Throws:

CPUException - If there is an error during the configuration process.

java.lang.IllegalArgumentException - If the governor type is not supported by the CPU, (see getAvailableGovernorTypes()).

See Also:

getAvailableGovernorTypes(), getGovernor(), getGovernorType(), Governor, GovernorType

getGovernorType

public GovernorType getGovernorType()
                             throws CPUException

Returns the governor type the CPU is configured with.

Returns:

The GovernorType that the CPU is configured with.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableGovernorTypes(), getGovernor(), setGovernorType(GovernorType), GovernorType

getGovernor

public Governor getGovernor()
                     throws CPUException

Returns the governor that the CPU is configured with.

Returns:

The governor that the CPU is configured with. GovernorType.UNKNOWN if the governor type does not match any of the known types.

Throws:

CPUException - If there is an error during the configuration process.

See Also:

getAvailableGovernorTypes(), getGovernorType(), setGovernorType(GovernorType), Governor, GovernorType

getTransitionLatency

public int getTransitionLatency()
                         throws CPUException

Returns the transition latency of the CPU in nano seconds (10^⁻9). It is the time it takes to the CPU to switch between two frequencies.

If it is unknown or known to be that high that the driver does not work with the 'ondemand' governor, it returns -1.

Returns:

The transition latency of the CPU in nano seconds.

Throws:

CPUException - If there is an error during the configuration process.

boostPulse

public void boostPulse()
                throws UnsupportedCommandException,
                       CPUException

Immediately boosts the speed of all CPUs to high speed frequency for the period of time specified by the 'Boost pulse duration' property of the 'interactive' governor. After that, speeds are allowed to drop below the high speed frequency according to load as usual.

This operation can be performed only if the CPU is configured with 'interactive' governor.

Throws:

CPUException - If there is an error during the configuration process.

UnsupportedCommandException - If the GovernorType configured in the CPU is different from GovernorType.INTERACTIVE.

See Also:

GovernorInteractive.getBoostPulseDuration(), GovernorInteractive.setBoostPulseDuration(long)

getCurrentTemperature

public float getCurrentTemperature()
                            throws CPUTemperatureException

Retrieves the current CPU temperature.

Returns:

The current CPU temperature.

Throws:

CPUTemperatureException - If there is an error reading the current temperature.

getHotTemperature

public float getHotTemperature()
                        throws CPUTemperatureException

Retrieves the hot CPU temperature value.

Hot CPU temperature is the temperature limit at which system will reduce CPU and GPU frequency to avoid system overheating.

Returns:

The hot CPU temperature value.

Throws:

CPUTemperatureException - If there is an error reading the hot temperature.

See Also:

setHotTemperature(float)

setHotTemperature

public float setHotTemperature(float temp)
                        throws CPUTemperatureException

Sets the hot CPU temperature value.

Hot CPU temperature is the temperature limit at which system will reduce CPU and GPU frequency to avoid system overheating.

Note that in some scenarios there might be problems setting the requested temperature. Use the returned value to verify the temperature that was finally set.

Parameters:

temp - New hot CPU temperature value.

Returns:

The temperature value that was finally set.

Throws:

CPUTemperatureException - If there is an error setting the hot temperature.

java.lang.IllegalArgumentException - If the given temperature is equal or greater than the critical temperature.

See Also:

getCriticalTemperature(), getHotTemperature()

getCriticalTemperature

public float getCriticalTemperature()
                             throws CPUTemperatureException

Retrieves the critical CPU temperature value.

Critical CPU temperature is the temperature limit at which system will halt to avoid system damage caused by overheating. This always occurs after reaching hot temperature.

Returns:

The critical CPU temperature value.

Throws:

CPUTemperatureException - If there is an error reading the critical temperature.

See Also:

setCriticalTemperature(float), getHotTemperature()

setCriticalTemperature

public float setCriticalTemperature(float temp)
                             throws CPUTemperatureException

Sets the critical CPU temperature value.

Critical CPU temperature is the temperature limit at which system will halt to avoid system damage caused by overheating. This always occurs after reaching hot temperature.

Note that in some scenarios there might be problems setting the requested temperature. Use the returned value to verify the temperature that was finally set.

Parameters:

temp - New critical CPU temperature value.

Returns:

The temperature value that was finally set.

Throws:

CPUTemperatureException - If there is an error setting the critical temperature.

java.lang.IllegalArgumentException - If the given temperature is equal or lesser than the hot temperature.

See Also:

getCriticalTemperature(), getHotTemperature()

registerListener

public void registerListener(ICPUTemperatureListener listener,
                             long interval)

Registers for temperature updates using the given time interval.

Parameters:

listener - A ICPUTemperatureListener whose ICPUTemperatureListener.onTemperatureUpdate(float) method will be called for each temperature update.

interval - Time interval between temperature updates, in milliseconds.

Throws:

java.lang.IllegalArgumentException - If interval < MINIMUM_TEMP_INTERVAL.

java.lang.NullPointerException - If listener == null.

See Also:

MINIMUM_TEMP_INTERVAL, getCurrentTemperature(), unregisterListener(ICPUTemperatureListener), ICPUTemperatureListener

unregisterListener

public void unregisterListener(ICPUTemperatureListener listener)

Removes all temperature updates for the specified listener.

Following this call, updates will no longer occur for this listener.

Parameters:

listener - Listener object that no longer needs temperature updates.

Throws:

java.lang.NullPointerException - If listener == null.

See Also:

registerListener(ICPUTemperatureListener, long), ICPUTemperatureListener