diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/Makefile.am | 13 | ||||
| -rw-r--r-- | src/org.freedesktop.DeviceKit.Power.QoS.xml | 341 |
2 files changed, 352 insertions, 2 deletions
diff --git a/src/Makefile.am b/src/Makefile.am index 4d501d7..7d7c2b4 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -26,7 +26,9 @@ DEVKIT_POWER_LIBS = $(top_builddir)/libdevkit-power/libdevkit-power.la BUILT_SOURCES = \ dkp-daemon-glue.h \ dkp-device-glue.h \ - dkp-marshal.h dkp-marshal.c + dkp-qos-glue.h \ + dkp-marshal.h \ + dkp-marshal.c dkp-marshal.h: dkp-marshal.list glib-genmarshal $< --prefix=dkp_marshal --header > $@ @@ -40,10 +42,16 @@ dkp-daemon-glue.h: org.freedesktop.DeviceKit.Power.xml Makefile.am dkp-device-glue.h: org.freedesktop.DeviceKit.Power.Device.xml Makefile.am dbus-binding-tool --prefix=dkp_device --mode=glib-server --output=dkp-device-glue.h org.freedesktop.DeviceKit.Power.Device.xml +dkp-qos-glue.h: org.freedesktop.DeviceKit.Power.QoS.xml Makefile.am + dbus-binding-tool --prefix=dkp_qos --mode=glib-server --output=dkp-qos-glue.h org.freedesktop.DeviceKit.Power.QoS.xml + libexec_PROGRAMS = devkit-power-daemon dbusifdir = $(datadir)/dbus-1/interfaces -dbusif_DATA = org.freedesktop.DeviceKit.Power.xml org.freedesktop.DeviceKit.Power.Device.xml +dbusif_DATA = \ + org.freedesktop.DeviceKit.Power.xml \ + org.freedesktop.DeviceKit.Power.Device.xml \ + org.freedesktop.DeviceKit.Power.QoS.xml devkit_power_daemon_SOURCES = \ egg-debug.c \ @@ -103,6 +111,7 @@ CLEANFILES = $(BUILT_SOURCES) EXTRA_DIST = \ org.freedesktop.DeviceKit.Power.xml \ org.freedesktop.DeviceKit.Power.Device.xml \ + org.freedesktop.DeviceKit.Power.QoS.xml \ dkp-marshal.list \ 95-devkit-power-csr.rules \ 95-devkit-power-hid.rules \ diff --git a/src/org.freedesktop.DeviceKit.Power.QoS.xml b/src/org.freedesktop.DeviceKit.Power.QoS.xml new file mode 100644 index 0000000..47341ba --- /dev/null +++ b/src/org.freedesktop.DeviceKit.Power.QoS.xml @@ -0,0 +1,341 @@ +<!DOCTYPE node PUBLIC +"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" +"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd" [ + <!ENTITY ERROR_GENERAL "org.freedesktop.DeviceKit.Power.GeneralError"> +]> +<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> + <interface name="org.freedesktop.DeviceKit.Power.QoS"> + <doc:doc> + <doc:description> + <doc:para> + org.freedesktop.DeviceKit.Power.QoS is a DBus interface implimented + by DeviceKit-power. + It allows applications to request latencies, for example a couple of seconds + for an IM application, or a few hundred microseconds for a multiplayer game. + </doc:para> + <doc:para> + Use cases: + </doc:para> + <doc:itemizedlist> + <doc:listitem> + <doc:para> + I want my IM application to request 0.5s latency for messages. + </doc:para> + <doc:para> + I'm running an OpenGL simulation and want maximum performance, + even when on battery power. + </doc:para> + <doc:para> + I'm running an SQL server for a credit card company, and want the + server to request low latency CPU and network as any delay costs money. + </doc:para> + <doc:para> + I'm an admin, and want to change the power consumption vs. latency + from cron scripts so it uses high latency during the night for + maximum power saving, and low latency during business hours. + </doc:para> + <doc:para> + I want high throughput when copying files, but want low throughput + for downloading updates in the background. + </doc:para> + <doc:para> + I want my power manager to set all latencies to lowest when on + AC power. + </doc:para> + <doc:para> + I don't want my users messing with latency settings. + </doc:para> + <doc:para> + I'm and admin and I want to be able to override all latency + settings on my machines. + </doc:para> + </doc:listitem> + </doc:itemizedlist> + <doc:para> + Why don't applications use the PMQoS interface directly? + By providing a framework we can override requests by policy, and also + control requests from random services. + You also can't set latencies unless you're the root user, which is not + suitable for the desktop use case. + </doc:para> + <doc:para> + Of course, you can do if you really want, but then you loose the + benefits of the query interface and the policy override, + and have to run your application as root. + </doc:para> + </doc:description> + </doc:doc> + + <!-- ************************************************************ --> + <method name="SetMinimumLatency"> + <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> + <arg name="type" direction="in" type="s"> + <doc:doc> + <doc:summary> + The type of latency to control, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:summary> + </doc:doc> + </arg> + <arg name="value" direction="in" type="i"> + <doc:doc> + <doc:summary> + The value, in microseconds or kilobits per second. + The value <doc:tt>-1</doc:tt> means unset and the default is used. + </doc:summary> + </doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Set the minimum acceptable latency of the system. + Setting this value tells the system to not attempt latencies below this setting. + This may be useful in a data center or server room, when you want to override the + latency requests from applications. + This may be required if the server room is operating outside a standard thermal + or power envelope, and an override is required. + You do not have to use this method during normal operation. + </doc:para> + </doc:description> + <doc:permission>Callers need the <doc:tt>org.freedesktop.devicekit.power.latency.set-minimum-latency</doc:tt> authorization</doc:permission> + <doc:errors> + <doc:error name="&ERROR_GENERAL;">if an error occured while setting the latency</doc:error> + </doc:errors> + </doc:doc> + </method> + + <!-- ************************************************************ --> + <method name="RequestLatency"> + <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> + <arg name="type" direction="in" type="s"> + <doc:doc> + <doc:summary> + The type of latency to control, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:summary> + </doc:doc> + </arg> + <arg name="value" direction="in" type="i"> + <doc:doc> + <doc:summary> + The value, in microseconds or kilobits per second. + The value <doc:tt>-1</doc:tt> means remove all latency requirements. + </doc:summary> + </doc:doc> + </arg> + <arg name="persistent" direction="in" type="b"> + <doc:doc> + <doc:summary> + If the latency request outlives the connection. + When the application issuing the request disconnects from the system + bus, the latency request is automatically cleaned up. + By setting this flag to TRUE, the request is not cleaned up when + the client disconnects, and the cookie is preserved acress reboots. + </doc:summary> + </doc:doc> + </arg> + <arg name="cookie" direction="out" type="u"> + <doc:doc> + <doc:summary> + A cookie that identifies the request. This allows an application or + service to request multiple latency settings from one process, and for + other processes to cancel requests. + </doc:summary> + </doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Set the required latency of an application or service. + </doc:para> + </doc:description> + <doc:permission> + Callers need the + <doc:tt>org.freedesktop.devicekit.power.latency.request-latency-persistent</doc:tt> + authorization if <doc:tt>persistent</doc:tt> is TRUE, or + <doc:tt>org.freedesktop.devicekit.power.latency.request-latency</doc:tt> otherwise. + </doc:permission> + <doc:errors> + <doc:error name="&ERROR_GENERAL;">if an error occured while setting the latency</doc:error> + </doc:errors> + </doc:doc> + </method> + + <!-- ************************************************************ --> + <method name="CancelRequest"> + <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> + <arg name="type" direction="in" type="s"> + <doc:doc> + <doc:summary> + The type of latency to control, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:summary> + </doc:doc> + </arg> + <arg name="cookie" direction="in" type="u"> + <doc:doc> + <doc:summary> + A cookie that identifies the request. This allows an application or + serivice to request multiple latency settings from one process. + </doc:summary> + </doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Cancel the latency request from the application or service. + </doc:para> + </doc:description> + <doc:permission> + Callers need the + <doc:tt>org.freedesktop.devicekit.power.latency.cancel-request</doc:tt> + authorization if they were not the one issuing the request. + </doc:permission> + <doc:errors> + <doc:error name="&ERROR_GENERAL;">if an error occured while clearing the latency</doc:error> + </doc:errors> + </doc:doc> + </method> + + <!-- ************************************************************ --> + <method name="GetLatency"> + <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> + <arg name="type" direction="in" type="s"> + <doc:doc> + <doc:summary> + The type of latency to return, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:summary> + </doc:doc> + </arg> + <arg name="value" direction="out" type="i"> + <doc:doc> + <doc:summary> + The value, in microseconds or kilobits per second. + The value <doc:tt>-1</doc:tt> means not set or unavailable. + </doc:summary> + </doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Get the lowest latency state on the system at the current time. + </doc:para> + </doc:description> + <doc:errors> + <doc:error name="&ERROR_GENERAL;">if an error occured while getting the latency</doc:error> + </doc:errors> + </doc:doc> + </method> + + <!-- ************************************************************ --> + <signal name="LatencyChanged"> + <arg name="type" direction="out" type="s"> + <doc:doc> + <doc:summary> + The type of latency that changed, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:summary> + </doc:doc> + </arg> + <arg name="value" direction="out" type="i"> + <doc:doc> + <doc:summary> + The value, in microseconds or kilobits per second. + The value <doc:tt>-1</doc:tt> means not set or unavailable. + </doc:summary> + </doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Some latency value has changed. + </doc:para> + </doc:description> + </doc:doc> + </signal> + + <!-- ************************************************************ --> + <method name="GetLatencyRequests"> + <arg name="requests" direction="out" type="a(uuusxbssi)"> + <doc:doc> + <doc:summary> + The request lists, where each application can request different + latency types. + <doc:list> + <doc:item> + <doc:term>cookie</doc:term> + <doc:definition> + The random cookie that identifies the request. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>uid</doc:term> + <doc:definition> + The user ID that issued the request. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>pid</doc:term> + <doc:definition> + The process ID of the application. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>exec</doc:term> + <doc:definition> + The executable that issued the request. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>timespec</doc:term> + <doc:definition> + The number of seconds since the epoch. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>persistent</doc:term> + <doc:definition> + If the request is persistent and outlives the connection lifetime. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>type</doc:term> + <doc:definition> + The type of the request, <doc:tt>cpu_dma</doc:tt> or + <doc:tt>network</doc:tt>. + </doc:definition> + </doc:item> + <doc:item> + <doc:term>value</doc:term> + <doc:definition> + The value, in microseconds or kilobits per second. + <doc:tt>discharging</doc:tt>. + </doc:definition> + </doc:item> + </doc:list> + </doc:summary></doc:doc> + </arg> + <doc:doc> + <doc:description> + <doc:para> + Gets all the system requests from all services and applications. + </doc:para> + </doc:description> + </doc:doc> + </method> + + <!-- ************************************************************ --> + <signal name="RequestsChanged"> + <doc:doc> + <doc:description> + <doc:para> + The latency requests on the system have changed. + </doc:para> + </doc:description> + </doc:doc> + </signal> + + </interface> + +</node> |