12 Powersave DBus specification

Namespace: com.novell.powersave

Interfaces:

1. com.novell.powersave.manager
2. com.novell.powersave.request
3. com.novell.powersave.action

12.1 The Manager Interface

The Manager interface is connection oriented Interface. Clients have to connect (and send their capabilities) to the daemon.

12.1.1 Initial Connection by a Client at the Powersave Daemon

• Interface: com.novell.powersave.manager
• Member : "Connect"
• Type : Method call with return

-> client connection (message "connect" with the capabilities which can be handle by the connecting client).

-> return type: boolean (TRUE on successful connection, else: FALSE)

-> powersaved has to store the D-BUS sender string (e.g. ":1.5") of the "connect" message. Using this information gives the +possibility to track clients whether they died unexpectedly.

Depending on the amount of capabilities the client has, the daemon now knows

• what events and messages should be sent to the client.
• what he can request from the client
• what will be processed by the clients (e.g. screensaver capablities, ...)

D-BUS Example:

signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=connect

0 int32 "3"

11 corresponds to the capabilities CAPABILITY_NOTIFICATIONS and CAPABILITY_SCREENLOCK

• #define CAPABILITY_NOTIFICATIONS 1
• #define CAPABILITY_SCREENLOCK 2
• #define CAPABILITY_BRIGHTNESS 4

12.1.2 Disconnect by a Client

• Interface: com.novell.powersave.manager
• Member : "Disconnect"
• Type : Signal

D-BUS Example:

signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=disconnect

-> According to the sender of the disconnect signal, the powersave daemon knows which capabilities are no longer available.

12.1.3 Events triggerd by the Powersave Daemon

Acpi events from /proc/acpi/events

• Interface: com.novell.powersave.manager
• Member : "AcpiEvent"
• Type : Signal

Powersave events

• Interface: com.novell.powersave.manager
• Member : "PowersaveEvent"
• Type : Signal

Possible events:

• "acadapter.offline"
• "acadapter.online"
• "button.sleep"
• "button.power"
• "button.lid.open"
• "button.lid.closed"
• "temperature.ok"
• "temperature.active"
• "temperature.passive"
• "temperature.hot"
• "temperature.critical"
• "battery.normal"
• "battery.warning"
• "battery.low"
• "battery.critical"
• "battery.info" (something changed -> remaining percent/time should be reread)
• "global.suspend2disk" (daemon has been asked to suspend and will do so now)
• "global.suspend2ram"
• "global.standby"
• "global.resume.suspend2disk" (we are back from suspend)
• "global.resume.suspend2ram"
• "global.resume.standby"
• "processor.performance" (The cpufreq policy changed to performance)
• "processor.powersave"
• "processor.dynamic"
• "processor.busy" (The processor is not idle anymore)
• "processor.idle" (The processor was idle for the last x seconds (by default 10))
• "processor.notify" (Not sure now)
• "daemon.start"
• "daemon.terminate"
• "daemon.scheme.change" (scheme has been switched -> reread schemes or other info that could have changed)
• "other" (Not sure now)

Daemon or script progress (e.g. 'unloading modules 40%)

• Interface: com.novell.powersave.manager
• Member : "Progress"
• Type : Signal

Return types:

• 0 string : Progress description (e.g. "unloading modules...")
• 1 int32 : Progress (e.g. "10")

Simple messages, error messages or notifications

• Interface: com.novell.powersave.manager
• Member : "Notification"
• Type : Signal

D-BUS Example:

signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=acpi_event 0 string "button.power"

-> according to its capabilities, the client has to set up matches in his filter function for the corresponding events triggered by the daemon.

When an event occurs the clients may want to use the Request interface to reread specific values (e.g. request "rem_charg_time_battery" after a event "battery.info", or request "schemes" after a event "daemon.scheme.changed"

12.2 IV. Client Requests (Client -(request)-> Daemon -(response)-> Client)

(Interface: com.novell.powersave.request)

-> All requests do not have any parameters.

Get all Powersave schemes

• Interface: com.novell.powersave.request
• Member : "SchemesGet"
• Type : Method call with return

Return types:

• 0 string : array containing all available schemes
• 1 uint8_t: index of current active scheme (use order of sent string array)
• 2 uint8_t: index of battery scheme (use order of sent string array)
• 3 uint8_t: index of AC scheme (use order of sent string array)

Get a specific scheme description

• Interface: com.novell.powersave.request
• Member : "SchemesGetDescription"
• Type : Method call with return

Param:

• 0 string : string has to match a scheme name.

Return types:

• 0 string : the requested scheme description

Cpu frequency policy

• Interface: com.novell.powersave.request
• Member : "CpufreqPolicy"
• Type : Method call with return

Return type:

• 0 string : ("dynamic", "performance", "powersave")

Battery status

• Interface: com.novell.powersave.request
• Member : "BatteryState"
• Type : Method call with return

Return type:

• 0 string : ("critical", "low", "warning", "normal", "no battery")

Ac adapter power

• Interface: com.novell.powersave.request
• Member : "AcPower"
• Type : Method call with return

Return type:

• 0 string : "on", "off", "unknown"

If suspend to ram is allowed

• Interface: com.novell.powersave.request
• Member : "AllowedSuspendToRam"
• Type : Method call with return

Return type:

• 0 boolean

If suspend to disk is allowed

• Interface: com.novell.powersave.request
• Member : "AllowedSuspendToDisk"
• Type : Method call with return

Return type:

• 0 boolean

If standby is allowed

• Interface: com.novell.powersave.request
• Member : "AllowedStandby"
• Type : Method call with return

Return type:

• 0 boolean

Get current brightness level

• Interface: com.novell.powersave.request
• Member : "BrightnessGet"
• Type : Method call with return

Return type:

• 0 int : the current brightness level

Get current brightness in percent

• Interface: com.novell.powersave.request
• Member : "BrightnessGetPercent"
• Type : Method call with return

Return type:

• 0 int : the current brightness level in percent

Get available brightness levels

• Interface: com.novell.powersave.request
• Member : "BrightnessLevelsGet"
• Type : Method call with return

Return type:

• 0 int : value containing the maximum brightness level

Query list of device classes for runtime power management

• Interface: com.novell.powersave.request
• Member : "DpmClassesGet"
• Type : Method call with return

Return type:

• 0 string : array containing all available classes

Query list of devices for a specific device class

• Interface: com.novell.powersave.request
• Member : "DpmDevicesGet"
• Type : Method call with return

Param:

• 0 string : string has to match a class name. classes names can be requested (see above)

Return type:

• 0 string : array containing all available classes

12.3 Daemon Actions (Client -(action)-> Daemon)

(Interface: com.novell.powersave.action)

Check whether daemon is up and replies

• Interface: com.novell.powersave.action
• Member : "Ping"
• Type : Method call with return

Set machine into suspend to disk mode

• Interface: com.novell.powersave.action
• Member : "SuspendToDisk"
• Type : Method call with return

Set machine into suspend to ram mode

• Interface: com.novell.powersave.action
• Member : "SuspendToRam"
• Type : Method call with return

Set machine into standby mode

• Interface: com.novell.powersave.action
• Member : "Standby"
• Type : Method call with return

Set cpu policy to performance

• Interface: com.novell.powersave.action
• Member : "CpufreqPerformance"
• Type : Method call with return

Set cpu policy to powersave

• Interface: com.novell.powersave.action
• Member : "CpufreqPowersave"
• Type : Method call with return

Set cpu policy to dynamic

• Interface: com.novell.powersave.action
• Member : "CpufreqDynamic"
• Type : Method call with return

Enabled a single CPU

• Interface: com.novell.powersave.action
• Member : "CpufreqCPUEnable"
• Type : Method call with return

Param:

• 0 int : the CPU number to enable starting from 0

Disable a single CPU

• Interface: com.novell.powersave.action
• Member : "CpufreqCPUDisable"
• Type : Method call with return

Param:

• 0 int : the CPU number to disable starting from 0. CPU 0 can't be disabled ATM because it runs the main timer

Set a powersave scheme

• Interface: com.novell.powersave.action
• Member : "SchemesSet"
• Type : Method call with return

Param:

• 0 string : string has to match a scheme name. scheme names can be requested (see above)

Set brightness level

• Interface: com.novell.powersave.action
• Member : "BrightnessSet"
• Type : Method call with return

Param:

• 0 int : the brightness level to set

Set brightness level given in percent

• Interface: com.novell.powersave.action
• Member : "BrightnessSetPercent"
• Type : Method call with return

Param:

• 0 int : the brightness level to set in percent

Set brightness to minimum

• Interface: com.novell.powersave.action
• Member : "BrightnessMin"
• Type : Method call with return

Set brightness to medium

• Interface: com.novell.powersave.action
• Member : "BrightnessMed"
• Type : Method call with return

Set brightness to maximum

• Interface: com.novell.powersave.action
• Member : "BrightnessMax"
• Type : Method call with return

Increase brightness

• Interface: com.novell.powersave.action
• Member : "BrightnessUp"
• Type : Method call with return

Decrease brightness

• Interface: com.novell.powersave.action
• Member : "BrightnessDown"
• Type : Method call with return

Set a devices into powersave mode

• Interface: com.novell.powersave.action
• Member : "DpmDevicesSuspend"
• Type : Method call with return

Param:

• 0 int : the device number to suspend. If not provided, -1 is taken which is the default

Resume a devices from powersave mode

• Interface: com.novell.powersave.action
• Member : "DpmDevicesResume"
• Type : Method call with return

Param:

• 0 int : the device number to resume. If not provided, -1 is taken which is the default

Notify connected clients of any progress going on

12.4 Return Messages

All calls to the bus get a return/error message replied.

Return messages include following types:

• 0 uint_16 : Error ID
• 0 string : Error message

The error ids can be found in powersave_dbus.h as defines.

12.4.1 If no error occured the return message includes (normal message):

• 0 Error ID : REPLY_SUCCESS
• 1 Error message : "success"

If an error happens the message will be an error reply (as specified by dbus). Following errors can be checked for all method calls/signals:

General Error

• 0 Error ID : REPLY_GENERAL_ERROR
• 1 Error message : "general error"

No connection Error (The daemon is probably not running)

• 0 Error ID : REPLY_CONNECTION
• 1 Error message : "no connection"

No rights Error (The client is not allowed to speak with the daemon)

• 0 Error ID : REPLY_NO_RIGHTS
• 1 Error message : "no rights"

Invalid Paramet (The client sent bullshit)

• 0 Error ID : REPLY_INVALID_PARAM
• 1 Error message : "invalid param"

Following request/actions may return specialised errors:

12.4.2 Specialised Error Replies

Following errors may occur on some actions/requests and must be checked by the client if such a action/request is made:

1. Not supported (by HW):
   • 0 : REPLY_HW_NOT_SUPPORTED
   • 1 : "not supported"

   Interface: com.novell.powersave.action

   • Member : "SuspendToDisk"
   • Member : "SuspendToRam"
   • Member : "Standby"
   • Member : "CpufreqPerformance"
   • Member : "CpufreqPowersave"
   • Member : "CpufreqDynamic"
2. Disabled by administrator:
   • 0 : REPLY_DISABLED
   • 1 : "disabled"

   Interface: com.novell.powersave.action

   • Member : "SuspendToDisk"
   • Member : "SuspendToRam"
   • Member : "Standby"
3. Already set
   • 0 : REPLY_ALREADY_SET
   • 1 : "already set"

   Interface: com.novell.powersave.action

   • Member : "CpufreqPerformance"
   • Member : "CpufreqPowersave"
   • Member : "CpufreqDynamic"
4. Does not exist
   • 0 : REPLY_INVALID_METHOD
   • 1 : "does not exist"

   Interface: com.novell.powersave.action

   • Member : "SchemesSet"