Functions to gather acpi/apm information
[Libpower]

Classes
struct	BatteryGeneral
	General battery information. More...
struct	BatteryDetailed
	Detailed battery information. More...
struct	ThermalDev
	object representing a thermal device More...
Defines
#define	MAX_FILE_PATH   512
	maximum length of a filepath
#define	MAX_LINE_SIZE   1024
	maximum length of a line
#define	MAX_BATTERIES   4
	maximum number of batteries we support
#define	MAX_BAT_CHAR_LEN   200
	Max string length in ACPI Source Language: 200 bytes.
#define	MAX_THERMAL_ACTIVE   10
#define	NO_ACPI_ERROR   -20
	error if acpi is not supported by the system
#define	NO_MODULE_ERROR   -10
	error for unavailable module
#define	NO_DEVICE_ERROR   -5
	error for unavailable device
#define	MAX_SUPPORTED_CPUS   32
	maximum number of supported cpus
#define	UNKNOWN   -1
	defining an unknown state
#define	CHARG_STATE_UNKNOWN   0
	charging state is unknown
#define	CHARG_STATE_CHARGING   1
#define	CHARG_STATE_DISCHARGING   2
	battery is currently discharging
#define	CHARG_STATE_CHARG_DISCHARG   (CHARG_STATE_CHARGING | CHARG_STATE_DISCHARGING)
	defines whether charging or discharging
#define	ACPI_S1   1
	acpi sleep state S1
#define	ACPI_S2   2
	acpi sleep state S2
#define	ACPI_S3   4
	acpi sleep state S3
#define	ACPI_S3_BIOS   8
	acpi sleep state S3 bios
#define	ACPI_S4   16
	acpi sleep state S4
#define	ACPI_S4_BIOS   32
	acpi sleep state S4 bios
#define	APM_STANDBY   64
	apm standby
#define	APM_SUSPEND   128
	apm suspend
#define	pDebug(level, string, args...)   do {} while (0);
Enumerations
enum	BATTERY_PRESENT { PRESENT_YES = 0, PRESENT_NO }
	whether the battery is present More...
enum	CAPACITY_UNIT { WATT_H = 0, AMP }
	the unit of the battery capacity More...
enum	BATTERY_TECH { TECH_NON_RECHARGEABLE = 0, TECH_RECHARGEABLE }
	technologie of the battery More...
enum	CAPACITY_STATE { STATE_OK, STATE_CRIT, STATE_LOW, STATE_WARN }
enum	AC_ADAPTER_STATE { AC_UNKNOWN, AC_ONLINE, AC_OFFLINE }
	ac adapter status More...
enum	DISK_MODE { DISK_FULL_ON, DISK_STANDBY, DISK_SLEEP }
	states a disk can be in More...
enum	LID_STATE { LID_OPEN, LID_CLOSED }
	current state of the lid More...
enum	ISACPI { NOT_SUPPORTED = -1, APM, ACPI }
	use for checkACPI function return value! More...
enum	THERM_MODE {   OK, ACTIVE, PASSIVE, HOT,   CRITICAL }
	the current thermal mode More...
enum	_COOLING_POLICY { COOLING_MODE_ACTIVE = 0, COOLING_MODE_PASSIVE }
	cooling policy More...
Functions
int	getBatteriesInfo (BatteryGeneral *bat)
	fills the given Battery struct with the current battery information for all found batteries
int	getBatteryInfo (const int no, BatteryGeneral *battery_info)
	get Information for only one battery
int	numBatteries (void)
	get number of present batteries
int	getBatteryDetailedInfo (const int no, BatteryDetailed *bd)
	use this method to get amount of batteries in the system
int	setBatteryAlarm (const int percent)
	sets the ACPI battery alarm for all batteries
int	getLidState (void)
	returns the current state of the lid
int	getThrottlingInfo (int *num_states, int *current_state)
	get throttling information (ACPI only)
int	setThrottlingPercent (const int percent)
	set throttling percent
int	getThrottlingInfoCPU (const int cpu, int *num_states, int *current_state)
	get throttling info for one single cpu
int	setThrottlingStateCPU (const int cpu, const int state)
	set throttling state on cpu
int	setThrottlingPercentCPU (const int cpu, const int percent)
	set throttling percent for single cpu
int	getThermalZonesNum (void)
	get the number of thermal zones
int	getThermalZoneTemp (const int zone)
	get thermal zone temp
int	getThermalZoneState (int zone)
	get thermal zone state
int	getThermalZone (const int zone, ThermalDev *td)
	get a thermal zone
int	setThermalTrippoints (const int zone, const ThermalDev td)
	set thermal trippoints
int	setCoolingMode (const int device_num, const int mode)
	set cooling mode
int	getFanNum (void)
	get number of fans in the system
int	getFanStatus (const int device_num)
	get fan status
int	getACAdapterStatus (void)
	returns if the machine is on ac power or not
float	getRealProcessorSpeed (void)
	get processor speed
int	calcCPULoad (const int consider_nice)
	calculate cpu load
int	getCPULoad (const int cpu)
	get current cpu load
void	freeCPULoadData (void)
	free data for calculating cpu time
int	getCPUCount (void)
	get number of cpus in system
int64_t	getSupportedSleepStates (void)
	get all supported sleeping states
int	checkACPI (void)
	determine whether there is apm, acpi or nothing on your Computer
void	setDebugLevel (const int dbg)
	set the debug level. Values: 0-31

---

Detailed Description

this is conform to the ACPI specification 2.0b (2002)

IMPORTANT !!! Test all data for UNKNOWN
You never know if the kernel or the hw supports specific features!

---

Define Documentation

#define ACPI_S1   1

acpi sleep state S1

#define ACPI_S2   2

acpi sleep state S2

#define ACPI_S3   4

acpi sleep state S3

#define ACPI_S3_BIOS   8

acpi sleep state S3 bios

#define ACPI_S4   16

acpi sleep state S4

#define ACPI_S4_BIOS   32

acpi sleep state S4 bios

#define APM_STANDBY   64

apm standby

#define APM_SUSPEND   128

apm suspend

#define CHARG_STATE_CHARG_DISCHARG   (CHARG_STATE_CHARGING | CHARG_STATE_DISCHARGING)

defines whether charging or discharging

#define CHARG_STATE_CHARGING   1

#define CHARG_STATE_DISCHARGING   2

battery is currently discharging

#define CHARG_STATE_UNKNOWN   0

charging state is unknown

#define MAX_BAT_CHAR_LEN   200

Max string length in ACPI Source Language: 200 bytes.

#define MAX_BATTERIES   4

maximum number of batteries we support

#define MAX_FILE_PATH   512

maximum length of a filepath Hope this is only under /proc/acpi where this is correct.

#define MAX_LINE_SIZE   1024

maximum length of a line

#define MAX_SUPPORTED_CPUS   32

maximum number of supported cpus

#define MAX_THERMAL_ACTIVE   10

#define NO_ACPI_ERROR   -20

error if acpi is not supported by the system

#define NO_DEVICE_ERROR   -5

error for unavailable device

#define NO_MODULE_ERROR   -10

error for unavailable module

#define pDebug (  level, string, args...   )     do {} while (0);

#define UNKNOWN   -1

defining an unknown state be careful to test every variable on unknown

---

Enumeration Type Documentation

enum _COOLING_POLICY

cooling policy Enumerator: COOLING_MODE_ACTIVE  COOLING_MODE_PASSIVE

enum AC_ADAPTER_STATE

ac adapter status Enumerator: AC_UNKNOWN  AC_ONLINE  AC_OFFLINE

enum BATTERY_PRESENT

whether the battery is present Enumerator: PRESENT_YES  PRESENT_NO

enum BATTERY_TECH

technologie of the battery Enumerator: TECH_NON_RECHARGEABLE  TECH_RECHARGEABLE

enum CAPACITY_STATE

because of kernel implementations separated in ACPI spec this is combined to battery_state be careful this is kernel definition of batteries states ! Enumerator: STATE_OK  STATE_CRIT  STATE_LOW  STATE_WARN

enum CAPACITY_UNIT

the unit of the battery capacity Enumerator: WATT_H  AMP

enum DISK_MODE

states a disk can be in Enumerator: DISK_FULL_ON  DISK_STANDBY  DISK_SLEEP

enum ISACPI

use for checkACPI function return value! Enumerator: NOT_SUPPORTED  APM  ACPI

enum LID_STATE

current state of the lid Enumerator: LID_OPEN  LID_CLOSED

enum THERM_MODE

the current thermal mode modes used for active/passive cooling mode and for the devices' temperature state Enumerator: OK  ACTIVE  PASSIVE  HOT  CRITICAL

---

Function Documentation

int calcCPULoad (  const int  consider_nice  )

calculate cpu load Parameters: consider_nice  give a nice value Returns: "Idleness" of the processor in percent since the last time this function has been called Return values: UNKNOWN  if not supported if you poll idleness of processor, ignore the result of the first time you invoke this function, because it will be the total idleness of cpu since the machine has been powered on

int checkACPI (  void   )

determine whether there is apm, acpi or nothing on your Computer Returns: integer values representing acpi status Return values: ISACPI

void freeCPULoadData (  void   )

free data for calculating cpu time needs to be invoked, once the getCPULoad function is called to free memory. The getCPULoad may be called multiple times, when not using the func anymore call this one

int getACAdapterStatus (  void   )

returns if the machine is on ac power or not apm + acpi Returns: < 0 on error Return values: NO_MODULE_ERROR  NO_DEVICE_ERROR  AC_ADAPTER_STATE

int getBatteriesInfo (  BatteryGeneral *  bat  )

fills the given Battery struct with the current battery information for all found batteries supports acpi and apm Parameters: bat  pointer to a BatteryGeneral struct Returns: integer with result of call Return values: 0  on success <  0 on error

int getBatteryDetailedInfo (  const int  no, BatteryDetailed *  bd )

use this method to get amount of batteries in the system ACPI only! Parameters: no  battery number bd  pointer to detailed battery info structure Returns: : integer with result of call Return values: 0  SUCCESS <  0 ERROR -1  general error -2  if device no does not exist -3  if struct has not initialized with memory NO_ACPI_ERROR  if it is not an ACPI system NO_MODULE_ERROR  if the battery module is not loaded NO_DEVICE_ERROR  if there is a fan directory, but no device >  0 END OF BATTERIES REACHED

int getBatteryInfo (  const int  no, BatteryGeneral *  battery_info )

get Information for only one battery Parameters: no  number of battery to query starting from 0 battery_info  pointer to an BatteryGeneral struct Return values: 1  on success and battery is present 0  on success but battery is not present <  0 on error

int getCPUCount (  void   )

get number of cpus in system Returns: number of cpus, < 0 on error

int getCPULoad (  const int  cpu  )

get current cpu load Parameters: cpu  the cpu to use starting at 0 Returns: the current cpu load

int getFanNum (  void   )

get number of fans in the system ACPI only! Returns: number of devices, < 0 on error

int getFanStatus (  const int  device_num  )

get fan status Parameters: device_num  Returns: integer with result of get fan status Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  NO_DEVICE_ERROR  0  if fan is on -1  if fan is off -3  if fan device no. num does not exist -4  if state file does not exist -5  if state could not be figured out (probably changes in kernel syntax)

int getLidState (  void   )

returns the current state of the lid Returns: LID_STATE

float getRealProcessorSpeed (  void   )

get processor speed be careful this method waits a second ... Function only available on i686 and x86_64 machines! Returns: current processor speed Return values: -1.0  if sleep is interrupted, result will be wrong -2.0  if compiled for a not supported architecture -3.0  if /proc/cpuinfo is not accessable and supported for architecture could not be evaluated

int64_t getSupportedSleepStates (  void   )

get all supported sleeping states mask out return value to evaluate supported states Return values: 0  if no support

int getThermalZone (  const int  zone, ThermalDev *  td )

get a thermal zone ACPI only! Parameters: zone  value from 0-n zones td  ThermalDev Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -3  if thermal device no. num does not exist -4  if td is not allocated

int getThermalZonesNum (  void   )

get the number of thermal zones ACPI only! Returns: < 0 on error

int getThermalZoneState (  int  zone  )

get thermal zone state ACPI only! Parameters: zone  value from 0-n zones Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -3  general error (too long file name or similar) -1  if thermal_zone zone does not exist

int getThermalZoneTemp (  const int  zone  )

get thermal zone temp ACPI only! Parameters: zone  value from 0-n zones Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -3  general error (too long file name or similar) -1  if thermal_zone zone does not exist

int getThrottlingInfo (  int *  num_states, int *  current_state )

get throttling information (ACPI only) ACPI only! Parameters: num_states  will be filled with number of states current_state  will be filled with current state Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -1  on general error

int getThrottlingInfoCPU (  const int  cpu, int *  num_states, int *  current_state )

get throttling info for one single cpu ACPI only! Parameters: cpu  number of cpu starting with 0 num_states  integer where number of states will be stored current_state  integer where current state will be stored Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -2  if cpu does not exist -3  on general error

int numBatteries (  void   )

get number of present batteries Returns: number batteries (also not present ones) or -1 on error

int setBatteryAlarm (  const int  percent  )

sets the ACPI battery alarm for all batteries ACPI only!

int setCoolingMode (  const int  device_num, const int  mode )

set cooling mode Parameters: device_num  the device number mode  the cooling mode Returns: integer value repesenting result of call func Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -1  general error -> could not be set -2  if cooling_mode is not supported -3  if thermal device no. num does not exist

void setDebugLevel (  const int  dbg  )

set the debug level. Values: 0-31 if library is compiled without -DPOWERSAVE_DEBUG variable this method has no effect. Define -D USE_SYSLOG to use the syslog daemon for debugging sum up the levels you want to see: e.g.: 7 -> error + warning + diag levels: 0 = nothing 1 = error 2 = warning 4 = diag 8 = info 16= debug Parameters: dbg  the debug level

int setThermalTrippoints (  const int  zone, const ThermalDev  td )

set thermal trippoints ACPI only! Parameters: zone  value from 0-n zones td  ThermalDev Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -3  if thermal device no. num does not exist

int setThrottlingPercent (  const int  percent  )

set throttling percent ACPI only! Parameters: percent  percent value to which should be throttled Returns: < 0 on error

int setThrottlingPercentCPU (  const int  cpu, const int  percent )

set throttling percent for single cpu ACPI only! Parameters: cpu  number of cpu starting with 0 percent  percent value to which should be throttled Returns: < 0 on error

int setThrottlingStateCPU (  const int  cpu, const int  state )

set throttling state on cpu ACPI only! Parameters: cpu  number of cpu starting with 0 state  state to set Returns: < 0 on error Return values: NO_ACPI_ERROR  NO_MODULE_ERROR  -3  on general error

---